IntroductionWhile 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 distThe 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: - From calling a get_version() function defined in the toplevel wscript file of the project, or,
- 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: - Scripting.g_dist_exts is a list of file extensions to exclude;
- Scripting.g_excludes is a list of folders to exclude;
- 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 distcheckBefore 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 distcleanThe 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 distIf 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)
|
Sign in to add a comment
Alternative DistTarball? API.
Obtain a tarball object: tarball = DistTarball?(APPNAME, VERSION, compression_type='gz')
To generate digests: tarball.digest(crypto_service=sha1,md5) => '12a3cfe..'
The tarball is an instance of a file object: isinstance(tarball, file) => True print tarball.name