PBI Module Builder Guide/9.2

From PC-BSD Wiki
Revision as of 12:08, 6 April 2012 by Drulavigne (Talk | contribs)

Jump to: navigation, search

(Sorry for the inconvenience)


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.

On PC-BSD, PBIs can be installed using the graphical AppCafe™ utility or from the command line using PBI Manager.

The PBI format changed between PC-BSD 8.x and 9.x. This section demonstrates how to create PBIs for PC-BSD 9.x and higher. Building PBIs for PC-BSD 8.x and Earlier describes the old format, but is considered to be deprecated.

Building PBIs for PC-BSD 9.x and higher

Creating a PBI from an existing FreeBSD port is a surprisingly easy and 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 FreeBSD ports into PBIs. EasyPBI provides a graphical interface and pbi_makeport provides a command line utility. This section demonstrates how to use both of these tools, explains the components of a PBI module, and provides some troubleshooting tips.

NOTE: 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.

Using EasyPBI

EasyPBI is a graphical application created by Jesse Smith and Ken Moore. It makes it easy to build a PBI module from a FreeBSD port. Beginning with PC-BSD 9.1, EasyPBI ships with PC-BSD and can be found in the Control Panel. If you double-click the EasyPBI icon in Control Panel, you will see the screen shown in Figure 10.7a.

If ports is not installed, you will first receive the pop-up message: "The FreeBSD ports tree is not installed for this system or user. Please install the ports tree as root to make it available for all users, or push 'File'->'Get Ports' to retrieve the ports tree for this user only". Since EasyPBI is used to convert an existing FreeBSD port into a PBI module, you will need to install the FreeBSD ports collection using one of the methods in the message. If you want the ports tree to be available to any user, go to Control Panel -> System Manager -> Tasks. Use this method if multiple users will be using the EasyPBI utility. Alternatively, if you only want the ports tree to be available to the current user, click File ➜ Get Ports from within EasyPBI; this will fetch the ports tree and place it in the user's home directory.

Figure 10.7a: EasyPBI Graphical Interface


To build a PBI using EasyPBI:

1. Create a module for the desired FreeBSD port:

When determining which PBIs need to be built, refer to the PBI Requests forum to determine which PBI's have been requested by users. You should also check that a module does not already exist on the PBI Modules section of trac.

To create a new module, click the "New Module" button and use the browser to select the desired port from the FreeBSD ports tree. Once a port is selected, EasyPBI will attempt to automatically supply the port information for the PBI and display the results on the GUI. In the example shown in Figure 10.7b, the net/xrdesktop port has been selected and the fields have been auto-filled in.

Figure 10.7b: Reviewing the Port's Information


You should review these fields for accuracy. If you click "Get Port Info" FreshPorts.org will open in the default web browser so that you can view additional information about the port.

A generic icon will be supplied for the module; you can change the default icon by clicking the "Choose Icon" button. When using a custom icon, use 64x64 .png files with transparent backgrounds.

If the program provides a GUI, check the box "GUI App".

Once the port information is complete, click the "Create Module" button and EasyPBI will produce a generic PBI module. A message will indicate the location of the module, as seen in the example in Figure 10.7c:

Figure 10.7c: PBI Module Created


2. Build a PBI from the module: once your module is created, click on the "Build PBI" tab and click the Select Module button to browse to the module you just created. Figure 10.7d shows this tab with our example PBI selected.

Figure 10.7d: The Build PBI Tab


The options in this tab allow you to perform the following actions:

Save Settings as Defaults: once you are satisfied with your settings, click this button and EasyPBI will remember your settings between uses.

Change the Output Directory: allows you to specify which different directory will store the built module. By default, it is the EasyPBI/PBI subdirectory of the user's home directory.

Change the Digital Signature File: the PBIs available from the PC-BSD repositories are digitally signed by the PC-BSD project's signature file. If you are creating your own repository, you can use your own digital signature file by browsing to its location.

Use TMPFS: if your build system has a lot of RAM, selecting this option can speed up the build.

Select Module: select the previously created module which you would like to build.

Build PBI: starts the build of the PBI using the settings contained within the PBI module. It will prompt you for the superuser password and requires a working Internet connection to build the PBI. This process may take quite a while, depending upon the port selected and the speed of your computer. The build messages will be displayed in the window at the bottom of the tab. EasyPBI will inform you when the PBI build is finished, and whether it was successful or not.

Stop Build: stops the build process. Click the "Build PBI" button to resume the build.

Save Build Log: useful if the build fails.

You can produce additional modules from the "Create Module" tab while a PBI build is running.

The Module Editor tab, shown in Figure 10.7e, allows you to further customize the PBI module.

Figure 10.7e: Module Customization Using Module Editor Tab


Several tabs are provided, allowing you to perform the following advanced actions. Note that most PBI modules do not require you to make any configuration changes in the Module Editor tab. This tab allows the creation of more complex PBI modules that are built with additional FreeBSD ports or scripts which are not provided by the default FreeBSD port.

1. pbi.conf: Typically the program name, website, and author are left at their defaults. If the information is incorrect, you should email the FreeBSD port maintainer (shown in the Program Author) field so that they can update the FreeBSD port. If you choose to replace the default icon, use a 64x64 .png file with a transparent background. If your PBI requires a dependency that is not provided by the FreeBSD port, use the + button next to "Make Port Before" to select the needed port. If you wish an additional port to be included with your PBI, use the + button next to "Make Port After" to select the desired port.

The "Make Options" field lets you specify a space separated list of options. The available options and their default settings will be listed in the OPTIONS= section of the port's Makefile.

If the resulting PBI needs to be run as the root user, check the "Require Root Permissions" box.

2. Resources: this tab, shown in Figure 10.7f, is used to

Figure 10.7f: PBI Module Resource Configuration


3. Desktop/Menu Entries: this tab, shown in Figure 10.7g, is used to

Figure 10.7g: Customizing the PBI's Desktop and Menu Entries


4. External-Links: this tab, shown in Figure 10.7h, is used to

Figure 10.7h: Configuring Custom Links for the PBI


If the PBI build fails for some reason, you may need to modify the module. Use the build log to determine the error and modify the module as needed. If you are unsure how to fix the module, send the build log for the failure as well as the module to the pbi-dev mailing list.

3. Test the PBI: once the PBI build is complete, a pop-up message will indicate that the PBI finished building successfully. You will find the PBI in the output directory that you specified in Figure 10.7c. To continue with our example, the following commands will install the PBI so that it can be tested. Note the error message that occurs since the PBI has not been signed yet.

cd /home/dru/EasyPBI/PBI
pbi_add xrdesktop-1.2_2-i386.pbi
pbi_add: No digital signature! If you are *SURE* you trust this PBI, re-install with --no-checksig option.
pbi_add --no-checksig xrdesktop-1.2_2-i386.pbi
Verifying Checksum...OK
Extracting to /usr/pbi/xrdesktop-i386
Installed: xrdesktop-1.2.2

Once installed, specify the full path to the application's binary to make sure that you are testing the PBI's binary. If the application starts and is a GUI, try using all of the menu items to make sure they work as expected. 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 after some Googling, send the error report the pbi-dev mailing list.

Alternately, if everything seems to be working, send the tarball of the PBI to the pbi-dev mailing list. You will find it in the EasyPBI/Modules/ subdirectory. In our example, the name of the tarball is /home/dru/EasyPBI/Modules/xrdesktop.tar.gz.

Creating a New PBI with pbi_makeport

Starting in PC-BSD 9.x and higher, pbi_makeport is included with the operating system. This utility provides an easy way for a user to convert an existing FreeBSD port into a PBI module. The PBI build server builds modules into PBIs which are then made available to users through AppCafe™. man pbi_makeport provides details on this application's various usage options.

When running pbi_makeport it is possible to supply an optional metadata configuration directory which contains additional data used to supplement the port building and the final PBI file. This configuration directory may contain extra icon data for the desktop, install/uninstall scripts, custom make options and more.

Examples of 9.x modules can be found at Examples in Subversion.

FreeBSD ports may contain build dependencies, runtime dependencies, and required libraries. When building a PBI, pbi_makeport automatically compiles all of the required dependencies, and, when finished compiling, prunes the build dependencies before packaging the PBI file, leaving only the runtime packages and libraries that are required for the program to work. This means that any files which are included in the PBI are necessary for the program to run, and manually removing them will cause the program to fail.

PBI Module Components

A PBI module contains the following components. When creating a PBI module, create a directory on your computer to hold the module's components. For example, if you are creating a PBI module for firefox, create a directory called firefox/ and place the following files within that directory. The directory that you create is referred to as %PBI_APPDIR%%.


The text of a license agreement you want the user to click to accept before installation. This file is optional unless the underlying port is restricted and requires the user to accept a license in order to install and use the software.

2. pbi.conf

The pbi.conf file is mandatory. It is a simple shell script that contains the information needed to build the PBI. Typically this file requires you to modify a few simple variables, such as the name of the program, its location in the ports tree, and the name of its icon. Sometimes you will need to set a few additional variables in order to make sure that required dependencies are included in the PBI. If you get stuck when creating your own pbi.conf, you can view the pbi.conf file for every PBI module in this section of the PC-BSD trac repository. Here is an example of the pbi.conf file for firefox:

# PBI Build Configuration
# Place over-rides and settings here
# XDG Desktop Menu Spec:
# http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html

# Program Name
# Program Website
# Program Author / Vendor
PBI_PROGAUTHOR="The Mozilla Foundation"
# Default Icon (Relative to %%PBI_APPDIR%% or resources/)
# The target port we are building
# Additional options for make.conf
# Ports to build before / after
PBI_MKPORTAFTER="audio/esound x11-fonts/dejavu x11-themes/qtcurve-gtk2 devel/gconf2 www/firefox-i18n"

# Exclude List
PBI_EXCLUDELIST="./include ./share/doc"
# Increment to trigger rebuild of PBI on build servers
# This app needs to install as root
# Set the priority of this build 
# Set the files we want to exclude from the shared hashdir

Table 10.7a describes the most commonly used variables. When creating your pbi.conf file, you will want to refer to the FreeBSD port's Makefile and pkg-descr to determine which values to use.

Table 10.7a: Commonly Used pbi.conf Variables

Variable Description
PBI_PROGNAME= mandatory; should be the same value as PORTNAME= in the port's Makefile, but capitalized
PBI_PROGWEB= mandatory unless does not exist; should be the same value as WWW= in the port's pkg-descr
PBI_PROGAUTHOR= mandatory; often found in the port's pkg-descr or at the website for the application
PBI_PROGICON= mandatory path, relative to %PBI_APPDIR%%, to application icon file in png format
PBI_PROGREVISION= bump up a PBI's revision number; useful when rebuilding a port with new PBI specific options
PBI_MAKEPORT= mandatory; the path to the port within /usr/ports/
PBI_MAKEOPTS= optional; set this to the options that you want saved into make.conf for the port building process (e.g. WITH_CUPS=YES)
PBI_MKPORTBEFORE= optional; port(s) to build before starting the target port PBI_MAKEPORT
PBI_MKPORTAFTER= optional; port(s) to build after finishing the target port PBI_MAKEPORT
PBI_BUILDKEY= should not be included; this variable is used on the PBI build server to force the rebuild of a PBI that has failed to build
PBI_REQUIRESROOT= set to to YES to require this app to be installed as root; default is NO which allows it to be installed as a regular user
PBI_EXCLUDELIST= list of files or directories to exclude from the final archive, such as ./include or ./share
PBI_AB_PRIORITY= may be set by build server administrator; a higher number indicates a greater priority and will be built before lower priority PBIs
PBI_AB_NOTMPFS= set to YES to disable using tmpfs when doing auto-builds on a server
PBI_HASH_EXCLUDES= set to a space delimited list of files to exclude from merging into the shared hash-dir
export mandatory; followed by a list of all of the variables that will be included when the PBI is built

3. external-links

The optional external-links file contains a list of targets to link into the system's LOCALBASE at PBI installation time. This is useful for placing binaries and files in the user's PATH. When building PBIs from a FreeBSD port, this file is usually not needed, as most binaries and files are auto-detected and placed in the LOCALBASE. Example 10.7a shows an example usage:

Example 10.7a: Example external-links File

# Files to be Sym-Linked into the default LOCALBASE
# One per-line, relative to %%PBI_APPDIR%% and LOCALBASE
# Defaults to keeping any existing files in LOCALBASE

# TARGET                LINK IN LOCALBASE       ACTION
#etc/rc.d/servfoo       etc/rc.d/servfoo        keep
#include/libfoo.h       include/libfoo.h        replace
#etc/rc.d/servfoo       etc/rc.d/servfoo        keep
bin/firefox3            bin/firefox3            binary,nocrash

The flags in the ACTION column are as follows:

  • keep: if this file already exists in LOCALBASE, don't overwrite it
  • replace: replace this file in LOCALBASE if it exists
  • binary: this file is an executable
  • nocrash: used for binary files; don't display crash handler if program exits with non-0 status
  • linux: used for binary files; indicates that this is a Linux application, and needs to be run with Linux compat

4. resources/

The resources/ directory can contain extra files you wish copied into the PBI application directory. This is often the best place for icons and other files not included with a port.

5. scripts/

This directory can contain the following scripts:

  • post-install.sh: script run immediately after the extraction of PBI contents to disk
  • post-portmake.sh: script run during building of the PBI file, after the port compile is finished
  • pre-portmake.sh: script run during building of the PBI file, prior to the port compile
  • pre-install.sh: script run before installation of the PBI; return non-0 to halt installation
  • pre-remove.sh: script run before deletion of the PBI file

Table 10.7b summarizes the variables that may be used in these scripts:

Table 10.7b Supported Variables

Variable Description
PBI_PROGNAME= mandatory; should be the same value as PORTNAME= in the port's Makefile, but capitalized
PBI_PROGDIRNAME= name of the subdirectory that is created for the PBI in /usr/pbi/ (e.g. "firefox-amd64" for the 64-bit Firefox PBI)
PBI_PROGDIRPATH= full path to the PBI install directory (e.g. /usr/pbi/firefox-amd64/ for the 64-bit Firefox PBI)
PBI_PROGVERSION= version of the program - should be the same value as the DISTVERSION in the port's Makefile
PBI_RCDIR= location of rc.d/ directory used by PBIs, usually /usr/local/etc/rc.d
SYS_LOCALBASE= LOCALBASE of the default system, typically /usr/local
PBI_FAKEBIN_DIR= the binary wrapper directory, typically /usr/pbi/<pbidir>/.sbin/

6. xdg-menu/ and xdg-desktop/

The xdg-menu/ and xdg-desktop/ directories can be used to supply menu and desktop icons, respectively. The file that you place in these directories should be in the format pbiname.desktop. Example 10.7b shows the firefox.desktop files for the firefox PBI:

Example 10.7b: firefox.desktop File

more xdg-menu/firefox.desktop
#!/usr/bin/env xdg-open
[Desktop Entry]
Exec=%%PBI_EXEDIR%%/firefox %U

more xdg-desktop/firefox.desktop
#!/usr/bin/env xdg-open
[Desktop Entry]
Exec=%%PBI_EXEDIR%%/firefox %U

%%PBI_EXEDIR%% should reference the PBI's executable and any required switches.

For more details on the XDG menu specifications, please refer to the freedesktop specifications.

7. xdg-mime/

The xdg-mime/ directory is used to register file associations according to the freedesktop MIME specs. This requires the creation of an XML file. The example shown in Figure 10.7c adds the MIME information for gimp, so that it can be available as an application choice in a web browser:

Example 10.7c: Gimp MIME Info

more xdg-mime/gimp-xdg.xml
<?xml version="1.0"?>
<mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'>
 <mime-type type="application/x-gimp">
   <comment>Gimp - XCF File</comment>
  <glob weight="100" pattern="*.xcf"/>
  <glob weight="100" pattern="*.XCF"/>

Useful Tips

If your PBI's executable does not run, it may be because the program executable is actually a wrapper script rather than a binary file. If so, check the first line of the script to make sure 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 this example.

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.

Getting Help

The PBI Developers mailing list can help if you:

  • get stuck building a PBI
  • need to ask a question about your PBI
  • are ready to submit a new module
  • find a bug in an existing PBI
  • have a bugfix for an existing PBI