Difference between revisions of "PBI Module Builder Guide/9.2"

From PC-BSD Wiki
Jump to: navigation, search
(Using EasyPBI: fix typo in filename for third screenshot)
(Module Components)
Line 233: Line 233:
{{Tbl-line|bg=ff|align=left|Set this to a number, the higher indicates greater priority and will be built before lower priority PBIs.}}  
{{Tbl-line|bg=ff|align=left|Set this to a number, the higher indicates greater priority and will be built before lower priority PBIs.}}  
{{Tbl-line|bg=ff|align=left|Set to YES to disable using tmpfs when doing auto-builds on a server.}}

Revision as of 07:49, 19 December 2011

(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 means that you should follow the instructions for the PBI format that you wish to create.


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 new GUI application created by Jesse Smith and Ken Moore. It streamlines the process of building a PBI from a FreeBSD port. Once this application is available in the FreeBSD ports tree, a PBI will be created. Until then, you can install this application as follows:

1. Use Control Panel -> System Manager -> System Packages to install the Development -> Development-Qt package.

2. Use AppCafe™ to install the subversion PBI.

3. Become the superuser and download the EasyPBI source after cding into your regular user's home directory. These commands are used to download and compile the EasyPBI program:

cd ~dru
svn co http://makeapbi.svn.sourceforge.net/svnroot/makeapbi EasyPBI
A    EasyPBI/defaulticon.png
A    EasyPBI/pbi.h
A    EasyPBI/mainwindow.h
A    EasyPBI/main.cpp
A    EasyPBI/EasyPBI.pro.user
A    EasyPBI/mainwindow.ui
A    EasyPBI/EasyPBI.pro
A    EasyPBI/pbi.cpp
A    EasyPBI/Makefile
A    EasyPBI/mainwindow.cpp
Checked out revision 10.
cd EasyPBI/
qmake-qt4 *.pro

4. If you wish to update EasyPBI to the latest version at a later date, run this command from your regular user's home directory:

svn update EasyPBI/

To run the program, give your user account permission to the EasyPBI contents, leave the superuser account, then run the EasyPBI executable as your regular user from the EasyPBI directory:

chown -R dru ~dru/EasyPBI

This will open the screen shown in Figure 10.7a. Depending upon whether or not ports is installed, you may first receive a pop-up message.

Figure 10.7a: EasyPBI Graphical Interface


The two main components to building a PBI are reflected in EasyPBI:

1. Create a module for the desired FreeBSD port: when you first start EasyPBI, it will check to see if the FreeBSD ports tree is installed into /usr/ports. If it is not, a pop-up message will indicate that you have a choice on how to install the ports tree. If you want the system ports tree to be available for any user, go to Control Panel -> System Manager -> Tasks -> Fetch System Ports Tree. 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.

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 multimedia/handbrake port has been selected and the fields other than "Port's website" have been auto-filled in.

Figure 10.7b: Reviewing the Port's Information


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

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. In this example, FreshPorts does not indicate the port's website, but the PBI request does.

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". Since handbrake is a command line program, this box is left unchecked in this example.

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 in EasyPBI and review the default settings. Figure 10.7d shows the default settings for our example PBI.

Figure 10.7d: The Build PBI Tab


The options in this tab allow you to do the following:

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

Change Directory:

Change File:


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.

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.

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 meta-data configuration directory which contains additional data used to supplement the port building and the final PBI file. This conf 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.

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 port's FreeBSD Makefile and pkg-descr so that you will know which values to input.

Table 10.7a: Commonly Used pbi.conf Variables

Tableneeds a caption: {{tbl-init|caption=a. is the caption}} Please use alternative templates. Please use alternative templates.
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. For example: 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 to be installed as user or root mode.
PBI_EXCLUDELIST= List of files / directories to exclude from the final archive, such as ./include ./share
PBI_AB_PRIORITY= Set this to a number, the higher indicates 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 you have set so that they 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 shows an example usage:

Example 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

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-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 summarizes the variables that may be used in these scripts:

Table Supported Variables

Tableneeds a caption: {{tbl-init|caption=a. is the caption}} Please use alternative templates. Please use alternative templates.
PBI_PROGNAME= Mandatory. Should be the same value as PORTNAME= in the port's Makefile, but capitalized.
PBI_PROGDIRNAME This is the name of the directory that is created for the PBI in the /usr/pbi/ directory.
(example: "firefox-amd64" for the 64-bit Firefox PBI)
PBI_PROGDIRPATH This is the full path to the PBI install directory
(example: "/usr/pbi/firefox-amd64/" for the 64-bit Firefox PBI)

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 shows the firefox.desktop files for the firefox PBI:

Example 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 adds the MIME information for gimp, so that it can be available as an application choice in a web browser:

Example 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.

Building PBIs for PC-BSD 8.x and Earlier

Earlier PBI versions were created using the PBI Builder Software. The PBI Builder Software automates the process of converting an existing FreeBSD package into a PBI. Anyone with a bit of time, the willingness to learn new things, and the desire to increase the number of PBIs available to PC-BSD users is welcome to create and submit new PBIs.

Installing the PBI Builder software relatively easy, simply download the tbz package for you architecture and version of PC-BSD 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

PBI Building Concepts

The PBI Builder software relies on the following concepts:

1. Modules:a directory containing the files needed by the PBI. The next section will explain how to configure a module for a new PBI.

2. PBI Sandbox: in order to create a clean build environment that does not affect the software running on the host system, all PBI 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 by using this command as the superuser:

# chroot /pbi-build/pbisandbox

3. Build command: once you have a module, simply cd into the pbi-build directory and specify which module to build. Depending upon the size of the application, the build may take some time to finish. The following example will build the firefox PBI:

# cd /pbi-build
# ./buildpbi.sh webbrowsers/firefox 

4. Recreate command: during the creation of a new module, it may become necessary to recreate the PBI file to test new configurations. If the PBI has already been compiled once, a change often 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 webbrowsers/firefox

5. 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.

Working with Modules

When starting the process of creating a new module for the PBI Builder, you should start with an existing module and modify it to suit your program's needs. You can either copy a module from /pbi-build/docs/module-examples, download a module from SVN, or download a template from SVN.

Modules currently in the PC-BSD Subversion repo can be browsed via the web.

To download a specific module, use the following commands, replacing "firefox" with the specific module you intend to checkout.

# cd /pbi-build/modules
# svn co svn://svn.pcbsd.org/pbibuild/modules/webbrowsers/firefox webbrowsers/firefox

If you wish to start with a blank module template, you may download by using these commands:

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

A proper module will contain several files and directories:

Required files / directories

  • pbi.conf: the main configuration file for the module.
  • copy-files: listing of the files and directories you wish to copy from the pbisandbox environment to your finished PBI file.
  • kmenu-dir: directory of configuration entries for the K menu.
  • overlay-dir: directory of contents to be applied to base PBI directory. Icons, PBI setup scripts, and most other files not added via copy-files are placed here.

Optional Files used on a per-need basis

  • build.sh: script to run after the port make and copy-files are processed.
  • preportmake.sh: script to run in pbisandbox prior to the port make being executed.
  • mime-dir: directory of mime entries for your PBI.

The pbi.conf file

This file is the first thing you read for each module. The available variables are explained with the example of "FireFox" below:

# Program Name
# The name of the PBI file being built
# Program Website
# Website of the program the module is building
# Program Author
# Who created / maintains the program being built
PROGAUTHOR="The Mozilla Foundation"
# Default Icon
# Relative to overlay-dir, the main icon you want to show up for this PBI
# Port we want to build
# The port the server will track to determine when it's time for a rebuild
# Set to "Auto or NONE" to have the PBI creator auto-populate libs or not
# This allows you to also use the autolibs/ directory in your overlay-dir as a location for extra
# library files
# PBI Update URL set to "" or the http:// URL of update checker
# Leave this as update.pbidir.com normally
# Other Ports we need built
# One per line, any additional ports that need to be built for this PBI
# Enter your custom make options here
# Options that will be put into the make.conf for the build of this port
# Options get inserted into the build's /etc/make.conf file and effect all the ports built for that PBI
# FBSD7BASE - (7.1 or 7.2)
# This variable can be used to set the specific version of FreeBSD this port needs to be compiled
# under. Use this is a port is known to not build / work when compiled on FreeBSD 7.0 (the default)
FBSD7BASE="7.2"; export FBSD7BASE
# This option determines if the pbi-builder will auto-copy files from the target port
# Can be set to YES/NO/FULL
# YES - Copy only target port files automatically
# No - Don't copy any target port files (will need to use copy-files config instead)
# FULL - Copy target port files, and recursive dependency files as well (Makes very large PBI)
# Can be set to OFF/NO to disable copying all files from ports made with the OTHERPORT variable
# Leaving this unset will have the builder auto-copy all files from OTHERPORT targets
# Set this variable to any target ports you want to autopopulate files from, in addition to
# the main target port
# List additional ports one-per-line
PBIAUTOPOPULATE_PORTS="/usr/ports/www/mplayer-plugin/" ; export PBIAUTOPOPULATE_PORTS
# By default the PBI will remove any xorg-fonts, and create a symlink to the the users system fonts
# Setting this to YES keeps the PBIs internal fonts and doesn't create a link
# By default the libGL* libraries will be removed from a PBI in order to use the systems libGL
# Set this to YES to keep the PBIs libGL* libraries, and not use the system's
# By default we prune any include/ files used for building,
# Set this to NO to keep any include/ directories in the resulting PBI
# By default we prune the python files used for building,
# Set this to NO to keep any python files in the resulting PBI
# By default we prune any perl files used for building,
# Set this to NO to keep any perl files in the resulting PBI
# By default we prune any doc files (such as man, info, share/doc)
# Set this to NO to keep any doc files in the resulting PBI
# Build Key - Change this to anything else to trigger a rebuild
#           - The rebuild will take place even if port is still the same ver
The copy-files configuration

This file is very straight forward, simply list the files you want to copy from the installed port, and where they should go in your PBI directory structure. The first argument should be the file/directory you wish to copy, and the 2nd argument will be the directory within the PBI it needs to be copied to.

Example copy-files from FileZilla:

/usr/local/bin/filezilla bin/
/usr/local/bin/fzsftp bin/
/usr/local/bin/gst-* bin/
/usr/local/bin/wxrc* bin/
/usr/local/bin/wxgtk2* bin/
/usr/local/share/filezilla share/filezilla

The preportmake.sh script

This script, if it present is run right before starting the "make install" of your port. This allows you to make modifications to the pbisandbox environment or to the port building source itself. Normally this won't be necessary, unless working with a very tricky program to get compiled.


# Script to grab the java files and place them in the right directory
# before starting the build
cd /usr/ports/distfiles
fetch ftp://ftp.pcbsd.org/pub/autobuildpkgs/javapack.tbz
tar xvjf javapack.tbz
cd /usr/ports/java/jdk16/
echo "#!/bin/sh
exit 0" > /usr/ports/java/jdk16/files/license.sh
cd /usr/ports/devel/automake15
make install clean

The build.sh script

Below is the example of the build.sh script, which runs after all the files have been copied to your PBI directory. This allows you to make mods to specific things for your PBI to work properly. In this example we modify the uninstall script to use the right version.

# PBI building script
# This will run after your port build is complete
# Build your PBI here, and exit 0 on success, or exit 1 on failure.
# Available Variables
#    PBIDIR = The location of where you can populate your PBI directory
# MODULEDIR = The location of the module directory for this PBI
#   PORTVER = Version number of the port we used to build

# Save the right version number in the removepbi.sh script
sed -e "s,CHANGEME,Firefox${PORTVER},g" ${PBIDIR}/scripts/removepbi.sh > /tmp/removepbi.sh
mv /tmp/removepbi.sh ${PBIDIR}/scripts/removepbi.sh
chmod 755 ${PBIDIR}/scripts/removepbi.sh

The kmenu-dir directory

In this directory you may make any number of files, which contain the .pbc configuration for your kmenu icons. This defines where you would like icons created for your users desktop

Example of kmenu-dir/firefox file:

ExePath: bin/firefox
ExeIcon: share/pixmaps/FireFox-128.png
ExeDescr: FireFox
ExeNoDesktop: 0
ExeNoMenu: 0
ExeNoCrashHandler: 0
ExeRunRoot: 0
ExeRunShell: 0
ExeNotify: 1
ExeLink: 0
ExeWebLink: 0
ExeTaskbar: 0
ExeOwndir: 1
ExeKdeCat: Internet

Line-By-Line description of each entry:

ExePath: bin/firefox

This line indicates the binary / script we want this icon to run when the user clicks it. This is relative to the PBI directory, so we use bin/firefox

ExeIcon: share/pixmaps/FireFox-128.png

This is the icon you want to show up for this program, again it is relative to the PBI directory

ExeDescr: FireFox

This would be the name of the icon in the kmenu or on the users desktop.

ExeNoDesktop: 0

This allows you to disable creating a desktop icon for this entry. Set it to '0' if you want a desktop icon, or '1' if you don't wish an icon.

ExeNoMenu: 0

This allows you to disable creating a kmenu icon for this entry. Set it to '0' if you want a kmenu icon, or '1' if you don't wish an icon.

ExeNoCrashHandler: 0

This option enables / disables the usage of the PC-BSD CrashHandler program. This dialog warns the user that the application has crashed if it returns status non-zero (0), and provides the option to save the output of stdout and stderr from the application. Setting this to "1" disables the CrashHandler helper, which is useful for programs which normally return non-0, such as Window Managers and various apps.

ExeRunRoot: 0

This indicates if you want your program to be run as "root" when the user clicks it. Set it to '0' to run as a regular user, or '1' to run kdesu and switch to "root" Set this to '0'

ExeRunShell: 0

This indicates if you want your program to be executed in a console session, which may be useful for command-line applications. Set it to '0' if you dont want it to run in console, or set it to '1' if you do.

ExeNotify: 1

This indicates if you want to enable launch feedback in KDE, which is the bouncing icon, showing that the program is loading. Set it to '0' to disable launch feedback, or set it to '1' if you want this enabled. Normally it is best to leave this enabled.

ExeLink: 0

This is used to indicate if the ExePath variable was set to a local file / document you want opened with konqueror insetead of just being "run". This is useful for README type documents. Set this to '1' if you want your document opened with konq, or '0' to just run it as normal.

ExeWebLink: 0

This is similar to above, and instead indicates that the ExePath being opened is actual a web URL. Set this to '1' to open it the ExePath with Konq, or '0' to just run it as normal.

ExeTaskbar: 0

This indicates if you want this application icon added to the taskbar. Set it to '1' to add it, or '0' to leave it disabled. (THIS FEATURE IS CURRENTLY UNAVAILABLE, BUT WILL BE ADDED DOWN THE ROAD)

ExeOwndir: 1

This option is used to specify where you want your Kmenu icon to be placed, and may be set to 0, 1, 2

0 = Place kmenu icon directory in top level. 
    I.E.  Kmenu -> Firefox -> Firefox
1 = Place kmenu icon in its own directory in the sub category indicated by ExeKdeCat:
    I.E.  Kmenu -> Internet -> Firefox -> Firefox
2 = Place kmenu icon directly in the sub category indicated by ExeKdeCat:  
    I.E.  Kmenu -> Internet -> Firefox

ExeKdeCat: Internet

This allows you to choose a kmenu sub-directory to place your icons / directory into, when ExeOwnDir is set to 1 or 2. Available options are:

ExeKdeCat: Development
ExeKdeCat: Editors
ExeKdeCat: Edutainment/Languages
ExeKdeCat: Edutainment/Math
ExeKdeCat: Edutainment/Misc
ExeKdeCat: Edutainment/Science
ExeKdeCat: Edutainment/Teaching
ExeKdeCat: Games/Arcade
ExeKdeCat: Games/Board
ExeKdeCat: Games/Card
ExeKdeCat: Games/Kidsgames
ExeKdeCat: Games/TacticStrategy
ExeKdeCat: Games
ExeKdeCat: Graphics
ExeKdeCat: Internet
ExeKdeCat: Multimedia
ExeKdeCat: Office
ExeKdeCat: System
ExeKdeCat: Toys
ExeKdeCat: Utilities

The mime-dir directory

This directory allows to you specify mime types for your applications defined in the kmenu-dir entries.

Example of mime-dir/exe file:

MimeExt: *.exe; *.EXE
MimeIcon: win_apps.png
MimeProg: 0

The only catch to this is to note that the "MimeProg: 0" is a pointer to a file in the kmenu-dir structure. In this case you would have to ensure that the application you want to open .exe files gets added first to the template the server creates. Files in the kmenu-dir are added in the order of a "ls" listing, so if you have a wine-exe entry, you may wish to rename it to 00wine-exe to ensure it is added first, which would make this MimeProg: 0 entry work with it.

If you have more than 1 mime-type, you would then increment the MimeProg: 0 number to MimeProg: 1, MimeProg: 2, and so forth. Then you would do the same with your kmenu-dir entries, such as 00wine-exe, 01wine-bat, 02wine-msi

The overlay-dir directory

This folder contains any of the files you wish placed into your PBI program directory. Here is an example from firefox:

PBI.FirstRun.sh         autolibs                lib
PBI.RemoveScript.sh     bin                     scripts
PBI.SetupScript.sh      header.png              share

In this example you see we have added our PBI.* setup scripts, and the custom graphics we want for the PBI installer. You may also create directories that will be populated with the copy-files configuration, such as share/ or others you may need.

Useful Tips

If the program uses the python programming language: use [PBIPRUNEPYTHON="NO" ; export PBIPRUNEPYTHON] (usually the file is called py-(something) if that file is written in python)

If the program uses the perl programming language: use [PBIPRUNEPERL="NO" ; export PBIPRUNEPERL] (harder to spot, usually the filename has "perl" in it somewhere)

The installed program does not work: this is usually because the python or perl option was not set appropriately. This is only noticed at runtime because after building, python and perl files are removed unless instructed otherwise.

If your program path needs to be /usr/local/sbin: first, make a kmenu-dir entry similar to the one used by cabextract. Next, make sure that the "ExeNoDesktop" and "ExeNoMenu" options are both set to "1". Then, in your PBI.SetupScript.sh, you can symlink the wrapper script into /Programs/bin as in this example.

If the underlying port pauses to wait for user acceptance of license agreement: put this setting into the MAKEOPTS variable:


Don't forget to include the license text in the file overlay-dir/LICENSE so the user can read and accept the license during the PBI installation.

If you don't have reliable Internet access and want to avoid running portsnap and build a PBI with pre-fetched distfiles: use this variable in /pbi-build/conf/pbibuild.conf:


Place all of your distfiles into /pbi-build/distfiles; with this variable set, that directory will be nullfs mounted into the PBI sandbox when doing builds.

How does the builder know which port the module is associated with?

The PBI build system will look at the module path first, so if in SVN we are using the module www/firefox, it'll look for a port at www/firefox. However, in some cases a module doesn't use the same port or directory name. In that case, set this variable:

# The target port we are building

That'll let the build server know which specific port this is building.

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
Personal tools