dominicm00 / ham

A meaty Jam build tool replacement

Ham - WIP {#index}

Disclaimer

This repository holds Ham v1, based on Ingo Weinhold's original work, and is in maintenance mode. Bug fixes and quality-of-life changes are still being merged, but new features are not being added.

Development is currently underway on Ham v2, which is a heavily rewritten version with better parsing, exact header scanning, improved incremental builds, and more. You can check it out here.

Issues building Haiku

There are currently bugs in Haiku's build system (at least #17965) that are preventing Ham from being used with Haiku. Validation on other projects is ongoing, and any bugs in Ham itself should be reported.

Documentation

Most available documentation is for Ham v2; although not all of it is applicable to Ham v1, the language specification is still a good resource. For strictly Ham v1 compatible documentation, check out the Perforce Jam docs.

Introduction

Ham is a drop-in replacement for the Jam build system. Its primary goal is to be compatible with and extend Haiku Jam, and eventually become Haiku's official build system. However, compatibility with Perforce Jam, Boost.Build, and possibly other variants are planned.

Motivation

While Jam is a great build system, its legacy codebase makes it difficult to fix bugs or introduce new features. Ham uses a modern, friendly C++ codebase, and is rigorously tested. Ham also has more robust multithreading support, and is written as a library for IDE integration:

Usage

To run Ham in compatibility mode, use the -c/--compat flag. For instance, you can define jam with an alias:

alias jam='ham --compat'

While in compatibility mode, Ham will attempt to respect the command line parameters and features of the chosen tool. For convenience, Ham provides aliases for many commands. A compatibility matrix is provided below:

Key: X=implemented, P=planned, N/A=not applicable

Flags	Description	ham	jam	ham --compat
-a	build all	P	X	P
-dX	debug info	P1	X	P
-fX	select ruleset	P	X	P
-g	new sources first	P	X	P
-jX	run actions concurrently	P	X2	P
-n	dry run	P	X	P
-oX	output commands to file	P	X	P
-q	quit on build failure	P	X	P
-sX=Y	set variable	P	X	P
-tX	rebuild target	P	X	P

Info about the Jam language can be found in the Perforce documentation and the (archived) Gentoo tutorial.

Building Ham

Ham is built using Autotools. Currently, no distribution tarballs are available, so Ham must be built from the repository source code.

To build Ham from this repository, the following dependencies are required:

• Autoconf
• Automake
• Libtool
• A C++ compiler with support for C++20

To build Ham from the repository source code, initialize the Automake system and then run the standard ./configure && make.

autoreconf --install
./configure
# Add -jN (where N is the number of parallel CPUs on your system) for faster builds
make

You can then run make install to install Ham on your system.

Contributing

To contribute to Ham, you'll need:

• clang-format v14 or above

Before submitting a pull request, make sure to run the format.sh script.

Footnotes

1. Debug information/levels may differ from Jam. ↩

2. jam's implementation of concurrent actions has known bugs. ↩