Difference between revisions of "Create PBIs/10.0"

From PC-BSD Wiki
Jump to: navigation, search
m (Protected "Create PBIs/10.0": Finalized/Published (‎[edit=sysop] (indefinite) ‎[move=sysop] (indefinite)))
 
(2 intermediate revisions by 2 users not shown)
Line 62: Line 62:
  
 
<!--T:21-->
 
<!--T:21-->
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.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.
  
 
<!--T:22-->
 
<!--T:22-->
{{Tbl-init|caption=11.7a: Commonly Used pbi.conf Variables}}
+
{{Tbl-init|caption=11.6a: Commonly Used pbi.conf Variables}}
 
!Variable  
 
!Variable  
 
!Description
 
!Description
Line 125: Line 125:
  
 
<!--T:25-->
 
<!--T:25-->
Example 11.7a shows an example usage:
+
Example 11.6a shows an example usage:
  
 
<!--T:26-->
 
<!--T:26-->
'''Example 11.7a: Example external-links File'''
+
'''Example 11.6a: Example external-links File'''
 
   
 
   
 
{{txtbox|box=<nowiki># Files to be Sym-Linked into the default LOCALBASE
 
{{txtbox|box=<nowiki># Files to be Sym-Linked into the default LOCALBASE
Line 183: Line 183:
  
 
<!--T:43-->
 
<!--T:43-->
Table 11.7b summarizes the variables that may be used in these scripts:
+
Table 11.6b summarizes the variables that may be used in these scripts:
  
 
<!--T:44-->
 
<!--T:44-->
{{Tbl-init|caption=11.7b Supported Variables}}
+
{{Tbl-init|caption=11.6b Supported Variables}}
 
!Variable
 
!Variable
 
!Description
 
!Description
Line 216: Line 216:
  
 
<!--T:46-->
 
<!--T:46-->
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:
+
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:
  
 
<!--T:47-->
 
<!--T:47-->
'''Example 11.7b: firefox.desktop File'''
+
'''Example 11.6b: firefox.desktop File'''
  
 
<!--T:48-->
 
<!--T:48-->
Line 256: Line 256:
  
 
<!--T:52-->
 
<!--T:52-->
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:
+
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.6c adds the MIME information for gimp, so that it can be available as an application choice in a web browser:
  
 
<!--T:53-->
 
<!--T:53-->
'''Example 11.7c: Gimp MIME Info'''
+
'''Example 11.6c: Gimp MIME Info'''
  
 
<!--T:54-->
 
<!--T:54-->
Line 307: Line 307:
  
 
<!--T:61-->
 
<!--T:61-->
{{note|icon48=Each time you run '''pbi_makeport''', it cleans up its environment, including all of the files that it downloaded and built. Since you may have to rebuild your PBI after testing it, you can save re-downloading and re-building all of these files again by including the '''--pkgdir <dir>''' option. You can manually remove that directory when you are finished if you need to save disk space.}}
+
{{note|icon32=Each time you run '''pbi_makeport''', it cleans up its environment, including all of the files that it downloaded and built. Since you may have to rebuild your PBI after testing it, you can save re-downloading and re-building all of these files again by including the '''--pkgdir <dir>''' option. You can manually remove that directory when you are finished if you need to save disk space.}}
  
 
<!--T:62-->
 
<!--T:62-->
Line 323: Line 323:
  
 
<!--T:66-->
 
<!--T:66-->
{{txtbox|pre|width=58%|box='''pbi_add -i /usr/local/my_pbis/cabextract-1.4-amd64.pbi'''
+
{{txtbox|box='''pbi_add -i /usr/local/my_pbis/cabextract-1.4-amd64.pbi'''<nowiki>
 
PBI Information for: cabextract-1.4-amd64
 
PBI Information for: cabextract-1.4-amd64
<nowiki>-----------------------------------------------------</nowiki>>
+
----------------------------------------------------->
 
Name: cabextract
 
Name: cabextract
 
RootInstall: NO
 
RootInstall: NO
Line 339: Line 339:
 
ArchiveSum: b75ef8fe699bfed50ad28b058f26af3e685915b5c2330951e2802f891a5b4a85
 
ArchiveSum: b75ef8fe699bfed50ad28b058f26af3e685915b5c2330951e2802f891a5b4a85
 
Signature: Not Signed
 
Signature: Not Signed
AutoUpdate: NO}}
+
AutoUpdate: NO</nowiki>}}
  
 
<!--T:67-->
 
<!--T:67-->

Latest revision as of 03:35, 29 January 2014


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.

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

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

[edit] 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® repository[1].

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

Table 11.6a: Commonly Used pbi.conf Variables [tables 1]
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

[edit] 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.6a shows an example usage:

Example 11.6a: 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

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

[edit] 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.6b summarizes the variables that may be used in these scripts:

Table 11.6b Supported Variables [tables 2]
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/

[edit] 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.6b shows the firefox.desktop files for the firefox PBI:

Example 11.6b: 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[2].

[edit] xdg-mime/

The xdg-mime/ directory is used to register file associations according to the freedesktop MIME specs[3]. 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

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>

[edit] 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 Panel → System Manager → 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. This chroot environment will be used for all PBI builds.

NOTE: Each time you run pbi_makeport, it cleans up its environment, including all of the files that it downloaded and built. Since you may have to rebuild your PBI after testing it, you can save re-downloading and re-building all of these files again by including the --pkgdir <dir> option. You can manually remove that directory when you are finished if you need to save disk space.

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

Once the process completes and a PBI is built successfully, it is very important to test the PBI, especially if the intent is to submit it for inclusion in AppCafe. Even quality control for your own sake is good because it will aid in learning the PBI build process. It will be easier to make corrections while everything is still fresh in your mind and little else has changed.


References


  1. https://github.com/pcbsd/pbi/tree/master/modules
  2. http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html
  3. http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html

List of Tables


  1. Table 11.6a: Commonly Used pbi.conf Variables
  2. Table 11.6b Supported Variables
Other languages:German 7% • ‎English 100%
Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox