Autobuild/How To
Autobuild is a framework for maintaining and building projects and managing dependencies among them. This page is a tutorial introduction to basic use of Autobuild. For an overview, see Autobuild.
Using Autobuild to build a project
This section discusses how to configure Autobuild to build a source package. It assumes you have a source distribution and a working build system like make or cmake.
Before you start
Build for your platform(s)
Autobuild is not a build system like make or cmake. It is not intended to solve the nitty-gritty problem of building code on particular platforms; it is designed to provide a common interface for builds and packaging on top of platform-specific tools.
For each library or application you want to manage with Autobuild you need a build (and possibly configure) command for every platform you support. For example, typical Linux packages use makefiles and are built by calling the make command. On Windows you may call devenv.com passing a project file as an argument. In subsequent sections you will learn how to configure Autobuild so it can run your platform configuration and build commands.
Creating a new configuration
The following steps create an autobuild configuration (conventionally autobuild.xml) for your project. That configuration describes the project output, each of the projects dependencies (also referred to as installables), and the platform specific steps required to configure and build the project.
Change directories to the root of your package (or wherever you would like the configuration file to live) and enter this command:
autobuild edit package
This starts an interactive session in which you may fill in the general package details. You must provide a name and the location of a file (relative to the build directory) of a file that will contain the project version number at the comletion of the build. If your project is intended to produce an archive package for use as an installable in other projects, you will also want to specify a license and license file. We will ignore the other fields for now. As an alternative to the interactive session, you may add or change package fields all from the command line by passing field=value arguments on the command line. For all edit commands, the interactive mode will be used when no attribute arguments are passed and the non-interactive mode otherwise. For example to create our configuration file non-interactively, use the following command to create the test package version 1.0 using an MIT license:
autobuild edit package name=test license=MIT license_file=LICENSES/test.txt version_file=VERSION.txt
Configuring platform builds
Now that you have defined basic attributes for the package you need to configure the platforms on which to build the library. At this level you can really only configure the build directory because you may define multiple build configurations (see below). The build directory is the directory in which Autobuild will run the build and configure commands and is presumed to be where any build product will be generated. You can, for example, configure the MacOS X platform with the command:
autobuild edit platform name=darwin build_directory=build
Note that for relative paths, the root is always the location of the autobuild configuration file.
Now you need to add a build configuration which includes the build and configure commands which autobuild will invoke to make the package. Assuming you are dealing with a UNIX style package, you typically just call configure and make from the root directory to make the package. You can define the Release configuration to do just that using the commands:
autobuild edit configure platform=darwin name=Release command=../configure autobuild edit build platform=darwin name=Release command=make options='--directory=..' default=True
You must run these commands in the build directory, so you must the path or add an option as appropriate to work select the root directory. The configure and build commands may take three attributes: command, arguments, and options. These are concatenated to produce the actual command invoked in the shell. The build configuration also supports the default option which flags a build configuration to be build by default if no configuration is specified when the autobuild build command is invoked. You may repeat these steps for other build configurations like Debug with different make and configure options to, for example, build a debug version of the library. You now have enough autobuild configuration to build a simple package for the Darwin platform. Simply run this command to configure and make the package:
autobuild build
Building on multiple platforms
To support other platforms you need only repeat the package, config, and build configuration steps for each platform.
In some cases you may find that different platforms share common command, arguments, or options. For example, a library configured by the cross-platform cmake tool may use the same configuration command on all platforms. In that case you can define the special platform common to define the commonalities. Attributes from build configurations in the common platform are inherited by those for the working platform.
If a command is defined for a platform for a build configuration like Release for both a working platform like darwin that platform will inherit from common. This means that if the arguments or command are not specified in the working platform build configuration for either the build or configure command, then the value from the common will be used. Conversely, if the arguments or command attribute is defined in the working platform, it will supersede what is specified in common. However, the options for the commands from common will be concatenated with those specified in the working platform configuration with the common options preceding the working. Specifying a common platform can allow you to specify commands once per build configuration enabling a single point of truth for cross platform tools.
Adding dependencies
If your package depends on other archives produced by autobuild in other projects, you can instruct autobuild to download and install those archives. First you will need to provide information in the autobuild configuration to identify and locate any package dependencies. You can add a package description of the installable archive using the installables command like the following
autobuild installables add GL url=http://s3.amazonaws.com/viewer-source-downloads/install_pkgs/GL-darwin-20101004.tar.bz2 hash=0b7c1d43dc2b39301fef6c05948fb826
This creates a new entry in the installables dictionary that includes the information needed to download and verify the GL package for the darwin platform. You can add downloads for other platforms using the installables edit command
autobuild installables edit GL platform=windows
url=http://s3.amazonaws.com/viewer-source-downloads/install_pkgs/GL-windows-20101001a.tar.bz2 hash=a94538d064cd0a235b2a95389e7e8ee8
Once a package has been added to the installables configuration for the platform you are working on, you can download and install it using the Autobuild install command
autobuild install GL
The package contents will be downloaded and extracted into the packages directory inside the build directory configured for the working platform. Autobuild will conveniently track which packages are installed and what files were extracted only installing or updating files as needed. If you no longer need a package, uninstall it with the command
autobuild uninstall GL
If you update a package by changing its configuration in the installables configuration, Autobuild will automatically clean up the older version so typically you will not need to uninstall packages.
Using Autobuild to construct an archive
Constructing the manifest and packaging
Autobuild has the ability to construct a compressed tar archives with the autobuild package command, but to do that you must tell Autobuild what to include in the archive. Typically you will be packaging an archive of build product generated by the Autobuild build command, but that is not a requirement. Minimally you will need an Autobuild configuration with the name, license, license_file, and copyright attributes set and a platform configuration for the platform for which you wish to build and archive. You may then use the Autobuild manifest command to add files which should be included in the archive. For example, this command adds the pattern 'include/*.h' to the manifest for the platform you are currently running (use the -p option to select another platform).
autobuild manifest add 'include/*.h'
Autobuild supports simple glob patterns, so this pattern instructs autobuild to add all .h header files in the include directory to the archive. The root directory for all paths is assumed to be the build directory configured for the platform. Use only relative paths in your manifest. Additional files may be added by calling manifest add again as needed (note that the add instruction can accept more than one pattern argument). Note that license file will automatically be included in the archive even if it is not explicitly listed in the manifest. If a file is to be included in every archive regardless of platform, you may add it to the manifest of the common platform.
Once you have added all the files required by the archive listed in the manifest, you can generate the archive using the command:
autobuild package
This command will generate an archive in the directory containing the Autobuild configuration file. Unless set using the --archive-name option, the archive will be named using the convention <name>-<version>-<platform>-<buildid>.tar.bz2, e.g. test-1.0-darwin-201010201423.tar.bz2 for the package described in this tutorial.
Laying out build product
Autobuild places no constraints on the layout of build product bundled into an archive, but there are some recommended conventions. The following table shows the recommended directory under which to place files of different types.
| File type | Directory |
|---|---|
| license | LICENSES |
| header | include |
| libraries | lib |
| executables | bin |
| scripts | scripts |
For more details, see Autobuild/Package_Layout. Follow these conventions to help package users easily configure their build systems to find your files. For types not listed here, install files following well-known conventions.