Any large software project needs a set of guiding principles and processes. Ideally, a project's processes are documented so new developers know what to expect. Processes are meant to address how the software project manages its code development, answering questions such as:

The rest of this section provides an overview of how PC-BSD manages its development process.

The code base for PC-BSD is kept in a subversion server, and trac provides browse and search mechanisms for the code base. Chapter 12 introduced you to the PC-BSD trac system. PC-BSD's code base is divided into branches, with each branch representing a different version of the software. Figure 14-1 shows the branches for the "pcbsd" code base from versions 1.4 to 7.1.1.

Figure 14-1. PC-BSD branches

New commits are made against trunk, which represents the current version that hasn't been released yet. Figure 14-1 was taken before the release of PC-BSD 8, meaning that version 8 was the trunk version at that time.

After a version is released, it is moved from trunk to a new version number in branches, and a new trunk is created for the next expected version. It is rare for a commit to be made against a released version because it is considered to be released (or finalized).

trunk and each branch version are divided into modules, which allow developers to follow and commit to the modules that interest them. Most modules contain the source files and configurations for a PC-BSD utility. The modules for trunk (version 8.0 before it was released) are seen in Figure 14-2 and briefly described in Table 14-1.

Figure 14-2. PC-BSD development modules

Security patches are not stored on the trac server because they are usually based on the FreeBSD security advisory system.^[105] Every PC-BSD security patch installed by Update Manager contains the URL to the associated security advisory.

As changes are committed to the PC-BSD code base, an email containing the details of the change is automatically sent to the Commits mailing list.^[106] Browsing through that list's archives gives you a good idea of the changes made to the PC-BSD code base.

As the trunk version of PC-BSD gets closer to being released, installable versions of the operating system are periodically released to the Testing mailing list.^[107] As described in Chapter 12, everyone is encouraged to install and try the testing version and to report any bugs so that developers can fix them. This helps to ensure that when the new version is released, it has been tested on many different types of hardware and is as bug-free as possible.

In addition to the resources mentioned in the previous section, the following resources are available to programmers interested in contributing to the development of the PC-BSD operating system.

If you are interested in PC-BSD system development, you should also take the time to familiarize yourself with the following documentation because PC-BSD is based on FreeBSD and KDE.

Anyone can browse and download any portion of the PC-BSD code base. If you are interested only in a few files, you can use your browser to download them from the trac server. If you would like to follow the changes being made in an entire branch while keeping the files you have downloaded "in sync" with the changes on the subversion server, you should use the svn utility to "check out" (download) the files you need.

Your PC-BSD system comes with the svn utility installed, and the Getting Source guide^[114] contains instructions for downloading all the branches, trunk only, or a specified branch. svn comes with a lot of options; following are the ones developers use most often.

Only PC-BSD committers are able to make changes to the code on the trac server. If you have created code patches, submit them using the methods described in Chapter 12. Over time, the community gets to know you and your development style. If you submit many useful patches, don't be surprised if you are asked whether you would like to have a commit bit, the term used to signify that you now have the necessary permissions to upload your changes directly to the code base.

PC-BSD committers are also able to use the following svn commands.

The previous sections describe the development process for the PC-BSD operating system. This section concentrates on the development process for PBIs.

PBIs are stored on the PC-BSD Project's official PBI build servers (http://pbibuild.pcbsd.org and http://pbibuild64.pcbsd.org). Every Monday through Friday night, each server checks and builds the PBIs that meet any of these criteria:

If the build of a PBI fails, an email is automatically sent to the Pbibuild mailing list.^[115] The email contains the last 50 lines of the build log, which should include the error message. The full build log can be downloaded from the PBI build server. Figure 14-3 shows a screenshot from the build server, which indicates that the astro/googleearth build has failed.

Figure 14-3. Build failure for astro/googleearth on the PBI build server

To access the build log, click the hyperlink for the failed PBI, in this case astro/googleearth. The build log has a .bz extension, which indicates that it has been compressed. You can uncompress the file using the bunzip2 command that came with your PC-BSD system.

The configuration information used for building a PBI is known as a module. PBI modules are created by the PBI maintainer. The next section demonstrates how to create a PBI module. You can browse through all the modules at http://trac.pcbsd.org/browser/pbibuild/modules. Browsing through the modules can be helpful if you are stuck building a PBI or aren't sure how to modify a PBI's configuration files and want to see how other PBI developers handled their module's configuration. Two tools are available for creating a PBI. The recommended method is to use PBI Builder^[116] when a FreeBSD port already exists. If a FreeBSD port does not exist, PBI Creator^[117] can be used to create the PBI. PBI Builder is recommended for several reasons, including:

In contrast, PBI Creator isn't recommended for several reasons, including:

For these reasons, this chapter demonstrates only how to use PBI Builder. If you would like to tackle porting software to a FreeBSD port, work your way through the FreeBSD Porter's Handbook.^[118]

After a PBI is created, it needs to be tested by others before it is added to the PBI build server and made available for download at pbidir.com. This helps to ensure the quality of the software available to PC-BSD users and provides a check that the developer didn't miss anything when creating the PBI.

Anyone can test a PBI. Feedback regarding a PBI should be sent to the Pbi-dev mailing list. This list should also be used if you ever find a bug in a PBI that is already available at pbidir.com so the developer can fix the bug.

In addition to the resources mentioned in the previous section, several resources are available to PBI developers, including:

Chapters 9 and 10 introduced you to FreeBSD ports and packages and gave some insight into the work port maintainers go through so that the package and port "just work." PBI Builder simplifies the process of converting an existing FreeBSD port into a PBI, which means anyone can create a PBI without needing much (if any) previous development experience. If you have a bit of time to spare, like to learn new things, and are interested in seeing as much software as possible available to the PC-BSD community, try your hand at creating a PBI with PBI Builder. The more PBIs that are available, the better it is for everyone because it ensures that even brand new PC-BSD users can safely install the software they need and keep it up to date.

Information about and the download for PBI Builder can be found at http://www.pcbsd.org/content/view/45/30/. PBI Builder is a command-line utility that requires you to edit a few configuration variables that are used when the PBI is built. PBI Builder automates the entire build process: the creation of the build sandbox, fetching the source for the port and all its dependencies, building everything that is needed, and converting the results into the PBI.

PBI Builder uses a large archive that contains the system source and world environment used by PC-BSD. It provides all the libraries needed to ensure that the resulting PBI works on the version of PC-BSD that matches the version of PBI Builder.

# cd /pbi-build/modules
# fetch http://www.pcbsd.org/files/templates/module-template.tgz
# tar xvzf module-template.tgz

# mkdir -p irc/conspire
# cp -R template/* irc/conspire/
# ls -F irc/conspire
build.sh        kmenu-dir/      overlay-dir/    preportmake.sh
copy-files      mime-dir/      pbi.conf

# Program Name
PROGNAME="conspire"

# Program Website
PROGWEB="http://confluence.atheme.org/display/CON/Home"

# Program Author
PROGAUTHOR="Conspire Team"

# Default Icon (Relative to overlay-dir)
# Please only use PNG files for the program icon
PROGICON="share/pixmaps/conspire.png"

# FreeBSD Port we want to build
PBIPORT="/usr/ports/irc/conspire"

ExePath: bin/conspire
ExeIcon: share/pixmaps/conspire.png
ExeDescr: IRC Client

# cd /pbi-build
# ./pbibuild.sh irc/conspire
Running portsnap to update ports tree
Starting module traversal...
Copying /pbi-build/buildworld to /pbi-build/pbisandbox
Copying /pbi-build/ports to /pbi-build/pbisandbox/usr/ports
Starting build of irc/conspire
Rebuilding module irc/conspire...

Found preportmake.sh, running it...
Running port build...
SUCCESS! Build finished for irc/conspire
#

Advanced Module Configuration

Most PBIs can be built by simply modifying the variables mentioned in the previous section. This section provides an overview of the more advanced configurations that are possible through modifying the other variables and files that come with the modules template.

• build.sh: This script is run after all the files have been copied to the PBI's directory and can contain any commands you wish to run at that time. The PBI Module Builder Guide^[124] provides an example that modifies the version number.

• copy-files: It is rare to need this file, but you can use it to modify where certain files get populated to.

• kmenu-dir/0mymenu: The variables in this file control how the application appears in the KDE menu. Table 14-2 provides a description of each variable.

• mime-dir/00mymime: Some applications require their MIME types to be listed to work correctly. See the PBI Module Builder Guide for usage examples and gotchas.

• overlay-dir/: PBI builder automatically populates all the files needed by the PBI, according to the underlying port's instructions. If you have an additional file you would like to include (for example a README for the PBI) or a customized graphic, include it here. You can also customize the PBI scripts that came with this directory but should only do so if you have a good reason to make the change.

• pbi.conf: Table 14-3 summarizes the remaining variables in this file.

• preportmake.sh: Allows you to execute commands needed for the port to build properly. See the PBI Module Builder Guide for an example.

Table 14-2. Variables that Control a PBI's Appearance in the KDE Menu

Variable	Description
ExePath	The path to the application's executable as listed at Freshports.
ExeIcon	The path to the application's icon as listed at Freshports or the name of the custom icon you have created in overlay-dir/.
ExeDescr	A brief description of the application.
ExeNoDesktop	Set to 0 if you want a desktop icon and to 1 if you don't.
ExeNoMenu	Set to 0 if you want an icon in the KDE menu and 1 if you don't.
ExeRunRoot	Some applications require superuser access to run correctly. Set this to 1 to require the user to enter the administrative password when the application launches.
ExeRunShell	Set to 0 if the application should run in a GUI and set to 1 if the application is command-line based and should be executed in a Konsole session.
ExeNotify	Set to 0 to disable the bouncy application loading icon and set to 1 to enable it (the preferred setting).
ExeLink	Set to 1 to open the ExePath value in Konqueror, and set to 0 to launch the ExePath value as an executable.
ExeWebLink	If the ExePath value is an URL, set to 1 to open the URL in Konqueror; otherwise, leave it set as 0.
ExeTaskbar	Places application in system tray; this feature is currently unimplemented.
ExeOwndir	0 places the application name in top level directory of KDE menu, 1 places the application name in its own directory under the category indicated by ExeKdeCat, and 2 places the application name in the category indicated by ExeKdeCat.
ExeKdeCat	Set to one of the category names listed in Kickoff

If you right-click Kickoff and select Menu Editor, you can see the settings that come with every application in the KDE menu. Comparing the General and Advanced tab of an application should give you a better understanding of the effect that the variables in Table 14-3 have on the KDE menu. Figure 14-4 shows a screenshot for the installed conspire PBI.

Figure 14-4. KDE menu settings for the conspire PBI

Table 14-3 briefly describes the remaining variables that can be set in pbi.conf.

Table 14-3. Remaining Variables for pbi.conf

Variable	Description
PBIVERSION=	Enables you to override the PBI version if the build fails to automatically detect it.
PROGLIBS=	Leave at AUTO; otherwise, you have to manually populate the PBI's directory. If you need to override a file that is populated, use copy-files instead.
PBIUPDATE=	Leave as-is as needed by the PBI build server.
OTHERPORT=	If you want to include another port in your PBI (besides the dependencies listed in the port's Makefile), add its category and portname; this is useful for applications that have additional plugins or skins that are available as separate ports.
MAKEOPTS=	Enables you to pass make targets that are used when the PBI is built; Chapter 10 discusses targets.
BUILDKEY=	Committers can temporarily change this number to force the build server to rebuild the PBI.
PBIDISABLEFONTLINK=	Use this if you want to use the application's internal fonts instead of the system fonts.
PBIKEEPGL=	Use this to use the applications internal libGL libraries instead of the system libraries.
PBIPRUNE*	Several prune variables allow you to keep include directories, python files, perl files, or doc files that were created during the PBI build.
BUILDINMATE=	Uncomment this line if you are building an inmate file instead of a PBI.
INMATEVER=	Uncomment and set a version number for the inmate; increment the number for each later version.

ERROR: 2.1 Build failed of irc/conspire!!!

# cd /pbi-build/modules/irc
# tar cvf /conspire.tar
# bzip2 /conspire.tar

This chapter discussed the most advanced tasks you can perform on your PC-BSD system, including those that enable you to contribute software back to the PC-BSD community so other users can benefit from it.

We cover a lot of ground in this book. It is our hope that you enjoyed learning more about the PC-BSD operating system and that this book is a handy guide you refer to often. We also hope that you have as much fun reading and using it as we had writing it!