= Porting Software to HelenOS =

This page shall contain a brief guide for porting software (e.g. from GNU/Linux) to HelenOS.
Currently, it only contains assorted links to existing resources.


== Links ==

 * [BinutilsMaintenance Maintenance instructions for binutils]
 * [http://vh.alisma.cz/blog/2013/01/24/towards-gcc-for-helenos Blog] [http://vh.alisma.cz/blog/2013/01/27/towards-gcc-for-helenos-2-libgmp posts] [http://vh.alisma.cz/blog/2013/02/13/towards-gcc-for-helenos-3-libmpfr about] [http://vh.alisma.cz/blog/2013/11/06/gcc-for-helenos-sitrep GCC] [http://vh.alisma.cz/blog/2013/11/07/gcc-for-helenos-todo porting]
 * [https://github.com/vhotspur/coastline Coastline] - scripts for porting POSIX-like software to HelenOS (and some [http://vh.alisma.cz/blog/2013/03/30/introducing-helenos-coastline blog] [http://vh.alisma.cz/blog/2013/12/08/helenos-coastline-updates-status-matrix posts])
 * Python porting: [https://github.com/zhalas/helenos-build-python repository] and [http://lists.modry.cz/private/helenos-devel/2013-April/006421.html ML announcement]

== POSIX emulation layer ==

HelenOS is not [wiki:DiffFromUnix another Unix-like OS] and thus it needs an emulation for applications that were written for Unix systems.
This emulation is currently in HelenOS provided by `libposix` library that provides implementation of functions that are part of POSIX standard but were considered inappropriate for HelenOS.

`libposix` provides an (incomplete) illusion that the application has access to standard POSIX headers and functions.
The ported application is then linked with `libposix` which translates the calls to HelenOS specific implementations in `libc`.

//Implementation detail//: some of the functions in `libc` have the same name as standard POSIX ones or they offer slightly different behaviour.
To prevent naming clashes, symbols in `libc.a` are renamed to avoid the need to rename the POSIX versions (which was an older approach where renaming was done during preprocessing, however this approach has various disadvantages).



== General approach ==

For most (reasonable) GNU/Linux programs, we can assume that they are distributed with a `./configure` script.
The purpose of this script is to check the environment and prepare `Makefile`s needed for actual compilation.
In order to build the application for HelenOS we "only" need to persuade the `configure` script to cross-compile it and use HelenOS specific compiler flags and link with `libposix`.


Although this seems as a simple task because `configure` offers parameters/variables for exactly this, there are several obstacles.

 * HelenOS currently uses Linux ABI and thus the cross-compiler used gives the impression that the target is GNU/Linux system. This could lead to some false expectations.
 * There is a lot of compiler/linker flags that are passed. The amount itself obscures a reasonable editing of the command line.
 * HelenOS works mostly with static libraries. When linking with static libraries, their order is important and they typically need to come after object files for proper linking. That is not always possible to specify with plain `LDFLAGS` or `CFLAGS` settings.

The above means that either patching or some build scripts is sometimes necessary or that the invocation line for `configure` is rather complex (or both).
To simplify the above and, foremost, to allow repeatable builds, the so called Coastline was created.

== Coastline ==


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.

Coastline is hosted as a Bazaar repository that can be [source:coastline browsed on-line].
To clone the repository, issue the following command:

{{{
brz branch bzr://helenos.org/coastline
}}}

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 following text assumes that following variables point to different directories where you have check-out of the Coastline and HelenOS mainline and also a build directory.

{{{
HSCT_HOME=~/helenos/coastline
HSCT_HELENOS_ROOT=~/helenos/mainline
BUILD_DIR=~/helenos/coast-build-ia32
}}}

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

{{{
cd $BUILD_DIR
$HSCT_HOME/hsct.sh init $HSCT_HELENOS_ROOT
}}}

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.
To avoid surprises from non-standard configuration, the recommended practice is to always forcefully rebuild the profile when initializing the directory:

{{{
cd $BUILD_DIR
$HSCT_HOME/hsct.sh init $HSCT_HELENOS_ROOT ia32 build
}}}

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_HOME/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_HOME/hsct.sh install <package>
}}}

would copy the application (library) to HelenOS source tree that was specified during initialization.
Executing

{{{
$HSCT_HOME/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