Difference between revisions of "Using PBI Manager"

From PC-BSD Wiki
Jump to: navigation, search
(New Features)
m
 
(2 intermediate revisions by one user not shown)
Line 1: Line 1:
PC-BSD 9.0 introduced PBI Manager, a suite of command line utilities for managing PBIs.
+
[[category:orphan]]
 
+
===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:'''
+
 
+
[http://www.pcbsd.org/~kris/pbi9-slides.pdf| The PBI Format Re-implemented for Free/PC-BSD]
+
 
+
[http://wiki.pcbsd.org/index.php/PBI9_Format| 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 [http://makeapbi.sourceforge.net/ 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:
+
{| border=1
+
|'''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:
+
{| border=1
+
|'''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 [http://lists.pcbsd.org/mailman/listinfo/pbi-dev 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:
+
{| border=1
+
|'''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:
+
{| border=1
+
|'''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 [http://en.wikipedia.org/wiki/Xdg XDG]-compliant to understand a PBI's icon and mime settings. This utility supports the following options:
+
 
+
{| border=1
+
|'''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:
+
{| border=1
+
|'''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:
+
{| border=1
+
|'''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 [http://lists.pcbsd.org/mailman/listinfo/pbi-dev 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:
+
{| border=1
+
|'''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:
+
{| border=1
+
|'''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:
+
 
+
{| border=1
+
|'''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.
+
|-
+
|}
+

Latest revision as of 01:31, 8 February 2012

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox