DESCRIPTION
-----------
A concurrent ports building tool.  Although FreeBSD ports supports building a
single port using multiple jobs (via MAKE_JOBS), it cannot build multiple ports
concurrently.  This tool accomplishes just that.

Some of it's key features:
 * Concurrent port building
 * Load control
 * Top like UI
 * Persistent builds (by default)


REQUIREMENTS
------------
python >= 2.6


INSTALLATION
------------
Unpack (or clone) the source files and in the portbuilder directory do:
# python setup.py build
# python setup.py install


USAGE
-----
NOTE: all ports are specified using [category]/[directory] as found in the ports
tree.  For example, to build all of KDE specify x11/kde4, or for VLC specify
multimedia/vlc


Usage:  portbuilder [-abdnpruFNU] [-c CONFIG] [-C CHROOT] [-D variable]
                    [-f PORTS_FILE] [-j J] [long-options] [variable=value]
                    port ...

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -a, --all             Add all installed ports to the list (aka `pkg_info-
                        aoq`)
  --arch=ARCH           Set the architecture environment variables (for cross
                        building)
  -b, --batch           Batch mode.  Skips the config stage
  -c CONFIG, --config=CONFIG
                        Specify which ports to configure (none, changed,
                        newer, all) [default: changed]
  -C CHROOT             Build ports in chroot environment
  -d, --debug           Turn off extra diagnostic information (faster)
  -D variable           Define the given variable for make (i.e. add ``-D
                        variable'' to the make calls)
  -f PORTS_FILE, --ports-file=PORTS_FILE
                        Use ports from file
  -F, --fetch-only      Only fetch the distribution files for the ports
  -j J                  Set the queue loads [defaults: attr=#CPU,
                        checksum=CPU/2, fetch=1, build=CPU*2, install=1,
                        package=1]
  --method=METHOD       Comma separated list of methods to resolve
                        dependencies (build, package, repo) [default: build]
  -n                    Display the commands that would have been executed,
                        but do not actually execute them.
  -N                    Do not execute any commands.
  --no-clean            Do not clean a port after it it has been
                        installed/packaged.
  -p, --package         Create packages for specified ports.
  -P, --package-all     Create packages for all installed ports
  --pkgng               Use pkgng as the package manager.
  --preclean            Pre-clean before building a port
  --profile=PROFILE     Produce a profile of a run saved to file PROFILE
  -u, --upgrade         Upgrade specified ports.
  -U, --upgrade-all     Upgrade specified ports and all its dependencies.


EXAMPLES
--------
Install KDE 4 and Xorg:
# portbuilder x11/kde4 x11/xorg

Install all ports specified in a file (# comments respected)
# cat /root/ports
print/cups      # For printing
devel/svk       # For development
^C
# portbuilder -f /root/ports

Fetch all the files required to update all ports in a file, fetch 4 ports at a
time
# portbuilder -Fuf /root/ports -j f=4

Reconfigure and upgrade all ports (and their dependencies) in a file
# portbuilder -c all -Uf /root/ports

Display the commands that will upgrade all installed ports
# portbuilder -anU

Simulate the above (using the Top display) without printing the commands
# portbuilder -aNU

Rebuild strigi with debug symbols
# portbuilder --force deskutils/strigi -DWITH_DEBUG

Build all ports, specified in a file, in an i386 chroot environment, using
packages were possible
# portbuilder --arch=i386 -C /scratchpad -f /root/ports -DUSE_PACKAGE_DEPENDS

Build ports using the pkgng package tool, and try install from a remote
package repository first
# portbuilder --method=repo,build -f /root/ports -DWITH_PKGNG

Install all ports from a repository, installing 4 packages at a time and
fetching 8 packages at a time
# portbuilder --method=repo -f /root/ports -j f=8,i=4


INTERFACE
---------
Portbuilder offers a user interface similar to the top(1) program.  The
interface should be intuitive however some commands are provided:

^L   - Redraw screen
d    - Toggle displaying ports with failed dependencies
f    - Toggle displaying only failed (and skipped) ports
i    - Toggle displaying only idle ports
PgDn - Scroll down display
PgUp - Scroll up display
q    - Quit portbuilder (once to send SIGTERM to all jobs,
                         twice to send SIGKILL to all jobs,
                         thrice to send SIGKILL to all and die)


NOTES
-----
 * Build log files are stored in /tmp/portbuilder, check there if a port failed.
 * Ensure the program runs as root, or has write access to build area (and
   /usr/ports/distfiles if ports need to fetch).
 * The load per stage can be seen under libpb/queue.py (at end of file).
   Default values (build load can be as high as cpus * 3 - 1, or more):
      attr     = CPUS
      config   = 1
      clean    = 1
      checksum = max(CPUS // 2, 1)
      fetch    = 1
      build    = CPUS * 2
      install  = 1
      package  = 1
   NOTE: pkginstall stage shares the install queue