Using the PBI Builder
Using the PBI Builder Software
This guide is intended to instruct developers, or simply the curious, on how to use the PBI Builder software, which compiles a FreeBSD port, and turns it into a fully-functional PBI file. For more specific information how to create modules for use with the PBI Builder, please read the PBI Module Builder Guide.
Installing the PBI Builder software relatively easy, simply download the tbz package from the PBI Builder Homepage, and place it somewhere on your system with several GB of free space. Next run these commands (as root):
# tar xvjpf pbibuild*.tbz # ln -s `pwd`/pbi-build /pbi-build
Note: On regular FreeBSD systems, you will need to install "bash" for the builder to function, and link it to /bin/bash. This step is not required on PC-BSD.
# pkg_add -r bash # ln -s /usr/local/bin/bash /bin/bash
Using the PBI builder to convert a port into a PBI is very simple. First, you will need to copy a module directory into the /pbi-build/modules directory. Several examples are provided in /pbi-build/docs/module-examples, or you may copy a module from our subversion repository. After you have done this, simply run these commands:
# cd /pbi-build # ./buildpbi.sh
The first time you run the buildpbi.sh script, it will connect to CVS and download a copy of the ports tree. You may change the cvsup server it uses by editing /pbi-build/conf/ports-supfile. If you wish to update your ports tree, simply run "/pbi-build/cron/cvsup-nightly.sh". This script may be run from cron to ensure that your ports tree is always up to date.
The PBI Builder has a few extra options which you may wish to use during the creation of your PBI.
Selective Module building
When the modules diretory contains many different modules for building, it may be necessary to single out only one of them for creation instead of rebuilding all of them. To single out a module for building simply run ./buildpbi.sh with a module name as the first agument:
# ./buildpbi.sh firefox (This will build the module /pbi-build/modules/firefox, ignoring all others for this run)
PBI Build (Without re-compile)
During the creation of a new module, it may become necessary to recreate the PBI file to test new configurations. Often this does not require the complete rebuilding of the port from source. By skipping the source build, a new PBI may be generated within moments. To skip the building simply run the 3.makepbi.sh script in /pbi-build/scripts/3.makepbi.sh as shown:
# cd /pbi-build/scripts # ./3.makepbi.sh firefox
This will rebuild the FireFox PBI using the /pbi-buid/modules/firefox configuration, skipping the actual port re-building.
NOTE: This requires that you have a full build of the port already finished in /pbi-build/pbisandbox
The PBI Sandbox
In order to build a port without touching the host system, all creation is done in the /pbi-build/pbisandbox directory. This is a complete buildworld environment, and you may "chroot" into it in order to tweak a port build, or inspect the built contents of a port.
# chroot /pbi-build/pbisandbox
Sharing port distfiles
When running a port build, many files will be downloaded and stored in /usr/ports/distfiles within the /pbi-build/pbisandbox directory. The pbisandbox is removed between builds of modules, but starting in PBI Builder 2.0, the distfiles contents are preserved in the /pbi-build/distfiles directory. This provides convenience for a user, in that building a new port can be done quicker, by using saved distfiles/ data and not wasting bandwidth re-downloading many of the same files repeatedly. Should you wish to remove this saved distfile data, you may do so by deleting the /pbi-build/distfiles directory. It will be re-created at the next run of the PBI Builder.
Stuck on a building a particular PBI? Run into a bug in the PBI Builder software itself? Need to ask a question not covered in this guide? If so, please sign-up and send your questions in to the PBI Developers mailing list.