Using PBI Manager

From PC-BSD Wiki
Revision as of 13:41, 14 March 2011 by Drulavigne (Talk | contribs)

Jump to: navigation, search
Return to Table of Contents
Previous: Using Software Manager
Next: Using Ports Jail to Manage FreeBSD Packages and Ports


PC-BSD 9.0 introduced PBI Manager, a suite of command line utilities for managing PBIs.

Contents

New Features

  • delta PBIs: when upgrading, you only have to download the changes, not the whole PBI (saving time and bandwidth)
  • shared libraries: PBIs are much smaller now as libraries are shared; uninstalling a PBI is smart, meaning it won't uninstall a library needed by another application

Additional Resources:

The PBI Format Re-implemented for Free/PC-BSD

The PBI Format for 9.0 and Beyond

Underlying Structure

The underlying files used by PBI Manager are as follows:

/usr/local/etc/pbi.conf

Location of the PBI Manager configuration file which contains the following variables:

PBI_UPDATEURL: location of the PBI update server. PBI Manager will look here first to see if an update is available; if it cannot find an update for the PBI, it will download the entire PBI. Updates to PBIs are much smaller, saving network bandwidth and download time.

PBI_PUBKEYS: every PBI is digitally signed in order to verify that it is the original, rather than a trojanned, version. This is the location of the OpenSSL public key used to verify the signature.

PBI_MIRROR: the location of the PBI mirror.

/var/db/pbi-keys/ default location of the OpenSSL public key used to verify the PBI's digital signature.

/usr/local/share/pbi-manager/convertoldmod.sh script which can be used to convert an existing PBI module to the new 9.x format.

/usr/local/etc/rc.d/ldpbiconfig rc script which enable's a PBI's ldconfig(8) hints file.

Command Line Utilities

The pbi_ tools will be able to build PBIs without the need for the PBI Builder package anymore, however they will not auto-generate a module for you. Luckily the new module format is really easy, just a pbi.conf file, and desktop files are usually all thats needed. Those looking for a utility to automate module creation can try the Make-A-PBI command line utility. (make sure the tool modified for 9.0 format and to manually ask questions from the user, spit out the pbi.conf/desktop files, and run "pbi_makeport <flags> to test the resulting module file)

PBI Manager's funcitionality is provided by a suite of command line utilities which are located in /usr/local/sbin/. Each of these utilities can be run as a stand-alone program. You can recognize these utilities as they all begin with "pbi". This section briefly describes each utility--refer to a utility's man page for more information.

pbi_add(1)

similar to FreeBSD's pkg_add(1), pbi_add can be used to install a PBI from the command line and register it into the PBI management database. This utility supports the following options:

Switch Description
-e Extract only, do not install. Will extract the archive to ~/<pbidirname> unless the -o option is used
-f Force installation, overwriting an already installed copy of the application
-g Get and show path to icon/images for GUI installations
-i Display information about specified PBI
-l Display LICENSE for specified PBI
-o outdir Specify the directory to use when extracting the PBI with -e.
-r Remote fetch installation file from update server. The system architecture and version will be automatically determined to fetch the correct file.
-v Enable verbose output
--checkscript Display any custom scripts used in the installation/removal of this PBI file.
--licagree Agree to LICENSE terms and conditions. Viewing the license can be done with -l flag
--no-checksig Skip the openssl signature verification of the PBI data
--no-checksum Skip the checksum verification of the archive data
--no-hash Disable using shared hash dir which uses hard-links to share files between applications

For security reasons, it is recommend that users first use the -e and --checkscript options to view archive contents and installation scripts prior to installing a PBI file.

To install a PBI, use: pbi_add -r PBINAME

pbi_autobuild(1)

This utility is used on the PBI build system to build any out-of-date or new packages. The utility is also of interest to PBI testers and system administrators who create and maintain their own internal repository of PBIs. The utility uses the following options:

Switch Description
-c confdir Specify the directory containing the PBI configuration modules data to traverse. Any found pbi.conf files will be parsed, and if PBI_MAKEPORT is set, the target port will be used for the build. If PBI_MAKEPORT is unset, the auto-build will attempt to match the module to a FreeBSD port based upon the dirname of pbi.conf
-d portsdir Specify an alternative ports-dir; defaults to /usr/ports
-o outdir The directory to place the finished PBI files. Also used to determine which apps are in need of a rebuild if the associated FreeBSD port has been updated.
--genpatch When building a new PBI, check for archived copies, and generate smaller patch updates to the new version (*.pbp files)
--keep num When building new PBIs, keep <num> copies of past versions of working PBI in <outdir>/archived/ folder. These archived copies can be used with the --genpatch command to generate update patch files.
--prune Remove any PBIs which no longer have an associated module in confdir
--sign keyfile Digitially sign the PBI file with the specified openssl private key file

pbi_create(1)

This utility is used to create a PBI and replaces the 8.x PBI Module Builder functionality. PBI creators are encouraged to send a tarball of the resulting PBI module to the PBI-testing mailing list so they can be added to the PC-BSD PBI repository and made available to other PC-BSD users.

This utility supports the following options:

Switch Description
-a author Specify the author for this PBI
-b Make a backup of an installed PBI. When using this option specify the target PBI name instead of [pbidir]
-c confdir Specify the meta-data confdir to use. While not required for building a PBI, it is highly recommended. Without some configuration settings in the meta-data, icons and binary entry-points will not be created.
-d portsdir Specify an alternative ports-dir, defaults to /usr/ports
-i icon Specify a default icon for this PBI, relative to pbidir/
-n name Specify a name for this PBI
-o outdir Place the finished .pbi file into the specified directory. Defaults to $HOME/
-p port Use the given port to get PBI name / version from
-r version Specify a version for this PBI
-u weburl Specify a website URL for the PBI
--no-hash Disable using the shared-hash dir which uses hard-links to share files between applications
--sign keyfile Digitially sign the PBI file with the specified openssl private key file

pbi_delete(1)

Similar to FreeBSD's pkg_delete(1), pbi_delete can be used to delete a PBI and de-register it from the PBI package management database. It supports the following options:

Switch Description
-v Enable verbose output
--clean-hdir Perform a full cleaning of the shared-hash dir, removing any unused files. This should only need to be done after a system crash or failure in removing a PBI via normal methods.
--no-hash Disable cleaning the shared-hash dir which uses hard-links to share files between applications

pbi_icon(1)

This utility can be used to manually add or remove a PBI's desktop icon, menu entry within a window manager, and its mime registration. Not all PBIs will contain desktop/menu/mime data. Additionally, the window manager must be XDG-compliant to understand a PBI's icon and mime settings. This utility supports the following options:

Switch Description
-add-desktop Installs any XDG compliant desktop icons, should be run as user.
-add-menu Installs any XDG compliant menu icons, should be run as root.
-add-mime Installs any XDG compliant mime registrations, should be run as root.
-del-desktop Removes any XDG compliant desktop icons, should be run as user.
-del-mime Removes any XDG compliant menu icons, should be run as root.
-del-mime Removes any XDG compliant mime registration, should be run as root.

pbi_info(1)

Similar to FreeBSD's pkg_info(1) command, pbi_info is used to determine which PBIs are currently installed. This utility supports the following options:

Switch Description
-a List all PBIs installed on the system, same as running pbi_info without an argument.
-v Enable verbose output

pbi_makepatch(1)

NEED MORE INFO ABOUT PBP FILES

This utility is used to create a PBI patch file, which allows users to download only the incremental changes when a PBI is upgraded. It supports the following options:

Switch Description
-o outdir Save the resulting .PBP file to the specified directory
--sign keyfile Use the specified openssl key to digitally sign the patch file

pbi_makeport(1)

This utility is used to create a PBI from an existing FreeBSD port skeleton. PBI creators are encouraged to send a tarball of the resulting PBI module to the PBI-testing mailing list so they can be added to the PC-BSD PBI repository and made available to other PC-BSD users.

This utility supports the following options:

Switch Description
-B Build-only, after the port make process has finished, do not generate the PBI file. Generally used with -k to build a port before running pbi_create manually.
-c confdir Specify the meta-data confdir to use. While not required for building a PBI, it is highly recommended. Without some configuration settings in the meta-data, icons and binary entry-points will not be created.
-d portsdir Specify an alternative ports-dir, defaults to /usr/ports
-k Keep the build files after a success or failure compiling/building the PBI
-o outdir The directory to place the finished PBI file, defaults to user's $HOME directory
-p prefix Manually provide a PREFIX, which determines the location where the PBI will end up being installed on the end-user's system.
--no-prune Disable auto-pruning of non REQUIREDBY ports after the compile phase. By default any ports which are used solely for building and which are not required for program execution will be pruned.
--mkdebug Will drop to a debugging shell should the port make fail
--sign keyfile Digitially sign the PBI file with the specified openssl private key file

pbi_patch(1)

This utility is used to install a PBP patch file, allowing the user to perform an incremental upgrade of an installed PBI.

This utility supports the following options:

Switch Description
-e Extract only, do not install. Will extract the archive to ~/<pbidirname> unless the -o option is used.
-g Extract image data from header, commonly used for GUI installations
-i Display information about this PBI file
-o outdir Specify the directory to use when only extracting the PBI with -e.
--checkscript Display any custom scripts used in the installation / removal of this PBI file. Recommended that these be checked if the PBI file is suspect in any way.
--no-checksig Skip the openssl signature verification of the PBI data
--no-hash Disable using the shared-hash dir, which uses hard-links to share files between applications

pbi_update(1)

pbi_update is used to check for updates from the PBI update servers and perform upgrades of PBI packaged applications. This utility supports the following options:

Switch Description
-c Check-only the specified PBI for available updates.
--check-all Run a full check of all installed PBIs and display list of available updates.
--update-all Update all installed PBIs to the latest versions available.
Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox