Table of Contents

• Table of Contents
• Introduction
• Installing
• Getting Started
• Tasks
  • Core Tasks
  • Java Tasks
  • Python Tasks
• Filters
• Examples

Introduction

Pyb is a build tool modeled after ant. The primary difference is that pyb is written in Python and all build scripts are also written in Python.

The main goals of Pyb are simplicity (in build scripts and implementation) and clarity of implementation (minimize the magic and limit class explosion).

Pyb requires version 2.3 of Python.

Pyb is currently released under a GPL license.

Installing

To install just add the Pyb directory to your PATH environment variable. This will let you execute Pyb just by typing in 'pyb' on the command line.

Getting Started

The Pyb distribution includes a demo which shows how pyb can be used to build Java project. The first thing to do is to take a look at the pybuild.py file located in the demo directory.

Tasks

Pyb already contains a variety of useful tasks.

Core Tasks

copy

Copy a file or directory to another directory.

delete

Delete a file or directory.

fail

Force a failure of the build script.

tar

Create a TAR from a directory.

untar

Extract a TAR into a directory.

gzip

Create a GZip from a directory.

gunzip

Extract a GZip into a directory.

zip

Create a Zip from a directory.

unzip

Extract a Zip into a directory.

bzip2

Create a BZip2 from a directory.

bunzip2

Extract a BZip2 into a directory.

Java Tasks

java

Execute a Java class file.

javac

Compile all java files in the specified base directory.

javadoc

Generate javadoc documentation.

jar

Generate JAR archives.

unjar

Extract JAR archives.

war

Generate WAR archivces.

unwar

Extract WAR archives.

ear

Generate EAR archivces.

Python Tasks

epydoc

Generate documentation using Epydoc (http://epydoc.sf.net/).

python

Execute a python script.

setup

Execute distutils.setup with the specified setup file.

Filters

Many of the tasks in pyb accept and includeFilters and excludeFilters arguments parameters. The parameters are used to filter file lists using regular expressions. First file lists are passed through the include filters. The result list is then passed through the exclude filters.

There are numerous canned filters in the pyb.filters module. These are standard filters which you can use just by including the variable name in the appropriate filter list.

Example

The following example build.py file is taken directly from the demo which is included with the pyb distribution.

""" Demo build script. """

from pyb import filters
from pyb import tasks
from pyb.tasks import java
from pyb.tasks import py
from pyb.core import *

# variables
src = 'src'
www = 'www'
webxml = 'etc/web.xml'
builddir = 'build'
distdir = 'dist'
tempdir = 'temp'
classes = 'build/classes'
docs = 'build/docs'
jarfile = 'build/test.jar'
warfile = 'build/test.war'
zipfile = 'dist/test.zip'
srczipfile = 'dist/test.src.zip'
tarfile = 'dist/test.tar'
srctarfile = 'dist/test.src.tar'
gzipfile = 'dist/test.tar.gz'
bzip2file = 'dist/test.tar.bz2'
srcgzip = 'dist/test.src.gz'

# targets
def build():
    tasks.java.javac(destdir=classes, basedir=src)

def javadoc():
    tasks.java.javadoc(destdir=docs)

def jar():
    tasks.java.jar(basedir=classes, destfile=jarfile)
    
def war():
    tasks.java.war(basedir=www, destfile=warfile, webxml=webxml)
    
def dist():
    build()
    jar()
    war()
    javadoc()
    
    # zip the source
    tasks.zip(basedir=src, destfile=srczipfile, includeFilters=[filters.java])
    
    # zip the binaries
    tasks.zip(basedir=builddir, destfile=zipfile, includeFilters=[filters.jars])
    tasks.tar(basedir=builddir, destfile=tarfile, includeFilters=[filters.jars])
    tasks.gzip(tarfile, gzipfile)
    tasks.bzip2(tarfile, bzip2file)
    tasks.gunzip(gzipfile, destdir=tempdir)
    tasks.bunzip2(bzip2file, destdir=tempdir)
    tasks.unzip(zipfile, destdir=tempdir + '/zip')
    tasks.untar(tarfile, destdir=tempdir + '/tar')
    
def clean():
    tasks.delete(dir=builddir)
    tasks.delete(dir=distdir)
    tasks.delete(dir=tempdir)
    
def failtest():
    tasks.fail('Something went wrong')
    
def test():
    tasks.copy(basedir='', destdir='copy')
    tasks.py.python(script='test.py')

targets={
    'build':Target(build),
    'javadoc':Target(javadoc),
    'jar':Target(jar),
    'war':Target(war),
    'dist':Target(dist),
    'clean':Target(clean),
    'failtest':Target(failtest),
    'test':Target(test)
}

Project(name='Demo Project', default='build', targets=targets)

The build script above can be broken down into several distinct sections. The first section imports modules which are used in the script. The filters modules contains pre-defined file filters as described in the Filters section of this guide. The tasks package contains core and language-specific tasks. The pyb.core module contains core classes such as Project and Task.

from pyb import filters
from pyb import tasks
from pyb.tasks import java
from pyb.tasks import py
from pyb.core import *

The next section of the build script contains any variables used globally throughout the build script.

# variables
src = 'src'
www = 'www'
webxml = 'etc/web.xml'
builddir = 'build'
distdir = 'dist'
tempdir = 'temp'
classes = 'build/classes'
docs = 'build/docs'
jarfile = 'build/test.jar'
warfile = 'build/test.war'
zipfile = 'dist/test.zip'
srczipfile = 'dist/test.src.zip'
tarfile = 'dist/test.tar'
srctarfile = 'dist/test.src.tar'
gzipfile = 'dist/test.tar.gz'
bzip2file = 'dist/test.tar.bz2'
srcgzip = 'dist/test.src.gz'

Next are all of the targets, defined as python functions. Targets can call other targets directly and can invoke tasks. Since the build script is python you can also have any other type of python construct, such as loops, if structurs, and so on.

# targets
def build():
    tasks.java.javac(destdir=classes, basedir=src)

def javadoc():
    tasks.java.javadoc(destdir=docs)

def jar():
    tasks.java.jar(basedir=classes, destfile=jarfile)
    
def war():
    tasks.java.war(basedir=www, destfile=warfile, webxml=webxml)
    
def dist():
    build()
    jar()
    war()
    javadoc()
    
    # zip the source
    tasks.zip(basedir=src, destfile=srczipfile, includeFilters=[filters.java])
    
    # zip the binaries
    tasks.zip(basedir=builddir, destfile=zipfile, includeFilters=[filters.jars])
    tasks.tar(basedir=builddir, destfile=tarfile, includeFilters=[filters.jars])
    tasks.gzip(tarfile, gzipfile)
    tasks.bzip2(tarfile, bzip2file)
    tasks.gunzip(gzipfile, destdir=tempdir)
    tasks.bunzip2(bzip2file, destdir=tempdir)
    tasks.unzip(zipfile, destdir=tempdir + '/zip')
    tasks.untar(tarfile, destdir=tempdir + '/tar')
    
def clean():
    tasks.delete(dir=builddir)
    tasks.delete(dir=distdir)
    tasks.delete(dir=tempdir)
    
def failtest():
    tasks.fail('Something went wrong')
    
def test():
    tasks.copy(basedir='', destdir='copy')
    tasks.py.python(script='test.py')

The next section creates a map of target objects which are mapped to a name and which wrap the previously defined target functions. You must create a Target object for each of your target methods and include it in this targets map.

targets={
    'build':Target(build),
    'javadoc':Target(javadoc),
    'jar':Target(jar),
    'war':Target(war),
    'dist':Target(dist),
    'clean':Target(clean),
    'failtest':Target(failtest),
    'test':Target(test)
}

Finally the Project is constructed and executed. The project is executed immediately upon construction. If no targets are specified via the command line when the build script is executed then the target specified in the default parameter is executed.

Project(name='Demo Project', default='build', targets=targets)

Keep in mind that the above form is a simple example and represents the base-level functionality possible in a build script. As previously mentioned because a build script is a Python script you have full access to all of the features of Python.

Copyright 2004, Aetrion LLC. All Rights Reserved.