Introduction

While developers usually work with a revision controlled tree, it is often necessary to make release archives (usually called "tarballs") containing a snapshot of the project, with only the files reqired to build it and nothing else. WAF provides a framework to make generating these tarballs relatively painless.

waf dist

The command waf dist generates a project tarball, usually a file named something like myproject-0.0.1.tar.bz2.

The version string ("0.0.1" in our example) is obtained in one of the following ways:

1. From calling a get_version() function defined in the toplevel wscript file of the project, or,
2. From a VERSION variable defined in the toplevel wscript file of the project.

Normally waf dist creates a tarball with the full contents of the source tree, excluding the build directory and a few well known file extensions, such as backup files (ending in ~).

WAF offers two mechanisms to allow you to customise what is added to the release tarball:

1. Scripting.g_dist_exts is a list of file extensions to exclude;
2. Scripting.g_excludes is a list of folders to exclude;
3. If the toplevel wscript file defines a function called dist_hook() with no arguments, it is called after creating the distdir (i.e. directory that will be the contents of the generated archive), but before creating the archive itself. WAF changes the current directory to the distdir before calling dist_hook, thereby allowing the dist_hook function to easily remove files or add new ones, before the archive is created.

waf distcheck

Before releasing a project tarball to the world, it might be a good idea to check that the generated tarball builds correctly. The command waf distcheck automates this testing process; it basically creates a distdir and then runs the following commands inside it:

  waf configure --prefix instdir && waf build && waf check && waf install && waf uninstall

Where instdir is a temporary directory created to test installation. If any of the steps fails, WAF issues an error. If in the end the temporary directory created to test installation is not removed by waf uninstall then it means the project manually installed a file that it forgot to remove afterwards, in which case waf distcheck notifies of this problem.

waf distclean

The command waf distclean simply removes the build directory with everything in it. It can be used to start a new build from scratch, for example when changing to a new architecture.

extending waf dist

If a dist method is provided, it will replace the default Scripting.Dist, for example, it can be used to print the md5sum of the file generated and change the compression system:

def dist():
        # set the compression type to gzip (default is bz2)
        import Scripting
        Scripting.g_gz = 'gz'

        # after making the package, print the md5sum
        import md5, sys
        from Scripting import DistTarball
        (f, filename) = DistTarball(APPNAME, VERSION)
        f = file(filename,'rb')
        m = md5.md5()
        readBytes = 1024 # read 1024 bytes per time
        while (readBytes):
                readString = f.read(readBytes)
                m.update(readString)
                readBytes = len(readString)
        f.close()
        print filename, m.hexdigest()
        sys.exit(0)