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

From PC-BSD Wiki
Jump to: navigation, search
m
(39 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<noinclude>{{NavHeader|back=Test PBIs|forward=Purchase PC-BSD Swag|custompagename=Create PBIs}}</noinclude>
+
<noinclude>{{NavHeader|back=Test PBIs|forward=Purchase PC-BSD® Swag|custompagename=Create PBIs}}</noinclude>
  
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.
+
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.  
+
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 [[Using AppCafe® | AppCafe®]] utility or from the command line using [[PBI Manager]].
+
Once a PBI is created, it can be installed using the graphical [[Using AppCafe® | 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.
+
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 {{citelink|url=http://www.freshports.org|txt=FreshPorts.org}}. If a port does not exist, you can issue a port request at the PC-BSD® Port Requests forum using {{citelink|url=http://forums.pcbsd.org/showthread.php?t=13743|txt=these instructions}}. Alternately, if you have ported software before, the {{citelink|fbsdph||txt=Porters Handbook}} contains detailed instructions for porting software to FreeBSD.
  
=== Building PBIs for PC-BSD 9.x and higher ===
+
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:
 +
# '''EasyPBI:''' provides a graphical interface and is available in Control Panel. See the [[EasyPBI]] section of the Handbook for instructions on how to use this utility.<br>
 +
# '''pbi_makeport:''' provides a command line utility.
  
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.
+
This section explains the components of a PBI module, demonstrates how to use the '''pbi_makeport''' utility, and provides some troubleshooting tips.
  
Two utilities are available for converting FreeBSD ports into PBIs:  
+
'''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.
  
1. '''EasyPBI:''' provides a graphical interface and is available in Control Panel. See the [[EasyPBI]] section of the Handbook for instructions on how to use this utility.
+
=== PBI Module Components ===
  
2. '''pbi_makeport:''' provides a command line utility.  
+
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.
  
This section demonstrates how to use the '''pbi_makeport''' utility, explains the components of a PBI module, and provides some troubleshooting tips.
+
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:
  
'''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.
+
'''mkdir -p /usr/local/my_pbis/www/firefox'''
  
==== Creating a New PBI with '''pbi_makeport''' ====
+
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.
  
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.
+
==== LICENSE File ====
  
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.  
+
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.
  
Examples of 9.x modules can be found at {{citelink|url=http://trac.pcbsd.org/browser/pcbsd/current/src-sh/pbi-manager/module-examples|Examples in Subversion}}.
+
==== pbi.conf ====
  
FreeBSD ports may contain build dependencies, runtime dependencies, and required libraries. When building a PBI, '''pbi_makeport''' automatically
+
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 {{citelink|url=http://trac.pcbsd.org/browser#pbi/modules|txt=the PC-BSD® trac repository}}.
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 ====
+
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.
  
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%%''.  
+
#!/bin/sh
 +
# PBI Build Configuration
 +
# Place over-rides and settings here
 +
#
 +
# XDG Desktop Menu Spec:
 +
# <nowiki>http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html</nowiki>
 +
##############################################################################
 +
# Program Name
 +
PBI_PROGNAME=<span style="color:#ff0000">"Firefox"</span>
  
1. '''LICENSE File'''
+
# Program Website
 +
PBI_PROGWEB=<span style="color:#ff0000"><nowiki>"http://www.mozilla.com"</nowiki></span>
  
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.
+
# Program Author / Vendor
 +
PBI_PROGAUTHOR=<span style="color:#ff0000">"The Mozilla Foundation"</span>
  
2. '''pbi.conf'''
+
# Default Icon (Relative to %%PBI_APPDIR%% or resources/)
 +
PBI_PROGICON=<span style="color:#ff0000">"share/pixmaps/FireFox-128.png"</span>
  
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 {{citelink|url=http://trac.pcbsd.org/browser#pbi/modules|the PC-BSD trac repository}}. Here is an example of the ''pbi.conf'' file for firefox:
+
# The target port we are building
<nowiki>
+
PBI_MAKEPORT=<span style="color:#ff0000">"www/firefox"</span>  
#!/bin/sh
+
# 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
+
# Additional options for make.conf
PBI_PROGNAME="Firefox"
+
  <span style="color:#ff0000">PBI_MAKEOPTS="PACKAGE_BUILDING=Y</span>
   
+
  <span style="color:#ff0000">WITH_CUPS=yes</span>
# Program Website
+
<span style="color:#ff0000">WITH_GECKO=libxul"</span>
PBI_PROGWEB="http://www.mozilla.com"
+
+
# Program Author / Vendor
+
PBI_PROGAUTHOR="The Mozilla Foundation"
+
+
# Default Icon (Relative to %%PBI_APPDIR%% or resources/)
+
PBI_PROGICON="share/pixmaps/FireFox-128.png"
+
   
+
# The target port we are building
+
PBI_MAKEPORT="www/firefox"
+
+
# Additional options for make.conf
+
PBI_MAKEOPTS="PACKAGE_BUILDING=Y
+
WITH_CUPS=yes
+
WITH_GECKO=libxul"
+
+
# Ports to build before / after
+
PBI_MKPORTBEFORE=""
+
PBI_MKPORTAFTER="audio/esound x11-fonts/dejavu x11-themes/qtcurve-gtk2 devel/gconf2 www/firefox-i18n"
+
  
# Exclude List
+
  # Ports to build before / after
PBI_EXCLUDELIST="./include ./share/doc"
+
PBI_MKPORTBEFORE=<span style="color:#ff0000">""</span>
   
+
  PBI_MKPORTAFTER=<span style="color:#ff0000">"audio/esound x11-fonts/dejavu x11-themes/qtcurve-gtk2 devel/gconf2 x11/libXScrnSaver www/gecko-mediaplayer www/firefox-i18n"</span>
# Increment to trigger rebuild of PBI on build servers
+
 
PBI_BUILDKEY="04"
+
# do not include the PBI_BUILDKEY or PBI_AB_PRIORITY options
   
+
  # as the correct values will be added for you when the PBI is added to the build server
# This app needs to install as root
+
PBI_BUILDKEY="06"
PBI_REQUIRESROOT="YES"
+
  PBI_AB_PRIORITY="50"
   
+
 
# Set the priority of this build
+
export PBI_PROGNAME PBI_PROGWEB PBI_PROGAUTHOR PBI_PROGICON PBI_MAKEPORT PBI_MAKEOPTS PBI_MKPORTBEFORE PBI_MKPORTAFTER PBI_BUILDKEY PBI_AB_PRIORITY
PBI_AB_PRIORITY="50"
+
 
   
+
Table 11.7a 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.
# Set the files we want to exclude from the shared hashdir
+
PBI_HASH_EXCLUDES="lib/firefox/firefox"
+
   
+
export PBI_PROGNAME PBI_PROGWEB PBI_PROGAUTHOR PBI_PROGICON PBI_MAKEPORT PBI_MAKEOPTS  
+
PBI_MKPORTBEFORE PBI_MKPORTAFTER PBI_BUILDKEY PBI_REQUIRESROOT PBI_EXCLUDELIST</nowiki>
+
+
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'''
+
'''Table 11.7a: Commonly Used pbi.conf Variables'''
  
 
{{Tbl-init}}
 
{{Tbl-init}}
Line 114: Line 93:
 
|-
 
|-
 
{{Tbl-line|align=left|'''PBI_PROGICON<nowiki>=</nowiki>'''}}
 
{{Tbl-line|align=left|'''PBI_PROGICON<nowiki>=</nowiki>'''}}
{{Tbl-line|align=left|mandatory path, relative to %PBI_APPDIR%%, to application icon file in png format}}
+
{{Tbl-line|align=left|mandatory path, relative to ''%%PBI_APPDIR%%'', to application icon file in ''.png'' format}}
 
|-
 
|-
 
{{Tbl-line|bg=ff|align=left|'''PBI_PROGREVISION<nowiki>=</nowiki>'''}}
 
{{Tbl-line|bg=ff|align=left|'''PBI_PROGREVISION<nowiki>=</nowiki>'''}}
Line 123: Line 102:
 
|-
 
|-
 
{{Tbl-line|bg=ff|align=left|'''PBI_MAKEOPTS<nowiki>=</nowiki>'''}}
 
{{Tbl-line|bg=ff|align=left|'''PBI_MAKEOPTS<nowiki>=</nowiki>'''}}
{{Tbl-line|bg=ff|align=left|optional; set this to the options that you want saved into ''make.conf'' for the port building process (e.g. WITH_CUPS<nowiki>=</nowiki>YES)}}
+
{{Tbl-line|bg=ff|align=left|optional; set this to the options that you want saved to ''make.conf'' for the port building process (e.g. WITH_CUPS<nowiki>=</nowiki>YES)}}
 
|-
 
|-
 
{{Tbl-line|align=left|'''PBI_MKPORTBEFORE<nowiki>=</nowiki>'''}}
 
{{Tbl-line|align=left|'''PBI_MKPORTBEFORE<nowiki>=</nowiki>'''}}
{{Tbl-line|align=left|optional; port(s) to build before starting the target port PBI_MAKEPORT}}
+
{{Tbl-line|align=left|optional; port(s) to build before building the PBI}}
 
|-
 
|-
 
{{Tbl-line|bg=ff|align=left|'''PBI_MKPORTAFTER<nowiki>=</nowiki>'''}}
 
{{Tbl-line|bg=ff|align=left|'''PBI_MKPORTAFTER<nowiki>=</nowiki>'''}}
{{Tbl-line|bg=ff|align=left|optional; port(s) to build after finishing the target port PBI_MAKEPORT}}
+
{{Tbl-line|bg=ff|align=left|optional; port(s) to build after building the PBI}}
 
|-
 
|-
 
{{Tbl-line|align=left|'''PBI_BUILDKEY<nowiki>=</nowiki>'''}}
 
{{Tbl-line|align=left|'''PBI_BUILDKEY<nowiki>=</nowiki>'''}}
Line 154: Line 133:
 
|}
 
|}
  
3. '''external-links'''
+
==== 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:
+
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 10.7a: Example external-links File'''
+
Example 11.7a shows an example usage:
 +
 
 +
'''Example 11.7a: Example external-links File'''
 
   
 
   
 
  <nowiki>
 
  <nowiki>
Line 174: Line 155:
 
The flags in the ACTION column are as follows:
 
The flags in the ACTION column are as follows:
  
* '''keep''': if this file already exists in LOCALBASE, don't overwrite it
+
* '''keep''': if this file already exists in LOCALBASE, do not overwrite it
  
 
* '''replace''': replace this file in LOCALBASE if it exists
 
* '''replace''': replace this file in LOCALBASE if it exists
Line 180: Line 161:
 
* '''binary''': this file is an executable
 
* '''binary''': this file is an executable
  
* '''nocrash''': used for binary files; don't display crash handler if program exits with non-0 status
+
* '''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
 
* '''linux''': used for binary files; indicates that this is a Linux application, and needs to be run with Linux compat
  
4. '''resources/'''
+
==== 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.  
+
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/'''
+
==== scripts/ ====
  
 
This directory can contain the following scripts:
 
This directory can contain the following scripts:
Line 202: Line 183:
 
* '''pre-remove.sh''': script run before deletion of the PBI file
 
* '''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 11.7b summarizes the variables that may be used in these scripts:
  
'''Table 10.7b Supported Variables
+
'''Table 11.7b Supported Variables
  
 
{{Tbl-init}}
 
{{Tbl-init}}
{{Tbl-title|width=15%|'''Variable'''}}
+
{{Tbl-title|width=15%|'''Variable'''}}
 
{{Tbl-title|width=85%|'''Description'''}}
 
{{Tbl-title|width=85%|'''Description'''}}
 
|-
 
|-
Line 231: Line 212:
 
{{Tbl-line|bg=ff|align=left|the binary wrapper directory, typically ''/usr/pbi/<pbidir>/.sbin/'' }}
 
{{Tbl-line|bg=ff|align=left|the binary wrapper directory, typically ''/usr/pbi/<pbidir>/.sbin/'' }}
 
|-
 
|-
|}      
+
|}
  
6. '''xdg-menu/ and xdg-desktop/'''
+
==== 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:
+
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.7b shows the ''firefox.desktop'' files for the firefox PBI:
  
'''Example 10.7b: firefox.desktop File'''
+
'''Example 11.7b: firefox.desktop File'''
 
   
 
   
 
  '''more xdg-menu/firefox.desktop'''
 
  '''more xdg-menu/firefox.desktop'''
Line 266: Line 247:
 
%%PBI_EXEDIR%% should reference the PBI's executable and any required switches.
 
%%PBI_EXEDIR%% should reference the PBI's executable and any required switches.
  
For more details on the XDG menu specifications, please refer to the {{citelink|url=http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html|freedesktop specifications}}.  
+
For more details on the XDG menu specifications, please refer to the {{citelink|url=http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html|txt=freedesktop specifications}}.
  
7. '''xdg-mime/'''
+
==== xdg-mime/ ====
  
The ''xdg-mime/'' directory is used to register file associations according to the {{citelink|url=http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html|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:
+
The ''xdg-mime/'' directory is used to register file associations according to the {{citelink|url=http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html|txt=freedesktop MIME specs}}. This requires the creation of an XML file. The example shown in Figure 11.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'''
+
'''Example 11.7c: Gimp MIME Info'''
  
 
  '''more xdg-mime/gimp-xdg.xml'''
 
  '''more xdg-mime/gimp-xdg.xml'''
Line 278: Line 259:
 
  <mime-info xmlns='<nowiki>http://www.freedesktop.org/standards/shared-mime-info</nowiki>'>
 
  <mime-info xmlns='<nowiki>http://www.freedesktop.org/standards/shared-mime-info</nowiki>'>
 
   <mime-type type="application/x-gimp">
 
   <mime-type type="application/x-gimp">
     <comment>Gimp - XCF File</comment>
+
     <comment>Gimp File</comment>
 
   <glob weight="100" pattern="*.xcf"/>
 
   <glob weight="100" pattern="*.xcf"/>
 
   <glob weight="100" pattern="*.XCF"/>
 
   <glob weight="100" pattern="*.XCF"/>
Line 284: Line 265:
 
  </mime-info>
 
  </mime-info>
  
==== Useful Tips ====
+
=== Creating a New PBI with '''pbi_makeport''' ===
 +
 
 +
Once you have created the files needed by your PBI module, use the built-in [[PBI Manager#pbi makeport(1)|'''pbi_makeport''']] command to convert the FreeBSD port to a PBI module.
 +
 
 +
Before attempting to build the PBI, make sure that the FreeBSD ports collection is installed. If ''/usr/ports/'' does not exist or is empty, the ports collection is not installed. To install the ports collection either use [[Control Panel]] ➜ [[System Manager]] ➜ [[System Manager#Install FreeBSD Source and Ports|Tasks]] ➜ Fetch Ports Tree or type '''portsnap fetch extract'''.
 +
 
 +
To build the PBI, make sure that you are in ''%%PBI_APPDIR%%'' then specify where to place the built PBI and the port to build the PBI from, as seen in this example:
 +
 
 +
'''pbi_makeport -o /usr/local/my_pbis archivers/cabextract'''
 +
Fetching FreeBSD chroot environment... This may take a while...
 +
<snip build output>
 +
===>  Compressing manual pages for cabextract-1.4
 +
===>  Registering installation for cabextract-1.4
 +
===>  Cleaning for cabextract-1.4
 +
Checking for Linux libraries to copy...
 +
Creating PBI: cabextract-1.4
 +
Creating Stage Dir: /usr/pbi/cabextract-amd64/.stagedir
 +
Creating external link entries...
 +
Creating xdg scripts...
 +
Creating install script...
 +
Creating deinstall script...
 +
Creating hash list...
 +
Creating compressed archive...
 +
Created PBI: /pbiout/cabextract-1.4-amd64.pbi
 +
Cleaning /usr/pbi/cabextract-amd64
 +
Cleaning /usr/pbi/cabextract-amd64.chroot
 +
 
 +
The first time you run the '''pbi_makeport''' command, a clean chroot environment will automatically download and install, which may take a few minutes. This chroot environment will be used for all PBI builds.
 +
 
 +
FreeBSD ports may contain build dependencies, runtime dependencies, and required libraries. When building a PBI, '''pbi_makeport''' automatically compiles all of the required dependencies. When the build is finished, it 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.
 +
 
 +
After the PBI build has finished, two files should be created in the specified directory: the PBI itself and its SHA256 checksum.
 +
 
 +
'''ls /usr/local/my_pbis'''
 +
cabextract-1.4-amd64.pbi        cabextract-1.4-amd64.pbi.sha256
 +
 
 +
Use the '''pbi_add''' command to verify the information about the PBI.
 +
 
 +
'''pbi_add -i /usr/local/my_pbis/cabextract-1.4-amd64.pbi'''
 +
PBI Information for: cabextract-1.4-amd64
 +
-----------------------------------------------------
 +
Name: cabextract
 +
RootInstall: NO
 +
Version: 1.4
 +
Built: 20120829 144309
 +
Prefix: /usr/pbi/cabextract-amd64
 +
Author:
 +
Website:
 +
Arch: amd64
 +
FbsdVer: 9.1-RELEASE
 +
CreatorVer: 1.0
 +
ArchiveCount: 498
 +
ArchiveSum: b75ef8fe699bfed50ad28b058f26af3e685915b5c2330951e2802f891a5b4a85
 +
Signature: Not Signed
 +
AutoUpdate: NO
 +
 
 +
=== Testing the PBI ===
 +
 
 +
Once your PBI has built, test the PBI to ensure that it installs and that the application works.
  
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''.
+
As the superuser, use the '''pbi_add''' command with the '''--no-checksig''' option:
  
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 {{citelink|url=http://trac.pcbsd.org/browser/pbi/modules/games/fretsonfire/scripts/post-install.sh?rev=13019|frets on fire}}.
+
'''pbi_add --no-checksig /path_to_pbi'''
  
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
+
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.
can get some interesting errors about missing files.
+
  
=== Getting Help ===
+
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 {{citelink|url=http://lists.pcbsd.org/mailman/listinfo/pbi-dev|PBI Developers mailing list}} can help if you:
+
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 {{citelink|url=http://trac.pcbsd.org/browser/pbi/modules/games/fretsonfire/scripts/post-install.sh?rev=13019|txt=frets on fire}}.
  
* get stuck building a PBI
+
If the application starts and it is a GUI application, go through the various menus to see if they produce any errors.
  
* need to ask a question about your PBI
+
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 the {{citelink|url=http://lists.pcbsd.org/mailman/listinfo/pbi-dev|txt=pbi-dev mailing list}}.
  
* are ready to submit a new module
+
If your PBI works and you would like to submit its module to be included on the build server, compress it after '''cd'''ing into your module directory (%%PBI_APPDIR%%):
  
* find a bug in an existing PBI
+
'''tar tzvf .'''
  
* have a bugfix for an existing PBI
+
This should result in a file named ''your_pbi_name.tar.gz.'' Send this file to the {{citelink|url=http://lists.pcbsd.org/mailman/listinfo/pbi-dev|txt=pbi-dev mailing list}}.
  
 
<noinclude>{{refheading}}</noinclude>
 
<noinclude>{{refheading}}</noinclude>
 
<noinclude>
 
<noinclude>
 
[[category:handbook]]
 
[[category:handbook]]
[[category:Supporting PC-BSD]]
+
[[category:Supporting PC-BSD®]]
 
[[category:PBI Module Builder Guide]]
 
[[category:PBI Module Builder Guide]]
 
[[category:Create PBIs]]
 
[[category:Create PBIs]]
 
</noinclude>
 
</noinclude>

Revision as of 15:29, 3 September 2012

(Sorry for the inconvenience)

Contents

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:

  1. EasyPBI: provides a graphical interface and is available in Control Panel. See the EasyPBI section of the Handbook for instructions on how to use this utility.
  2. pbi_makeport: provides a command line utility.

This section explains the components of a PBI module, demonstrates how to use the pbi_makeport utility, 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.

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:

mkdir -p /usr/local/my_pbis/www/firefox

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.

LICENSE File

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.

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 the PC-BSD® trac repository[4].

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.

#!/bin/sh
# 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
PBI_PROGNAME="Firefox" 
# Program Website
PBI_PROGWEB="http://www.mozilla.com" 
# Program Author / Vendor
PBI_PROGAUTHOR="The Mozilla Foundation"
# Default Icon (Relative to %%PBI_APPDIR%% or resources/)
PBI_PROGICON="share/pixmaps/FireFox-128.png" 
# The target port we are building
PBI_MAKEPORT="www/firefox" 
# Additional options for make.conf
PBI_MAKEOPTS="PACKAGE_BUILDING=Y
WITH_CUPS=yes
WITH_GECKO=libxul" 
# Ports to build before / after
PBI_MKPORTBEFORE=""
PBI_MKPORTAFTER="audio/esound x11-fonts/dejavu x11-themes/qtcurve-gtk2  devel/gconf2 x11/libXScrnSaver www/gecko-mediaplayer www/firefox-i18n"
# do not include the PBI_BUILDKEY or PBI_AB_PRIORITY options
# as the correct values will be added for you when the PBI is added to the build server
PBI_BUILDKEY="06"
PBI_AB_PRIORITY="50"
export PBI_PROGNAME PBI_PROGWEB PBI_PROGAUTHOR PBI_PROGICON PBI_MAKEPORT PBI_MAKEOPTS PBI_MKPORTBEFORE PBI_MKPORTAFTER PBI_BUILDKEY PBI_AB_PRIORITY

Table 11.7a 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.

Table 11.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 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

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. This file is usually not needed as most binaries and files are auto-detected and automatically placed in the LOCALBASE.

Example 11.7a shows an example usage:

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

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.

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

Table 11.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/

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

Example 11.7b: firefox.desktop File

more xdg-menu/firefox.desktop
#!/usr/bin/env xdg-open
[Desktop Entry]
Value=1.0
Type=Application
Name=FireFox
GenericName=FireFox
Exec=%%PBI_EXEDIR%%/firefox %U
Path=%%PBI_APPDIR%%
Icon=%%PBI_APPDIR%%/share/pixmaps/FireFox-128.png
StartupNotify=true
Categories=Network;

more xdg-desktop/firefox.desktop
#!/usr/bin/env xdg-open
[Desktop Entry]
Value=1.0
Type=Application
Name=FireFox
GenericName=FireFox
Exec=%%PBI_EXEDIR%%/firefox %U
Path=%%PBI_APPDIR%%
Icon=%%PBI_APPDIR%%/share/pixmaps/FireFox-128.png
StartupNotify=true 

%%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[5].

xdg-mime/

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

Example 11.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 File</comment>
  <glob weight="100" pattern="*.xcf"/>
  <glob weight="100" pattern="*.XCF"/>
 </mime-type>
</mime-info>

Creating a New PBI with pbi_makeport

Once you have created the files needed by your PBI module, use the built-in pbi_makeport command to convert the FreeBSD port to a PBI module.

Before attempting to build the PBI, make sure that the FreeBSD ports collection is installed. If /usr/ports/ does not exist or is empty, the ports collection is not installed. To install the ports collection either use Control PanelSystem ManagerTasks ➜ Fetch Ports Tree or type portsnap fetch extract.

To build the PBI, make sure that you are in %%PBI_APPDIR%% then specify where to place the built PBI and the port to build the PBI from, as seen in this example:

pbi_makeport -o /usr/local/my_pbis archivers/cabextract
Fetching FreeBSD chroot environment... This may take a while...
<snip build output>
===>   Compressing manual pages for cabextract-1.4
===>   Registering installation for cabextract-1.4
===>  Cleaning for cabextract-1.4
Checking for Linux libraries to copy...
Creating PBI: cabextract-1.4
Creating Stage Dir: /usr/pbi/cabextract-amd64/.stagedir
Creating external link entries...
Creating xdg scripts...
Creating install script...
Creating deinstall script...
Creating hash list...
Creating compressed archive...
Created PBI: /pbiout/cabextract-1.4-amd64.pbi
Cleaning /usr/pbi/cabextract-amd64
Cleaning /usr/pbi/cabextract-amd64.chroot

The first time you run the pbi_makeport command, a clean chroot environment will automatically download and install, which may take a few minutes. This chroot environment will be used for all PBI builds.

FreeBSD ports may contain build dependencies, runtime dependencies, and required libraries. When building a PBI, pbi_makeport automatically compiles all of the required dependencies. When the build is finished, it 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.

After the PBI build has finished, two files should be created in the specified directory: the PBI itself and its SHA256 checksum.

ls /usr/local/my_pbis
cabextract-1.4-amd64.pbi        cabextract-1.4-amd64.pbi.sha256

Use the pbi_add command to verify the information about the PBI.

pbi_add -i /usr/local/my_pbis/cabextract-1.4-amd64.pbi
PBI Information for: cabextract-1.4-amd64
-----------------------------------------------------
Name: cabextract
RootInstall: NO
Version: 1.4
Built: 20120829 144309
Prefix: /usr/pbi/cabextract-amd64
Author: 
Website: 
Arch: amd64
FbsdVer: 9.1-RELEASE
CreatorVer: 1.0
ArchiveCount: 498
ArchiveSum: b75ef8fe699bfed50ad28b058f26af3e685915b5c2330951e2802f891a5b4a85
Signature: Not Signed
AutoUpdate: NO

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[7].

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 the pbi-dev mailing list[8].

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

tar tzvf .

This should result in a file named your_pbi_name.tar.gz. Send this file to the pbi-dev mailing list[8].

References


  1. http://www.freshports.org
  2. http://forums.pcbsd.org/showthread.php?t=13743
  3. http://www.freebsd.org/doc/en/books/porters-handbook/
  4. http://trac.pcbsd.org/browser#pbi/modules
  5. http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html
  6. http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html
  7. http://trac.pcbsd.org/browser/pbi/modules/games/fretsonfire/scripts/post-install.sh?rev=13019
  8. 8.0 8.1 http://lists.pcbsd.org/mailman/listinfo/pbi-dev