Chapter 5 Using Tinderbox

To run a Tinderbox build, and track the progress in the database, you must first add the port you wish to build to the database using the ${pb}/scripts/tc application:

# cd ${pb}/scripts && ./tc addPort -b {BUILD} -d {PORT DIRECTORY}

Where {BUILD} is the name of the Build for which this port should be built and {PORT DIRECTORY} is the directory within the PortsTree where this port can be found. For example, to build the GNOME 2 Desktop port for the Build 9.2-FreeBSD:

# cd ${pb}/scripts && ./tc addPort -b 9.2-FreeBSD -d x11/gnome2

Note: A port does not have to be added to the database for Tinderbox to build it. If you just want to do a quick ad hoc port build, forgo the previously mentioned step.

Note: In Tinderbox 2.x, addPort took a -r argument which resursively added ports to the datastore. In Tinderbox 3.0 and higher, this option is assumed. If you do not want to enable recursion, specify the -R argument to addPort.

To start a Tinderbox build, use tc:

# cd ${pb}/scripts && ./tc tinderbuild -b {BUILD} [{PORT DIRECTORY}]

Note: If the {PORT_DIRECTORY} argument is empty, all ports without an up to date package in the datastore will be built.

For example, to build the GNOME 2 Desktop for the Build 9.2-FreeBSD:

# cd ${pb}/scripts && ./tc tinderbuild -b 9.2-FreeBSD x11/gnome2

Tip: Although port build logs are saved separately, messages and errors from Tinderbox itself will be echoed to the terminal. To capture all of this, it is recommended to redirect tinderbuild output to a log file. For example:

  • Bourne shell equivalents:

    # cd ${pb}/scripts && ./tc tinderbuild -b 9.2-FreeBSD \
      x11/gnome2 > ${pb}/builds/9.2-FreeBSD/build.log 2>&1 &
  • C shell equivalents:

    # cd ${pb}/scripts && ./tc tinderbuild -b 9.2-FreeBSD \
      x11/gnome2 >& ${pb}/builds/9.2-FreeBSD/build.log &

More advanced logging options are also available. All log files including tinderbuild output, make logs, and individual port build logs can be captured in one location. This location is specified by the LOG_DIRECTORY configuration option. By default, this option is unset meaning that logs will not be centralized. If set to a directory, a subdirectory will be created in the format of {BUILD}-{DATE} where {BUILD} is the Build name, and {DATE} is the date in the format YYYYMMDDHHMMSS (e.g. 9.2-FreeBSD-20091012112105). Within this subdirectory will be the tinderbuild log, and symlinks to the make logs and individual port build logs. If you would rather have the log files copied to this location (instead of using symlinks), set the LOG_DOCOPY configuration option to 1.

To manipulate the logging configuration, use ${pb}/scripts/tc configLog with the appropriate options. Those options are in Table 5-1.

Table 5-1. configLog Options

-d <directory>Set the logging directory
-DUnset the logging directory
-cSet the LOG_DOCOPY option to 1 which will copy log files to the log directory instead of using symlinks
-CSet the LOG_DOCOPY option to 0
-zSet the LOG_COMPRESSLOGS option to 1 which will compress the log files to save space
-ZSet the LOG_COMPRESSLOGS option to 0

The tinderbuild function also accepts some additional commands, described in Table 5-2.

Table 5-2. tinderbuild Commands

-bthe Build on which to run the tinderbuild process
-initupdates the Jail then updates the Build
-nullfsuses nullfs instead of NFS to mount Jail and PortsTree file systems
-cleanpackagesremoves all packages already built fors the specified Build
-onlymaketinderbuild exits after generating the Makefile; packages are not built
-updateportsupdates the Build's PortsTree (NOTE: dangerous if doing parallel runs with the same PortsTree)
-skipmakeskips the Makefile generation stage (NOTE: only use this option if a good Makefile already exists)
-nodudsskips the duds file generation stage (NOTE: packages which are forbidden or ignored will be built)
-nocleandoes not clean up the Build hierarchy after the port build completes
-plistcheckmakes any plist verification problems (e.g. leftover files) fatal
-cleandistfilesremoves all files and directories in the distfile cache prior to starting the build
-fetch-originalignores the distfile cache, and fetches all distfiles from their respective sources
-nologdisables log analysis code
-onceonlyonly performs one build pass (i.e. tinderbuild Phase 1)
-norebuilddo not force a rebuild of packages specified on the command line
-notestdo not run port regression tests as part of the build
portdir/portname ...an optional list of ports to build; if omitted, all ports in the datastore for the given Build will be built