Autosetup/jam

This is autosetup/jam, a simple Jam-based build system as an autosetup plugin.

Installation

After installing autosetup, copy lib/* to a (new) directory in your project autosetup/jam/

Note: autosetup v0.6.5 or later is required

Project Setup

From your project, run:

./configure --init=jam

This will create an initial auto.def, auto.jam and Jamrules file.

Now edit auto.def as required and supply a top-level Jamfile specifying the build targets.

If you are migrating from a make-based setup, do not forget to use jam in your auto.def and invoke make-jam-stub and make-jam-config instead of make-template.

Building

You must have FT-Jam http://www.freetype.org/jam/ installed in order to use the build system. The classic Perforce Jam has bugs in its built-in rules that make it unsuitable for use with autosetup/jam, and lacks shared library support.

To build, run:

./configure jam

Out-of-tree builds can be performed by running the configure script inside the desired build directory.

Configuration files

• Jamfile: the main build script for Jam. Refer to the original Jam documentation at http://www.perforce.com/documentation/jam for information on writing these. Autosetup/jam requires that you declare the top build directory of your project using a SubDir TOP ; line in the topmost Jamfile. In order to support out-of-tree builds, the configuration script must create a stub Jamfile in the build directory by calling make-jam-stub.

• Jamrules: the Jamrules file as created by autosetup --install contains the code to locate and source the Jamconfig file that contains the rules and imported variables from autosetup. This file can be created from auto.def by calling make-jam-config Jamconfig. It can also be created manually, if needed; the only requirement is that it sets a variable called JAMCONFIGURED to a non-empty value.

• auto.jam: An optional auto.jam file can be used to factor out local autosetup-specific customizations, in case you want your project to be buildable without autosetup (e.g. under Windows with MS Visual C++). If present, it will be sourced after all other autosetup-specific scripts.

• autosetup/jam/*.jam: Each autosetup module can have a corresponding Jam support file that defines or modifies stock rules in order to use the configuration information. The modules used by auto.def by the time make-jam-config is executed will have their support files sourced during the build.

All Jam files encountered during configuration are scanned for comments of the form

# AutoSetup : jamVar?=autoVar? ?...?

Each entry specifies that the given autosetup variable should be imported into Jam (by default, the variables are assumed to have the same name on both sides). Jam scripts can assume that the specified variables will be imported by the time the script is run, but the execution order is not otherwise restricted.

Jam rules

The support files provided in the autosetup/jam distribution performs several modifications of the stock Jambase.

• New rule: AutoGen files (in jam.jam)

  Specifies that the files are generated by autosetup inside the build directory and should be removed during a distclean.

• New target: distclean (in jam.jam)

  In addition to a running a regular clean, removes all configuration-related files.

• New target: reconfig (in jam.jam)

  Runs distclean and then re-runs configure with the same options that were used previously. Uses a rule called ReConfig to achieve the behaviour.

• New variable: $(BUILD_TOP) (in jam.jam)

  Refers to the top build directory correctly during out-of-tree or subdirectory builds.

• Modified variables: $(CC), $(C++) etc. (in cc.jam and cc-lib.jam)

  Compilation tools specified in the Jambase that were detected by cc-check-progs are imported into Jam. Various configuration settings and flags are also set using information from autosetup.

• Modified rules: SharedObjects, SharedLibraryFromObjects, LinkSharedLibraries (in cc-shared.jam)

  Shared library rules as specified in the FT-Jam Jambase are modified by the cc-shared module to take advantage of the configuration information. Versioned shared libraries are created according to $(VERSION) value on the target if the host system uses them.

Copyright

All files in autosetup/jam are copyright (C) 2012 Alexander Shpilkin, and are provided under the same terms as autosetup itself (see LICENSE in the autosetup distribution).