Using Jam

Haiku uses a custom fork of Perforce's Jam. This mailing list thread helps to explain the decision to fork jam.

As of December 2011, this is the current version. If a different version is reported, then you will need to build and install jam from source.

jam -v
Jam 2.5-haiku-20111222. OS=LINUX. Copyright 1993-2002 Christopher Seiwald.

Building Jam from Source

Haiku's version of jam lives inside the buildtools repository. If you need to, see this page on Getting Haiku Source Code.

cd  /path/haiku/buildtools/jam/
make
<jam-install-command>

<jam-install-command>

To install jam you can use one of two commands:
The first requires administrative privilege, as jam will be installed to '/usr/local/bin/'

  • sudo ./jam0 install
  • ./jam0 -sBINDIR=$HOME/bin install

Note, you may need to use `gmake` instead of `make`

Command Line Options

Only some of the options are being discussed here. See jam -h for a full listing of available options.

  • -q

    Typically jam will attempt to build all targets, even if an error is encountered. '-q' instructs jam to quit immediately upon encountering an error. This is preferred, as it helps to find the actual cause for build failure.

  • -j#

    Where # represents the number of threads to use. This is useful when building on SMP or multi-core machines.

    Jam suffers from a bug that might make your build fail when using this option.
  • -a

    Build all targets, even if they are current. Normally, this is not necessary.
    You may need to do this once in a while because some of the jam rules are not perfect and does not set the dependencies between files properly. The most frequent case is when we update our copy of Freetype : this will prevent anyone to build without the -a switch.
    You can also use this switch if something does not seem to get updated after some change you made. This is the case when you modify a jamfile : Jam does not check for that and will not rebuild things that should be affected by the changes.

  • -sx=y

    Set variable x=y, overriding environment. One example is :

        jam -sHAIKU_IGNORE_USER_BUILD_CONFIG=1 -q @release-raw
    

    This will ensure that the release-* targets are built to the exact specifications of Haiku's DefaultBuildProfiles.

  • -dX

    Enables debug output, where X can be one of the following:

    • (a)actions
    • (c)causes
    • (d)dependencies
    • (m)make tree
    • (x)commands
    • (0-9) debug levels
  • -n

    Don't actually execute the updating actions. This seems to be useful for testing Jamfiles.

Possible Targets

Official Release Targets

The following targets are defined in build/jam/DefaultBuildProfiles

  • @release-raw

    Builds a pre-release image as a raw image. This can be written directly to disk or used with Qemu

  • @release-vmware

    Builds a pre-release image for use with VMWare. This can also be used with VirtualBox.

  • @release-cd

    A single track ISO CD. `mkisofs` is needed to build this.

  • @release-anyboot

    A custom file that can be burned to CD or written directly to disk or used with Qemu.
    It is comprised of an Master Boot Record (MBR), El Torito boot image, and a BFS raw image.
    The MBR occupies the first 512 bytes of the El Torito image, which is usually empty.
    The BFS image is simply concatenated at the end. Inside the MBR is a partition table entry, which maps to the BFS image.

Non-Release Targets

In addition to looking at DefaultBuildProfiles, there is also a way of finding possible targets by looking at the various "NotFile" statements. A "NotFile" statement is usually used to create a build target with a more user-friendly name. Targets such as these should be viewed as a minimal base.

Some Notes

  • sudo jam <options>

    You should not be using the sudo command when running jam.

    First of all, any and all files in $(HAIKU_OUTPUT_DIR)--typically /path/haiku/haiku/generated/ will only be accessible to root. To fix this, it is necessary to run chown -R <user>:<group> <path>. Secondly, user-errors become much more damaging when `sudo jam` is used, as you could easily overwrite the wrong partition.

    The preferred method is to apply permissions to your device first.

    sudo chmod o+r /dev/sda
    sudo chmod o+rw /dev/sda2
    jam -q @walter-sda2
    

    This example uses the Build Profile 'walter-sda2', which is defined on the UserBuildConfig & BuildProfiles page.

    For Linux distributions that make use of udev to maintain /dev, this will only work until you reboot. To allow your user permanent read access to the full disk and write access to the Haiku partition, you need to ask udev to do that for you after every boot. In order to that, create a udev rule file for local changes (for openSUSE, the file could be named '/etc/udev/rules.d/99-local.rules') and add this to it:

    KERNEL=="sda", MODE="0664"
    KERNEL=="sda2", MODE="0666"
    

    In order to activate the changes for the current session, please invoke

    sudo udevadm trigger
  • Cleaning up emulated attributes

    When building Haiku on a filesystem that is not BFS nor uses a sufficient implementation of xattr, the build system will emulate attributes. An attributes/ folder will be created in your generated folder. It will be necessary to manually remove the emulated attributes folder, ideally before each build cycle. Otherwise some issues may occur.

    Note: This assumes your HAIKU_OUTPUT_DIR is generated/!!

    cd /path/haiku/haiku/
    jam clean
    rm -Rf generated/attributes/
    jam <options> <target>
    

Miscellaneous Links