Setup:Main

Building from source

People who are already setup for cross-compiling Genode from a Linux host should not need much time or effort to build HoG from source (building from Haiku is also possible but takes a little more planning). Indeed the build basically consists of compiling Genode Labs's latest and greatest, using its native build system ; and building this project's shared library and image, using a one-step build system based on Jam.

Toolchain

The below assumes that you are setup with the Genode toolchain, i.e. that you have retrieved the Genode-specific build of GCC. If not, head to the Toolchain page.

Out of the box, HoG is configured to be built with the Genode 23.05 toolchain (gcc12). The previous Genode 21.05 toolchain (gcc10) can also be used, by tweaking the GccToolChain and VersionLibGCC Jamrules variables mentionned below in the "configuring HoG build" section.

Build system

The first part of the build relies on gmake. The second part relies on Perforce Jam. Using the haiku variant of Jam is highly recommended, as the more well known variants (FTjam, Boost jam...) tend to crash or misbehave when dealing with our build scripts. See the directions at bottom of page to build Jam from source (i.e. a quick painless download followed by a quick compilation).

Abbreviated build instructions

If you already have fossil, jam etc installed, the whole build process can be relatively compact. For instance, if your intended target is "hog-demos", you just need (part of) the below.

Download the Genode sources -- as of this writing you'll need rev 24.02 -- and build the needed subset of Genode components:

git clone https://github.com/genodelabs/genode.git
#git clone https://github.com/genodelabs/genode-world.git genode/repos/world  # if you need libfuse & libntfs-3g
cd genode
git checkout -b 24.02 24.02
# now is the time to apply the patches listed below, if you want them to be part of the build
./tool/create_builddir x86_64
nano build/x86_64/etc/build.conf  # enable -j4 and most extra repos
# you might need only a (left-most) subset of these:
./tool/ports/prepare_port nova grub2 x86emu stb ttf-bitstream-vera jpeg libc stdcxx  zlib libav ntfs-3g lwip dde_bsd dde_linux acpica
# for "jam hog-demos.emu6" basic scenario:
make -C build/x86_64  KERNEL=nova  BOARD=pc  kernel core/nova lib/ld init
make -C build/x86_64  KERNEL=nova  BOARD=pc  timer drivers/rtc server/wm app/window_layouter app/decorator app/nano3d app/top
make -C build/x86_64  KERNEL=nova  BOARD=pc  drivers/framebuffer/vesa drivers/acpi drivers/platform app/pci_decode drivers/ps2   app/pointer app/status_bar
make -C build/x86_64  KERNEL=nova  BOARD=pc  app/global_keys_handler server/nitpicker app/nit_focus server/event_filter server/rom_filter   server/report_rom
make -C build/x86_64  KERNEL=nova  BOARD=pc  lib/posix lib/libm lib/vfs lib/stdcxx lib/libc
make -C build/x86_64  KERNEL=nova  BOARD=pc  server/black_hole drivers/ahci server/part_block
# for "jam t7" or even "jam distro" more complex scenarios:
# make -C build/x86_64  KERNEL=nova  BOARD=pc  drivers/usb_host drivers/usb_hid  # or download a pre-built binary of usb_host if it won't build : https://depot.genode.org/genodelabs/bin/x86_64/pc_usb_host_drv/2023-10-24.tar.xz
# make -C build/x86_64  KERNEL=nova  BOARD=pc  lib/zlib lib/vfs_pipe lib/vfs_ttf lib/jpeg lib/vfs_lxip  lib/avfilter lib/avformat lib/avresample lib/swscale lib/avcodec lib/avutil
# make -C build/x86_64  KERNEL=nova  BOARD=pc  server/nic_router drivers/nic lib/lwip lib/vfs_lwip  # if drivers/nic won't build, download  https://depot.genode.org/genodelabs/bin/x86_64/pc_nic_drv/2023-10-25.tar.xz
# make -C build/x86_64  KERNEL=nova  BOARD=pc  app/acpica server/vfs server/terminal server/terminal_log  server/mixer drivers/audio
  

Download the HoG sources, build haiku.lib.so, the demos, and create the bootable ISO:

cd ..
mkdir hog && cd hog  # otherwise fossil might complain/require the folder to be 'empty' before opening the repo
fossil clone http://chiselapp.com/user/ttcoder/repository/genode-haiku/  genode-haiku.fossil
fossil open genode-haiku.fossil  # if you don't have fossil installed, clone/open might be replaced with this download link: http://chiselapp.com/user/ttcoder/repository/genode-haiku/zip
cd genode-haiku/
export GenodeRepos=$PWD/../../genode/repos
# if you want a bootable USB image with a whole system (here: a 'basic' system with a few demo apps):
jam -j4 -q hog-demos.emu6
# if you just want to build haiku.lib.so and an app (here: DeskCalc) for e.g. integration into an unpatched SculptOS system:
GE_XATTR_DISABLED=1  GE_DECORATIONS_AND_WM=1  jam -q -j4 DeskCalc

If something goes wrong, or you intend to build a non-default ISO, you might have to dig through the (somewhat outdated) extended instructions below.

Extended build instructions

1 - Sources retrieval

First, retrieve a compatible version of Genode.

git clone https://github.com/genodelabs/genode.git
cd genode
git checkout -b x.y x.y

Alternatively, you may pick the latest SculptOS-compatible branch:

git checkout -b sculpt-21.03 sculpt-21.03

In that case you might need to edit jam/jamrules-pkg-versions after cloning the HoG sources from fossil (in the next step), to select appropriate pkg/lib dependancies (e.g. instead of stdcxx for 21.05, select stdcxx for 20.11 whose hash starts with "80f380...").

Then retrieve the HoG sources from this repository. They can be downloaded as a 2+ MB zip file from the zip archiver URL, or you may install fossil (i.e. : apt-get fossil) and use it to clone this repository:

cd ..  # e.g. side-by-side with the github.com Genode repository
fossil clone http://chiselapp.com/user/ttcoder/repository/genode-haiku/  genode-haiku.fossil
fossil open genode-haiku.fossil
cd genode-haiku/
nano Jamrules

The last step mentionned up here is for editing Jamrules (see below).

The build is done with Jam, a super sweet alternative to gmake. If you don't have jam out of the box (e.g. on Linux ?) make sure to install it. It's probably best to install the ftjam variant, since on Ubuntu 20.x the vanilla "jam" package seems to be broken.

If you intend to only build haiku.lib.so (to e.g. create a "genode/contrib/" SculptOS package) then you might be able to take a shortcut and skip the rest of this page : if your Genode build directory already contains the binaries matching your checked-out Genode version, you're about done and just need to invoke this:

jam haiku.lib.so

(possibly with "-j4" to speed up the build). Then lift the library file from within the haiku-on-genode/system/ folder. However, if you intend to build a full bootable system, or if you're missing some of the Genode libraries that haiku.lib.so needs to link against (ld.lib.so, vfs.lib.so, ldso_so_support.lib.a), you'll need to build part or all of the Genode components mentionned below.

2 - Genode build (for full-blown HoG O.S.)

The below assumes that you have the Genode SDK to compile against, or even (to build HoG O.S.) the full Genode source code, ready to build. If in doubt, follow the official Genode build instructions, e.g. here.

HoG expects to find Genode libraries and components in certain hardcoded subpaths of the Genode build dir, especially within bin/. Hence, rather than use tool/depot/download, the following steps are recommended instead :

./tool/create_builddir x86_64
nano build/x86_64/etc/build.conf  # enable -j4, and most extra repos except maybe for genode-world
./tool/ports/prepare_port nova
./tool/ports/prepare_port grub2
./tool/ports/prepare_port x86emu
./tool/ports/prepare_port stb
./tool/ports/prepare_port ttf-bitstream-vera
./tool/ports/prepare_port jpeg
./tool/ports/prepare_port libc
./tool/ports/prepare_port stdcxx
make -C build/x86_64  KERNEL=nova  BOARD=pc  kernel core/nova lib/ld/nova
# for the USB and Audio drivers:
./tool/ports/prepare_port dde_linux
./tool/ports/prepare_port dde_bsd
make -C build/x86_64  KERNEL=nova  run/libc_select  # automagically builds more components, esp. those needed by HoG like vfs.lib.so
make -C build/x86_64  KERNEL=nova  drivers/rtc
make -C build/x86_64  KERNEL=nova  drivers/audio server/mixer
# for mp3 etc decoding:
./tool/depot/download cnuke/bin/x86_64/libav/2019-11-23
./tool/depot/download cnuke/bin/x86_64/zlib/2019-11-18
make -C build/x86_64  KERNEL=nova  drivers/usb

If you do build for NOVA x64 bits and follow the above steps, the steps in the next section should go smoothly as Jam will be able to locate the Genode files it needs, including those presented in the following list, and some optional extras (audio_drv, libav, etc) and match them with HoG and successfully create an ISO boot image:

3 - Configuring the HoG build

In theory you'll only need to configure one variable, namely GenodeRepos. See below for the more complex cases.

That variable (and the others) can be configured by one of three methods. Choose the one most convenient for you:

By setting an environ variable:

export GenodeRepos=/home/john/develop/genode/repos
jam haiku.lib.so

By passing the variable to jam with the -s switch:

jam -s GenodeRepos=/home/john/develop/genode/repos haiku.lib.so

Or by editing the "Jamrules" file:

nano Jamrules  # look for the "GenodeRepos=..." definition and edit it
jam haiku.lib.so

4 - HoG build (full-blown standalone HoG O.S.)

We may now build haiku.lib.so and package it in a runnable/"stand-alone" ISO image. In this case, we are building from the HoG source tree, pulling in Genode binaries to us and emulating (parts of) the Genode build system, so things are a little more involved.

Before compiling you'll need to edit the Jamrules file (at the top of the file hierarchy) to configure the correct path values for the GenodeRepos variable, and maybe also for GenodeBuild and GccToolChain. Alternatively, these variables can be set in the bash environment, or provided as command-line arguments with the "-s" switch, e.g. "jam -s GenodeRepos=/home/john.smith/develop/genode/repos".

Then run jam with the "t1" target, which will compile and run a simple "test level 1" scenario:

jam t1

If the stars are aligned, that should create an .iso file and emulate it in qemu. You may then try a more complex test (up to t6) or even the "Haiku demos" scenario:

jam hog-demos.run

Type "jam help" for help.

Beyond the basics (optional)

Using Jam to compile the full-bore Haiku library (t6 mode) takes a few minutes. You can speed it up by building with four threads with the -j4 switch, e.g. "jam -j4 t6".

If you are curious about what you are about to embark on, first do a dry-run with the -n switch, e.g. "jam -n t1", which will dump the (possibly huge) list of calls to gcc et al to be performed.

Patching Genode (optional)

It's recommended you tweak Genode in places, for improved Haiku support in the "stand-alone OS" build scenario:

XAttr support: patch Genode's libc/vfs plug-in

HoG declares (with "extern C...") a dependancy on a custom function that needs to be added to vfs.lib.so ; if absent, linking will fail. You could do away with the dependancy (comment out the corresponding HoG code) if you have no use for extended attributes, though the patch is simple enough to apply:
diff --git a/repos/libports/lib/symbols/libc b/repos/libports/lib/symbols/libc
index e3de45d2d..95a088bdf 100644
--- a/repos/libports/lib/symbols/libc
+++ b/repos/libports/lib/symbols/libc
@@ -485,6 +485,7 @@ opterr D 4
 optind D 4
 optopt B 4
 optreset B 4
+path_for_genode_fd T
 pathconf W
 pause W
 pclose T
diff --git a/repos/libports/src/lib/libc/vfs_plugin.cc b/repos/libports/src/lib/libc/vfs_plugin.cc
index 89db7eab7..14805cab2 100644
--- a/repos/libports/src/lib/libc/vfs_plugin.cc
+++ b/repos/libports/src/lib/libc/vfs_plugin.cc
@@ -224,6 +224,26 @@ namespace Libc {
+#if 1  // HoG_GENODE
+//
+// Small-footprint 'private' accessor, which hai-on-genode uses to look-up fd's
+// (file descriptors) paths, without using ioctl(). This way, no need to patch ioctl() itself.
+//
+extern "C" int path_for_genode_fd( int fd, Genode::String<1024> & into )
+{
+       using namespace Libc;
+
+       File_descriptor *fdesc = file_descriptor_allocator()->find_by_libc_fd(fd);
+       if (fdesc == 0)
+               return ENOTSUP;
+
+       into = fdesc->fd_path;
+
+       return 0;
+}
+#endif  // ~HoG_GENODE

Reliable audio playback: patch Genode's dde_bsd/driver

The audio-out driver tends to "go to sleep" sometimes, with our usage patterns. Commenting out this 'return' statement fixes the issue for us:
diff --git a/repos/dde_bsd/src/drivers/audio/main.cc b/repos/dde_bsd/src/drivers/audio/main.cc
index c16e791b19..aba1a81423 100644
--- a/repos/dde_bsd/src/drivers/audio/main.cc
+++ b/repos/dde_bsd/src/drivers/audio/main.cc
@@ -142,7 +142,7 @@ class Audio_out::Out
                         } else {
                                _play_silence();
-                               return;
+///                            return;
                        }
                         _advance_position(p_left, p_right);
  

Building Jam from source (recommended)

Unfortunately the jam landscape is fragmented into several jam variants which are not fully compatible with each other (think of it as linux distros *g*). Thus it might be useful to build the same "Be Jam" variant we use, instead of installing one of the more well-known but different dialects (FTJam, Boost-jam, or the -- promising -- Ham). This should allow you to run "jam t1" instead of "jam hog-test.run", and avoid some stack/memory corruption issues seen with FTJam.

The following script should build the exact same version of Jam used by the HoG project:

mkdir build_jam && cd build_jam
wget  --execute robots=off  --recursive --no-parent --no-directories  https://git.haiku-os.org/buildtools/plain/jam/
# chmod a+x yyacc  # ?
make
#
# you'll probably need something like this to use the newly built jam:
# export "PATH=$(PWD):$PATH"