Changes between Version 3 and Version 4 of PortingSoftware

Timestamp:

2014-03-16T18:21:44Z (10 years ago)

Author:

Vojtech Horky

Comment:

A bit more about using coastline

PortingSoftware

@@ -45 +45 @@
 Currently, Coastline is hosted as a separate Git [https://github.com/vhotspur/coastline repository on GitHub].
 
-TODO:
+Coastline is a set of scripts that allows the developer porting software to HelenOS capture the porting process in a reasonable way.
+The porting is captured as a shell script that runs the `configure` and other commands needed to build the ported software.
+Apart from this it also prepares variables that contains proper path to HelenOS include directories or libraries.
+Use of Coastline means that the porting process is reproducible and it also allows to factor our common routines.
 
- * principles
-   * extracting the flags
-   * caching built libraries
-   * harbours
- * usage
- * writing harbour files
+When the developer uses the Coastline, he is working with 3 directories.
+The first one is the directory with Coastline checkout, in the scripts referred to as `HSCT_HOME`.
+Second one is the build directory where the building happens.
+And the last one is directory with HelenOS sources (`HSCT_HELENOS_ROOT`).
+
+The build directory needs to be initialized first.
+During initialization, headers and libraries from HelenOS source tree are copied to the build directory and used compiler/linker flags are extracted and prepared for further use.
+These are stored in the `helenos/` subdirectory.
+A shell script `helenos/env.sh` contains settings of various paths and also the flags for the compiler and the linker.
+To initialize the build directory, you need to call
+
+{{{
+$HSCT_HOME/hsct.sh init /path/to/HelenOS/source/tree
+}}}
+
+If you specify a profile (e.g. `ia32`) as a third argument, the initialization would prepare the build directory for that profile.
+Specifying the word `build` as a last (fourth) argument would force a complete rebuild for the specified profile.
+
+Once the directory is initialized, the user can build the ported software.
+The build is invoked by calling `hsct.sh` in the following manner:
+
+{{{
+hsct.sh build <package>
+}}}
+
+
+This would download the tarballs, unpack them and run `configure` and `make` (or alternatives) for the given software.
+
+Once the build is complete, the user can either package the software into a tarball or directly copy the application to HelenOS source tree.
+Running
+
+{{{
+hsct.sh install <package>
+}}}
+
+would copy the application (library) to HelenOS source tree that was specified during initialization.
+Executing
+
+{{{
+hsct.sh archive <package>
+}}}
+
+would create a tarball in `archives/` subdirectory.
+Unpacking this tarball into `uspace/overlay` would effectively install the package.
+
+
+If you do not want to rebuild the software yourself, you can download [http://helenos.alisma.cz/coastline/matrix/ pre-built packages].
+Please note that these packages are not 100% up-to-date with mainline and sometimes may not work or may work only partially.
+
+
+=== Porting new software ===
+
+ * harbour files
+   * `$shipname`, `$shipsources` and `$shiptugs`
+   * `build()` and `package()` functions
+ * common issues
+   * forcing cross-compilation
+   * naming clashes