Teach HSCT to download sources from git
[harbours.git] / README.rst
blobbfa787293f0396634602a2be8b08732745b1be50
1 HelenOS coastline: build POSIX applications for HelenOS
2 =======================================================
4 This repository contains scripts that should simplify porting POSIX
5 applications to run in `HelenOS <http://www.helenos.org>`_.
6 The motivation for this mini-project is that porting GNU/POSIX applications
7 to HelenOS is mostly about setting correctly the CFLAGS when running
8 ``./configure`` and then copying the generated executables somewhere to
9 ``uspace/dist``.
10 The idea is that this procedure would be recorded in a form of a simple shell
11 script, called harbour (because it is a port).
12 The wrapper script ``hsct.sh`` then takes care of downloading the necessary
13 sources and running the user-defined commands from respective ``HARBOUR`` file.
15 The whole idea is highly inspired by
16 `makepkg <https://wiki.archlinux.org/index.php/Makepkg>`_.
19 **WARNING**: some information here is obsoleted.
20 I will try to update it as soon as possible.
22 Using the coastline
23 -------------------
24 First, clone this repository somewhere on your disk.
25 The examples below would assume ``~/helenos/coast``.
27 Next, prepare the directory where the actual building of the POSIX
28 applications would happen.
29 It is recommended to do this outside HelenOS source tree and outside of the
30 coast-line sources.
31 ``~/helenos/coast-builds/ia32`` is a good choice if you plan to build for
32 ``ia32`` configuration.
34 Next, you obviously need check-out of HelenOS sources.
35 In the following examples, I would assume ``~/helenos/mainline``.
37 To use the coastline, go into the ``~/helenos/coast-builds/ia32`` and
38 issue the following command::
40         ~/helenos/coast/hsct.sh init ~/helenos/mainline ia32 build
42 This command would initialize the build directory and forcefully rebuild
43 HelenOS to the defaults of ``ia32`` configuration.
44 Once this command finishes, you can freely play inside ``~/helenos/mainline``
45 as all the necessary files are already cached in the build directory.
47 Now you can build some software.
48 Just choose one (for example, ``msim``) and run::
50         ~/helenos/coast/hsct.sh build msim
52 It may take a while but it shall eventually produce the simulator binary.
53 If you want to copy it to your HelenOS source tree, run::
55         ~/helenos/coast/hsct.sh install msim
56         
57 If you want to transfer the built files to another machine etc, you may
58 want to run::
60         ~/helenos/coast/hsct.sh archive msim
61         
62 that produces a TAR.XZ file in ``archives`` that you can directly unpack
63 into the ``uspace/overlay`` directory.
65 If you have a multicore machine, you may try setting the variable
66 ``parallel`` in ``hsct.conf`` inside your build directory to a higher
67 value to allow parallel builds.
72 Writing your own HARBOUR files
73 ------------------------------
74 The ``HARBOUR`` file is actually a shell script fragment.
75 The coastline script ``hsct.sh`` expects to find some variables and functions
76 declared in it.
77 These variables declare URLs of the source tarballs or versions while the
78 functions actually build (or install) the application/library/whatever.
80 Each ``HARBOUR`` is supposed to be in a separate directory.
81 This directory is placed together with the ``hsct.sh`` script.
83 The commands in individual functions are expected to use special
84 variables prepared by the wrapper script that would contain information
85 about selected compiler (i.e. full path to GCC) or flags for the compiler
86 to use.
87 These variables are prefixed with ``HSCT_`` followed by the name commonly
88 used in ``Makefile``\s or in ``configure`` scripts
89 (e.g. ``HSCT_CC`` contains path to the C compiler).
91 However, usually it is not possible to write the ``HARBOUR`` file directly:
92 for example various arguments to ``./configure`` scripts have to be tried
93 or extra ``CFLAGS`` might be necessary.
95 For testing, you can use the ``helenos/env.sh`` script and source it.
96 This script sets all the variables that you can use in the HARBOUR script.
98 Follows a shortened list of variables available.
100 - ``$HSCT_CC``: C compiler to use.
101 - ``$HSCT_CFLAGS``: C flags to use.
102 - ``$HSCT_LD``: linker to use.
103 - ``$HSCT_LDFLAGS``: linker flags
104 - ``$HSCT_LDFLAGS_FOR_CC``: linker flags preceded by ``-Wl,``.
105   This is extremely useful when linker is not called explicitly and compiler
106   is used for linking as well.
107   Some of the flags would be recognized during the compilation phase so
108   marking them as linker-specific effectively hides them.
109 - ``$HSCT_GNU_TARGET``: Target for which the application is being built.
110   Typically this is the value for the ``--target`` option of the ``configure``
111   script.
112 - ``$HSCT_INCLUDE_DIR``: Points to directory for header files.
113   This directory is shared by all packages.
114 - ``$HSCT_LIB_DIR``: Points to directory for libraries.
115 - ``$HSCT_MY_DIR``: Points to installation directory.
116   All files that shall appear in HelenOS must be copied here.
117   The structure of this directory shall mirror the HelenOS one
118   (i.e. the ``app/`` and ``inc/`` directories).
120 For example, the ``./configure`` script for `libgmp <http://gmplib.org/>`_
121 uses the following variables::
123         run ./configure \
124                 --disable-shared \
125                 --host="$HSCT_GNU_TARGET" \
126                 CC="$HSCT_CC" \
127                 CFLAGS="$HSCT_CFLAGS $HSCT_LDFLAGS_FOR_CC <more flags>" \
128                 LD="$HSCT_LD"
130 Once you know the command sequence that leads to a successful built you
131 should record this sequence into the ``HARBOUR`` file.
132 The easiest way is to take an existing one and just change it for the
133 particular application.
135 The variable ``shipname`` declares the package (application or library)
136 name and shall be the same as the directory the ``HARBOUR`` is part of.
138 The variable ``shipsources`` contains space separated list of tarballs
139 or other files that needs to be downloaded.
140 Obviously, you can use ``$shipname`` inside as shell does the expansion.
141 To simplify updating of the packages, it is a good practice to have
142 variable ``$shipversion`` containing the application version and use this
143 variable inside ``$shipsources``.
144 If you need to reference a local file (a patch for example),
145 just write a bare name there.
146 The files are downloaded with ``wget`` so make sure the protocol used
147 and the path format is supported by this tool.
148 Git repositories to clone can be specified with the syntax
149 ``git:localdir:[revision]:url`` where ``localdir`` is the name of the
150 local directory to which the repository is cloned. ``revision`` is the
151 revision to check out and ``url`` is the URL of the git repository.
153 The variable ``shiptugs`` declares packages this one depends on
154 (the twisted fun is here that tugs are required for the ship to actually
155 leave the harbour).
156 That is a string with space separated list of other ships.
158 For building is used a ``build()`` function.
159 The function is expected to complete the following tasks:
161 - unpack the tarballs
162 - configure the application or somehow prepare it for building
163 - actually build it
165 If you want to print an informative message to the screen, it is recommended
166 to use ``msg()`` function as it would make the message more visible.
168 To simplify debugging it is recommended to run commands prefixed with
169 function named ``run``.
170 That way the actual command is first printed to the screen and then
171 executed.
173 Below is an example from ``libgmp`` that illustrates a typical
174 ``build()`` function::
176         # Manually extract the files
177         run tar xjf "${shipname_}-${shipversion}.tar.bz2"
178         
179         # HelenOS-specific patches are needed
180         msg "Patching gmp.h..."
181         patch -p0 <gmp-h.patch
182         
183         # Run the configure script, notice the extra C flags
184         cd "${shipname_}-${shipversion}"
185         run ./configure \
186                 --disable-shared \
187                 --host="$HSCT_GNU_TARGET" \
188                 CC="$HSCT_CC" \
189                 CFLAGS="$HSCT_CFLAGS $HSCT_LDFLAGS_FOR_CC -D_STDIO_H -DHAVE_STRCHR -Wl,--undefined=longjmp" \
190                 LD="$HSCT_LD" \
191                 || return 1
192         
193         # The variable $shipfunnels reflects maximum parallelism allowed
194         # by the HARBOUR and by the current build directory
195         msg "Building the library..."
196         run make -j$shipfunnels
197         
198         # Tests are built and run as one target so this target always fails
199         # We check that the tests were built by explicitly checking for
200         # them below.
201         msg "Building the tests..."
202         run make check || true
203         (
204                 cd tests
205                 # Check that all tests were built
206                 find t-bswap t-constants t-count_zeros t-gmpmax t-hightomask \
207                         t-modlinv t-popc t-parity t-sub
208                 exit $?
209         )
211 After the application is built, it can be either archived or copied to
212 HelenOS source tree.
213 Both these actions requires that the application is *packaged* first.
215 The function ``package()`` is expected to copy the necessary files outside
216 of the build directory into ``$HSCT_MY_DIR``.
217 If there are some headers or libraries used by other packages, they should
218 be copied into ``$HSCT_INCLUDE_DIR`` and ``$HSCT_LIB_DIR``.
220 Directories ``$HSCT_INCLUDE_DIR`` and ``$HSCT_LIB_DIR`` behave as standard
221 Unix-like ``/usr/include`` and ``/usr/lib`` directories, while ``$HSCT_MY_DIR``
222 mirros the HelenOS directory ``uspace/dist`` structure.
223 Contents of ``$HSCT_MY_DIR`` is copied to ``uspace/overlay`` during
224 installation or tarred when archived.
226 Below is an excerpt from ``zlib`` ``package()`` function.
227 Notice the usage of the variables and the ``run()`` function::
229         cd "${shipname}-${shipversion}"
230         run make install DESTDIR=$PWD/PKG
231         
232         # Copy the headers and static library
233         run cp PKG/usr/local/include/zlib.h PKG/usr/local/include/zconf.h "$HSCT_INCLUDE_DIR/"
234         run cp PKG/usr/local/lib/libz.a "$HSCT_LIB_DIR/"
235         
236         run mkdir -p "$HSCT_MY_DIR/inc/c"
237         run cp PKG/usr/local/include/zlib.h PKG/usr/local/include/zconf.h "$HSCT_MY_DIR/inc/c"
238         
239         run mkdir -p "$HSCT_MY_DIR/lib"
240         run cp PKG/usr/local/lib/libz.a "$HSCT_MY_DIR/lib"