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.
PBI Module Components
This section describes the various components that comprise a PBI module. A PBI module is simply a collection of files which controls the contents of the PBI.
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 the directory as the superuser using this command:
As you create the subdirectories and files needed by the PBI module, save them to that directory. This directory is referred to as %%PBI_APPDIR%%. The rest of this section assumes that you are the superuser.
If the application requires the user to read a license agreement, save that license as a file named LICENSE in your %%PBI_APPDIR%%. 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.
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.
Here is an example of the pbi.conf file for firefox. When creating your file, modify the text in red to meet the needs of the PBI.
Table 11.6a describes the most commonly used variables. When creating your pbi.conf file, refer to the FreeBSD port's Makefile and pkg-descr to determine which values to use.
|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 to make.conf for the port building process (e.g. WITH_CUPS=YES)|
|PBI_MKPORTBEFORE=||optional; port(s) to build before building the PBI|
|PBI_MKPORTAFTER=||optional; port(s) to build after building the PBI|
|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|
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. This file is usually not needed as most binaries and files are auto-detected and automatically placed in the LOCALBASE.
Example 11.6a shows an example usage:
Example 11.6a: Example external-links File
The flags in the "ACTION" column are as follows:
- keep: if this file already exists in LOCALBASE, do not overwrite it
- replace: replace this file in LOCALBASE if it exists
- binary: this file is an executable
- nocrash: used for binary files; do not 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
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.
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 11.6b shows the firefox.desktop files for the firefox PBI:
Example 11.6b: firefox.desktop File
%%PBI_EXEDIR%% should reference the PBI's executable and any required switches.
For more details on the XDG menu specifications, please refer to the.
The xdg-mime/ directory is used to register file associations according to the. This requires the creation of an XML file. The example shown in Figure 11.6c adds the MIME information for gimp, so that it can be available as an application choice in a web browser:
Example 11.6c: Gimp MIME Info
List of Tables
- Table 11.6a: Commonly Used pbi.conf Variables