PC-BSD® provides a unique file format known as a PBI (push button installer). PBI files end with the .pbi extension and are self-contained installation programs. This means that even novice users can safely install and uninstall PBIs without inadvertently overwriting or deleting files needed by the operating system or other applications.

A PBI file includes all the runtime and library dependencies required by the application. This means that a PBI is a large file, but this does not necessarily mean that the installed PBI will be that large. During installation, the PBI system compares the currently installed libraries and files with the ones contained within the PBI file and only installs the ones that are not already installed on the system. A hash database is used to eliminate dependency problems while allowing the computer to share libraries between different programs.

Once a PBI is created, it can be installed using the graphical AppCafe® utility or from the command line using PBI Manager.

In order to create a PBI, the software must already be ported to FreeBSD. The easiest way to confirm whether or not a FreeBSD port exists is to search for the software at FreshPorts.org[1]. If a port does not exist, you can issue a port request at the PC-BSD® Port Requests forum using these instructions[2]. Alternately, if you have ported software before, the Porters Handbook[3] contains detailed instructions for porting software to FreeBSD.

Creating a PBI from an existing FreeBSD port is a mostly automated process that does not require development skills. Some ports are effortless to convert while more complex ports may require some thought and simple scripting. Two utilities are available for converting a FreeBSD port into a PBI:

pbi_makeport: provides a command line utility as part of the PBI Manager suite.

Before creating a PBI, check to see if one exists using the instructions in Submit PBI Requests. If you decide that you prefer to request a PBI that you need rather than to create one, that page also contains instructions for submitting a PBI request.

Testing the PBI

Once your PBI has built, test the PBI to ensure that it installs and that the application works.

As the superuser, use the pbi_add command with the --no-checksig option:

pbi_add --no-checksig /path_to_pbi

Once installed, start the application from the command line to determine if there are any error messages at application launch. When testing the executable, use the one located in /usr/pbi/(pbi-name)/bin/ so all the linking will be properly set up. Otherwise you can get some interesting errors about missing files.

If the executable does not start the application, the executable may actually be a wrapper script rather than a binary file. If so, check the first line of the script to make sure that it is using the right path for the scripting language. For example, #!/bin/python is an incorrect path which should be changed to #!/usr/pbi/(pbi-name)/bin/python.

The suggested path works because each program is packaged with the proper version of the language it uses and you want to make sure it uses that one. This is usually accomplished by putting a quick sed line in the post-install.sh script to fix the first line as seen in the post install script for frets on fire[4].

If the application starts and it is a GUI application, go through the various menus to see if they produce any errors.

If you encounter any error messages in either starting or using the application, record them. If the fix for resolving the error messages is not clear to you, send the error report to the pbi-dev mailing list[5].

If your PBI works and you would like to submit its module to be included on the build server, compress it after changing to your module directory (%%PBI_APPDIR%%):

>cd /usr/local/my_pbis>tar czvf ~/your_pbi_name.tar.gz .

This will create a compressed tarball named your_pbi_name.tar.gz in your home directory. Send this file to the pbi-dev mailing list[5].

Submit the PBI

Include the following in your mailing list submission, this consistent format will be helpful to all:

Subject of email: "PBI Submission of <PBI name>"

Name of the first PBI

Description

Master sites (where the original can be obtained - listed in the port's Makefile by this variable)

Category/directory name (often the same as the PBI name) such as: games/epiar

Attachment of PBI module (this is a function of the email client, but don't forget to include it)

More than one PBI may be submitted by the same person in the same email, but please limit to five per message per day and be sure to include the above information for each.

Here is an example submission:

Email Subject: PBI submission Epiar

Epiar

Epiar (ep-ee-are) is an open source computer game, in which the player navigates space from planet to planet, saving money to buy ship upgrades and new ships. The player can also join mercenary missions, attack other ships to steal their money and technology, and explore the universe. The game combines the action/arcade elements of aircraft dogfighting and the openness of role playing games to create this experience.

Epiar is a space exploration/combat/trading game. The Escape Velocity (EV) series for the Mac was the major point of inspiration for this game.
Other notable games of this genre include: