Autobuild/Quick Start

When creating a new autobuild package of a library, it can be unclear where to start. Autobuild How To can be a little intimidating. We're packaging a simple third party library just like all the rest of ours, so we don't need to use autobuild in it's full generality. We can skip some steps and share script fragments with other library packages.

Autobuild is largely self documenting. You can access help via the commands autobuild --help or autobuild <subcommand> --help, for example autobuild edit --help. If the help text is unclear, please file a bug.

Here's a crash course:

What will we be doing

Your packaging efforts will mostly consist of creating or modifying 2 files: autobuild.xml, and build-cmd.sh

autobuild.xml

Autobuild package definition metadata. For now, what you should focus on "This specifies the actual shell commands that autobuild should execute for each step." You should modify this file using the 'autobuild edit' command. Editing it by hand will lead to problems.

build-cmd.sh

the shell script that we are going to specify as the build command in autobuild.xml we've encapsulated a lot of the complexity within this script for our third party libraries, so we can just clone it from an existing library and customize it for our package.

What do we do

Get autobuild:

hg clone http://hg.lindenlab.com/brad/autobuild-trunk
cd autobuild-trunk/bin
export PATH="$PATH:$(pwd)"
cd ../..

Copy the skeleton from an existing package.

hg init hello
cd hello
curl -OL http://hg.lindenlab.com/brad/curl-autobuild/raw/tip/BuildParams
curl -OL http://hg.lindenlab.com/brad/curl-autobuild/raw/tip/build.sh
curl -OL http://hg.lindenlab.com/brad/curl-autobuild/raw/tip/build-cmd.sh
chmod +x build.sh build-cmd.sh
curl -OL http://hg.lindenlab.com/brad/curl-autobuild/raw/tip/.hgignore
hg add BuildParams build.sh build-cmd.sh .hgignore

Now you'll need to edit build-cmd.sh and customize it for your package in our case, GNU Hello. Mostly this is just a search and replace (replace occurrences of curl and CURL with the name or your package). For example, the sed search & replace commands would be s/curl/hello/g and s/CURL/HELLO/g in this case. You'll likely also need to update the version number variables to match your package's version.

Additionally you'll need to update the 3 sections under the case statement with any platform specific quirks for how to build your package natively. Darwin and Linux can be pretty standardized, but under windows there are a lot of different ways to build your package. Most of these have been worked through already for one package or another, so talk to a team Chopper member or scan Autobuild/Package Index if you need examples to imitate.

In the end, you should come up with something like this example build-cmd.sh.

Next you'll want to configure autobuild to use your build-cmd.sh.

autobuild edit package
# Name of package> hello
# Package description> The GNU Hello program produces a familiar, friendly greeting. Yes, this is another implementation of the classic program that prints “Hello, world!” when you run it.
# Copyright string (as appropriate for your package)> Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
# Type of license (as appropriate for your package)> gpl3
# Path to license file relative to package root, if known> LICENSES/hello.txt
# Version> 2.6
hg add autobuild.xml
autobuild edit build
# Name of config> default
# Platform of config> common
# Command to execute> ../build-cmd.sh
# Options for command> 
# Arguments for command>
autobuild edit platform name=linux build_directory=stage
autobuild edit platform name=darwin build_directory=stage
autobuild edit platform name=windows build_directory=stage
autobuild edit build name=default platform=linux default=true
autobuild edit build name=default platform=darwin default=true
autobuild edit build name=default platform=windows default=true

Now if you run autobuild print its output should look like this autobuild print example

Next you'll want to configure the manifest for packaging.

autobuild manifest --platform common add "include/hello/*.h"
autobuild manifest --platform common add "LICENSES/hello.txt"
autobuild manifest --platform linux add "lib/*.a"
autobuild manifest --platform darwin add "lib/*.a"
autobuild manifest --platform windows add "lib/debug/*.pdb"
autobuild manifest --platform windows add "lib/debug/*.lib"
autobuild manifest --platform windows add "lib/release/*.pdb"
autobuild manifest --platform windows add "lib/release/*.lib"
autobuild manifest --platform linux add "bin/*"
autobuild manifest --platform darwin add "bin/*"
autobuild manifest --platform windows add "bin/*.exe"

Now if you run autobuild print its output should look like this autobuild manifest example

Now things should be complete (for this simplified example), and you should be able to run autobuild build && autobuild package to get a package generated. Hooray!

hg commit

What did we do

1. We defined a build script that drives the native build of the package in a way that is compatible with our viewer builds and sandboxed from the rest of the system.
2. We configured autobuild to use that build script on all 3 platforms.
3. We packaged the result in a tarball consistent with Autobuild/Package_Layout

What haven't we done

1. We haven't addressed how to handle dependencies. For example libcurl depends upon zlib and openssl already having their autobuild packages availible for use. If you're packaging a new library that has dependencies you should begin at the leaves of the dependency tree.
2. We skipped features of autobuild that aren't useful for the way we're currently packaging third party library packages.
   1. like multiple configurations (Debug/RelWithDebInfo/Release)
   2. like options and arguments to the build command.
   3. like distinct configure and build stages.
3. We haven't covered the specifics of how autobuild integrates with the windows Visual Studio build system.
4. We haven't covered specifically what the ABI requirements are for packages intended to be linked into the viewer.