Difference between revisions of "PBI Manager/10.1"

From PC-BSD Wiki
Jump to: navigation, search
(45 intermediate revisions by one user not shown)
Line 5: Line 5:
  
 
<!--T:2-->
 
<!--T:2-->
PBI Manager is a suite of command line utilities which can be used to install, remove, create and manage PBIs.  
+
PBI Manager is a suite of command line utilities which can be used to install, remove, and manage PBIs.  
  
<!--T:95-->
+
<!--T:187-->
The underlying files and directories used by PBI Manager are as follows:
+
This chapter provides an overview of the commands that are installed by PBI Manager. When using these commands, note that single character options can not be stacked. As an example, you must type '''pbi_add -i -v''' as '''pbi_add -iv''' will fail with a syntax error.
  
<!--T:96-->
+
=== pbi === <!--T:188-->  
* '''/usr/local/etc/pbi.conf''': location of the PBI Manager configuration file
+
  
<!--T:97-->
+
<!--T:189-->
* '''/usr/pbi/''': where PBIs are installed on the system
+
The '''pbi''' meta-command can be used to install, uninstall, and get information about PBIs. Unlike the other '''pbi_*''' commands, it uses a space instead of an underscore. For example, '''pbi add''' is equivalent to '''pbi_add''' and either command can be used to install a PBI.
  
<!--T:98-->
+
<!--T:190-->
* '''/var/db/pbi/''': contains data files related to installed PBIs and repositories
+
This meta-command expects to be given a sub-command, and then a suitable option for that sub-command. To see the available options for a sub-command, use the built-in help system. For example, to see the available options for the '''add''' sub-command, type '''pkg help add'''. Table 7.3a summarizes the available sub-commands.
  
<!--T:99-->
+
<!--T:191-->
* '''/usr/local/sbin/pbi_*''': location of the PBI Manager commands
+
{{Tbl-init|caption=7.3a: pbi Sub-Commands}}
 
+
!Sub-Command
== Command Reference == <!--T:103-->
+
!Description
 
+
|-
<!--T:104-->
+
|'''add'''
The following commands are installed by PBI Manager. For more details, refer to that command's man page. Note that single character options can not be stacked. As an example, you must type '''pbi_add -i -v''' as '''pbi_add -iv''' will fail.
+
|installs the specified PBI
 +
|-
 +
|'''delete'''
 +
|uninstalls the specified PBI
 +
|-  
 +
|'''help'''
 +
|shows the options for the specified sub-command
 +
|-
 +
|'''icon'''
 +
|adds or deletes the PBI's desktop icon, menu icon, or MIME registration
 +
|-
 +
|'''info'''
 +
|shows all available PBIs or lists the packages installed into a specified jail
 +
|-
 +
|'''install'''
 +
|equivalent to '''add'''
 +
|-
 +
|}
  
=== pbi_add(1) === <!--T:105-->
+
=== pbi_add === <!--T:105-->
  
 
<!--T:106-->
 
<!--T:106-->
Similar to FreeBSD's '''pkg_add''', the '''pbi_add''' command is used for adding/installing PBIs on a system, either from a local file or remotely from a repository. This utility supports the options listed in Table 7.3a. All of the options, except for '''-r''', assume that the ''.pbi'' file has already been downloaded and is in the current or specified directory.
+
The pbi_add command is used to install a specified PBI. Table 7.3b summarizes the available options.
  
 
<!--T:107-->
 
<!--T:107-->
{{Tbl-init|caption=7.3a: pbi_add Options}}
+
{{Tbl-init|caption=7.3b: pbi_add Options}}
 
!Switch
 
!Switch
 
!Description
 
!Description
|-
 
|'''-e'''
 
|extract only, do not install; will extract the archive to ''~/<pbidirname>'' unless the '''-o''' option is used
 
 
|-
 
|-
 
|'''-f'''
 
|'''-f'''
 
|force installation, overwriting an already installed copy of the application
 
|force installation, overwriting an already installed copy of the application
 
|-  
 
|-  
|'''-g'''
 
|show path to icons and images for GUI installations
 
|-
 
 
|'''-i'''
 
|'''-i'''
 
|display information about specified PBI; if combined with '''-v''', will display all of the files that will be installed with the PBI
 
|display information about specified PBI; if combined with '''-v''', will display all of the files that will be installed with the PBI
 +
|-
 +
|'''-j <nowiki><jailname></nowiki>'''
 +
|installs the PBI into the specified jail
 
|-
 
|-
 
|'''-l'''
 
|'''-l'''
|display license for specified PBI
+
|display ''LICENSE'' text 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 version will be automatically determined in order to fetch the correct file and resume support is built-in
+
|-
+
|'''-R'''
+
|remote fetch the install file from the update server but do not install
+
 
|-
 
|-
 
|'''-v'''
 
|'''-v'''
 
|enable verbose output
 
|enable verbose output
|-
 
|'''--checkscript'''
 
|display any custom scripts used in the installation/removal of the PBI
 
|-
 
|'''--licagree'''
 
|agree to license terms and conditions; to view the license, use '''-l'''
 
|-
 
|'''--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 the shared hash dir
 
|-
 
|'''--repo repoid'''
 
|specify which repository to use
 
|-
 
|'''--rArch arch'''
 
|manually specify the PBI architecture type of i386 or amd64
 
|-
 
|'''--rVer version'''
 
|specify which version of the PBI to install
 
 
|-
 
|-
 
|}
 
|}
  
 
<!--T:108-->
 
<!--T:108-->
For security reasons, it is recommend that users first use the '''-i -v''' and '''--checkscript''' options to view archive contents and installation scripts prior to installing a PBI file.
+
The following example installs the alpine PBI. When prompted, input your password.
 
+
<!--T:109-->
+
To install a PBI from a remote repository, use: '''pbi_add -r name_of.pbi'''. The following example will install the alpine PBI:
+
  
 
<!--T:186-->
 
<!--T:186-->
{{txtbox|box='''pbi_add -r alpine'''
+
{{txtbox|box='''sudo pbi_add alpine'''
/usr/pbi/.alpine-2.00_4_1-amd64.pbi      100% of 22 MB  159 kBps 02m27s
+
Password:
Verifying Checksum...OK
+
Updating repository catalogue
Extracting to: /usr/pbi/alpine-amd64
+
Installing: alpine
Installed: Alpine-2.00_4_1}}
+
The following 2 packages will be installed:
 +
        Installing pico-alpine: 2.00_1
 +
        Installing alpine: 2.00_4
 +
The installation will require 9 MB more space
 +
2 MB to be downloaded
 +
pico-alpine-2.00_1.txz              100%  314KB 313.9KB/s 313.9KB/s  00:01   
 +
alpine-2.00_4.txz                  100% 1701KB  1.7MB/s  1.4MB/s  00:01   
 +
Checking integrity... done
 +
The following 2 packages will be installed:
 +
        Installing pico-alpine: 2.00_1
 +
        Installing alpine: 2.00_4
 +
The installation will require 9 MB more space
 +
0 B to be downloaded
 +
Checking integrity... done
 +
[1/2] Installing pico-alpine-2.00_1... done
 +
[2/2] Installing alpine-2.00_4... done
 +
<nowiki>*******************************************************************************</nowiki>
 +
<nowiki>***</nowiki> To use GnuPG with Alpine, take a look at the mail/pine-pgp-filters port <nowiki>***</nowiki>
 +
<nowiki>*******************************************************************************</nowiki>
 +
}}
  
<!--T:111-->
+
=== pbi.conf === <!--T:123-->
PBI Manager will automatically install the appropriate PBI. If only a 32-bit version is available, the 32-bit PBI will be installed and will work correctly on the PC-BSD® system.
+
 
+
<!--T:112-->
+
If you previously downloaded the PBI, do not include the '''-r''' switch and give the fullname of the PBI:
+
 
+
<!--T:113-->
+
{{txtbox|box='''pbi_add alpine-2.00_4_1-amd64.pbi'''}}
+
 
+
=== pbi_addrepo(8) === <!--T:114-->
+
 
+
<!--T:115-->
+
The '''pbi_addrepo''' command is used to register a new PBI repository on a system. If the '''pbid''' daemon is running, the repository's index and meta files will be automatically fetched and made ready for browsing. The command has one argument: the name of the repository file. Repository files have a ''.rpo'' extension and are created with the '''pbi_makerepo''' command.
+
 
+
=== pbi_autobuild(8) === <!--T:116-->
+
 
+
<!--T:117-->
+
The '''pbi_autobuild''' command is used on the PBI build system to build any out-of-date or new packages. It can traverse the FreeBSD ports and metadata trees, building missing PBI files or PBIs in which the target port version has been updated. Instructions for using this command to keep a custom repository up-to-date can be found in the section {{local|link=Create Your Own PBI Repository|anchor=Configure the Automatic Build of Updated Ports|Configure the Automatic Build of Updated Ports}}.
+
 
+
<!--T:118-->
+
Table 7.3b summarizes this command's options:
+
 
+
<!--T:119-->
+
{{Tbl-init|caption=7.3b: pbi_autobuild Options}}
+
!Switch
+
!Description
+
|-
+
|'''-c confdir'''
+
|mandatory; specify the directory containing the PBI configuration modules; 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 directory; defaults to ''/usr/ports/''
+
|-
+
|'''-h script'''
+
|specify a helper script to call after building a PBI
+
|-
+
|'''-o outdir'''
+
|mandatory; the directory to place the finished PBI files
+
|-
+
|'''-p num'''
+
|if your build hardware has the CPU and disk I/O to support concurrent build processes, specify the number of concurrent builds
+
|-
+
|'''-32'''
+
|include when building a 32-bit PBI on a 64-bit system
+
|-
+
|'''-32fallback'''
+
|only build the 32bit PBI if a 64-bit version does build
+
|-
+
|'''--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
+
|-
+
|'''--pkgcache'''
+
|enable caching of ''.txz'' pkg files which greatly speeds up subsequent builds of a PBI
+
|-
+
|'''--prune'''
+
|remove any PBIs which no longer have an associated module
+
|-
+
|'''--tmpfs'''
+
|automatically create and mount a tmp filesystem which can speed up port compiles on systems with available RAM
+
|-
+
|'''--sign keyfile'''
+
|digitally sign the PBI file with the specified openssl private key file
+
|-
+
|}
+
 
+
=== pbi_browser(1) === <!--T:120-->
+
 
+
<!--T:121-->
+
The '''pbi_browser''' command provides a CLI front-end to browsing a repository's available PBIs. Options for viewing categories and searching by keyword are available, and once the desired PBI is located, it will show the '''pbi_add''' command which can be used to install the application. Table 7.3c summarizes the available options.
+
 
+
<!--T:122-->
+
{{Tbl-init|caption=7.3c: pbi_browser Options}}
+
!Switch
+
!Description
+
|-
+
|'''-c category'''
+
|displays a list of PBIs in the specified category
+
|-
+
|'''-s search'''
+
|search for PBIs containing the specified string in the name, description, or keywords
+
|-
+
|'''--listcats'''
+
|list the available categories
+
|-
+
|'''--viewall'''
+
|list all available PBIs
+
|-
+
|}
+
 
+
=== pbi.conf(5) === <!--T:123-->
+
  
 
<!--T:124-->
 
<!--T:124-->
''pbi.conf'' is an ASCII text configuration file containing values that are used by the various '''pbi_*''' commands. The proxy variables are only needed if the system uses a proxy server to access the Internet. Table 7.3d lists the supported variables.
+
The '''pbi_*''' commands support several environment variables which can be stored in the ASCII text configuration file, ''/usr/local/etc/pbi.conf''. These proxy variables are only needed if the system uses a proxy server to access the Internet. Table 7.3c lists the supported variables.
  
 
<!--T:125-->
 
<!--T:125-->
{{Tbl-init|caption=7.3d: pbi.conf Variables}}
+
{{Tbl-init|caption=7.3c: pbi.conf Variables}}
 
!Variable
 
!Variable
 
!Description
 
!Description
|-
 
|PBID_REFRESH
 
|wakeup time in seconds for '''pbid''' to run its checks
 
|-
 
|PBI_INDEXREFRESH
 
|number of hours representing how often '''pbid''' refreshes the index and meta files from repos; default is every 24 hours
 
 
|-
 
|-
 
|PBI_PROXYURL
 
|PBI_PROXYURL
Line 231: Line 129:
 
|}
 
|}
  
=== pbi_create(1) === <!--T:126-->
+
=== pbi_delete === <!--T:136-->
 
+
<!--T:127-->
+
The '''pbi_create''' command provides a way for packagers to manually specify a target directory to be compressed into a PBI file. The option '''-b''' can also be used to re-package an already installed PBI back to an archive. PBI creators are encouraged to send a tarball of the resulting PBI module to the {{citelink|url=http://lists.pcbsd.org/mailman/listinfo/pbi-dev|txt=PBI-dev mailing list}} so they can be added to the PC-BSD® PBI repository and made available to other PC-BSD® users.
+
 
+
<!--T:128-->
+
Table 7.3e summarizes the available options:
+
 
+
<!--T:129-->
+
{{Tbl-init|caption=7.3e: pbi_create Options}}
+
!Switch
+
!Description
+
|-
+
|'''-a author'''
+
|specify the author for this PBI
+
|-
+
|'''-b'''
+
|make a backup of an installed PBI; specify the target PBI name instead of the PBI directory
+
|-
+
|'''-c confdir'''
+
|specify the metadata configuration directory; while not required it is highly recommended as metadata is required to create icons and binary entry-points
+
|-
+
|'''-d portsdir'''
+
|specify an alternative ports directory; defaults to ''/usr/ports/''
+
|-
+
|'''-i icon'''
+
|specify a default icon, 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 and version
+
|-
+
|'''-r version'''
+
|specify a version for this PBI
+
|-
+
|'''-u weburl'''
+
|specify a website URL for the PBI
+
|-
+
|'''--no-hash'''
+
|disable using the shared hash directory which uses hard links to share files between applications
+
|-
+
|'''--sign keyfile'''
+
|digitally sign the PBI file with the specified openssl private key file
+
|-
+
|}
+
 
+
<!--T:130-->
+
As the superuser, you can create a PBI with the '''pbi_create''' command using the following syntax:
+
 
+
<!--T:131-->
+
{{txtbox|pre|box='''pbi_create -a <author> -n <name> -r <version> -w <weburl> <target directory>'''{{nbsp|4}}}}
+
 
+
<!--T:132-->
+
Inside the target directory place the application's binaries or scripts along with any required dependencies. To indicate which file(s) represent the runtime command(s), include a file named ''external-links'' in the target directory. That file contains an entry for each command, as seen in the following example:
+
 
+
<!--T:133-->
+
{{txtbox|pre|box={{pound}} Files to be symlinked into the default LOCALBASE{{nbsp|30}}
+
{{pound}} One per-line, relative to %%PBI_APPDIR%% and LOCALBASE
+
{{pound}} Defaults to keeping any existing files in LOCALBASE
+
{{pound}} Use bin-files/ for binaries that need wrapper functionality
+
+
{{pound}} TARGET                LINK IN LOCALBASE      ACTION
+
bin/myapp              bin/myapp              binary,nocrash}}
+
 
+
<!--T:134-->
+
This entry instructs '''pbi_create''' to make the wrapper scripts for the ''myapp'' binary, along with placing it in the user's PATH at install time.
+
 
+
<!--T:135-->
+
It is also possible to include desktop icons and mime entries using the ''xdg-mime/'', ''xdg-desktop/'' and ''xdg-menu/'' directories. The section on how to {{local|link=Create PBIs}} contains more details about creating these files. These directories should be created as subdirectories of the target directory of your application.
+
 
+
=== pbi_delete(1) === <!--T:136-->
+
  
 
<!--T:137-->
 
<!--T:137-->
Similar to FreeBSD's '''pkg_delete''', the '''pbi_delete''' command removes an installed PBI from the system. It also schedules cleaning for the shared library directory, which is performed by '''pbid'''. Table 7.3f summarizes its options:
+
The pbi_delete command removes an installed PBI from the system. Table 7.3d summarizes its one available option:  
  
 
<!--T:138-->
 
<!--T:138-->
{{Tbl-init|caption=7.3f: pbi_delete Options}}
+
{{Tbl-init|caption=7.3d: pbi_delete Options}}
 
!Switch
 
!Switch
 
!Description
 
!Description
Line 318: Line 141:
 
|'''-v'''
 
|'''-v'''
 
|enable verbose output
 
|enable verbose output
|-
 
|'''--clean-hdir'''
 
|perform a full cleaning of the shared hash directory, removing any unused files; should only be required after a system crash or failure in removing a PBI
 
 
|-
 
|-
 
|}
 
|}
Line 327: Line 147:
 
The following example uninstalls the previously installed alpine PBI:
 
The following example uninstalls the previously installed alpine PBI:
 
   
 
   
{{txtbox|pre|box='''pbi_delete -v alpine-2.00_4_1-amd64'''
+
{{txtbox|pre|box='''sudo pbi_delete alpine'''
Running pre-removal script: /var/db/pbi/installed/alpine-2.00_4_1-amd64/pre-remove.sh
+
Password:
Removing: /usr/pbi/alpine-amd64
+
Updating repository catalogue
Removing: /var/db/pbi/installed/alpine-2.00_4_1-amd64}}
+
Deinstallation has been requested for the following 1 packages:
  
=== pbi_deleterepo(8) === <!--T:140-->
+
        <!--T:192-->
 +
alpine-2.00_4
  
<!--T:141-->
+
<!--T:193-->
The '''pbi_deleterepo''' command can be used to remove a registered repository from the system. It takes the repository's ID as the only command argument.
+
The deinstallation will free 8 MB
 +
[1/1] Deleting alpine-2.00_4... done
 +
Deinstallation has been requested for the following 2 packages:
  
=== pbi_icon(1) === <!--T:142-->
+
        <!--T:194-->
 +
openjpeg-2.1.0
 +
        pico-alpine-2.00_1
 +
 
 +
<!--T:195-->
 +
The deinstallation will free 2 MB
 +
[1/2] Deleting openjpeg-2.1.0... done
 +
[2/2] Deleting pico-alpine-2.00_1... done
 +
}}
 +
 
 +
=== pbi_icon === <!--T:142-->
  
 
<!--T:143-->
 
<!--T:143-->
The '''pbi_icon''' command provides a number of options for adding desktop icons, menu entries, and mime data for an installed PBI. Not all PBIs will contain desktop/menu/mime data. Additionally, the window manager must be {{citelink|url=http://en.wikipedia.org/wiki/Xdg|txt=XDG}}-compliant to understand a PBI's icon and mime settings. Table 7.3g summarizes this command's options:
+
The '''pbi_icon''' command provides a number of options for adding desktop icons, menu entries, and MIME data for an installed PBI. Not all PBIs will contain desktop/menu/MIME data. Additionally, the window manager must be {{citelink|url=http://en.wikipedia.org/wiki/Xdg|txt=XDG}}-compliant to understand a PBI's icon and mime settings. Table 7.3e summarizes this command's options:
  
 
<!--T:144-->
 
<!--T:144-->
{{Tbl-init|caption=7.3g: pbi_icon Options}}
+
{{Tbl-init|caption=7.3e: pbi_icon Options}}
 
!Switch
 
!Switch
 
!Description
 
!Description
Line 355: Line 188:
 
|'''add-menu'''
 
|'''add-menu'''
 
|installs menu icons; should be run as root
 
|installs menu icons; should be run as root
|-
 
|'''add-pathlnk'''
 
|installs any $PATH links to ''~/bin'' when run as user or to $LOCALBASE when run as root
 
 
|-
 
|-
 
|'''del-desktop'''
 
|'''del-desktop'''
Line 367: Line 197:
 
|'''del-mime'''
 
|'''del-mime'''
 
|removes mime information; should be run as root
 
|removes mime information; should be run as root
|-
 
|'''del-pathlnk'''
 
|removes any $PATH links to ''~/bin'' when run as user or to $LOCALBASE when run as root
 
|-
 
|}
 
 
=== pbi_indextool(1) === <!--T:145-->
 
 
<!--T:146-->
 
The '''pbi_indextool''' command is useful for repository maintainers. It allows PBI files to be added and removed from the repository's ''INDEX'' file. An example of using this command can be found in {{local|link=Create Your Own PBI Repository}}. Table 7.3h summarizes the available options:
 
 
<!--T:147-->
 
{{Tbl-init|caption=7.3h: pbi_indextool Options}}
 
!Command
 
!Switch
 
!Description
 
|-
 
|rowspan=4|'''add'''
 
|'''-b vers'''
 
|mark previous versions as having a binary diff patch (''.pbp'' file used for upgrading) available
 
|-
 
<!-- add (handled by rowspan 4) -->
 
|'''-f pbifile'''
 
|mandatory, name of PBI being added to the target ''INDEX'' file
 
|-
 
<!-- add (handled by rowspan 4) -->
 
|'''-k num'''
 
|number of previous versions of this PBI to keep in the ''INDEX'' file
 
|-
 
<!-- add (handled by rowspan 4) -->
 
|'''-u fileurl'''
 
|mandatory URL to PBI location on server in the format category/pbi_name
 
|-
 
|rowspan=3 style="background: #eeeeee;"|'''rem'''
 
|'''-m arch'''
 
|mandatory architecture type for PBI being removed (e.g. i386, amd64)
 
|-
 
<!-- rem (handled by rowspan 3) -->
 
|'''-n pbiname'''
 
|mandatory name of PBI being removed from the ''INDEX'' file
 
|-
 
<!-- rem (handled by rowspan 3) -->
 
|'''-v version'''
 
|mandatory, version of the PBI being removed from the ''INDEX'' file
 
 
|-
 
|-
 
|}
 
|}
  
=== pbi_info(1) === <!--T:148-->
+
=== pbi_info === <!--T:148-->
  
 
<!--T:149-->
 
<!--T:149-->
Similar to FreeBSD's '''pkg_info''' command, the '''pbi_info''' command is used to determine which PBIs are currently installed. Table 7.3i summarizes the available options:
+
The '''pbi_info''' command is used to determine which PBIs are currently installed. Table 7.3f summarizes the available options:
  
 
<!--T:150-->
 
<!--T:150-->
{{Tbl-init|caption=7.3i: pbi_info Options}}
+
{{Tbl-init|caption=7.3f: pbi_info Options}}
 
!width=15%|Switch
 
!width=15%|Switch
 
!width=85%|Description
 
!width=85%|Description
Line 427: Line 213:
 
|list all PBIs installed on the system; same as running '''pbi_info''' without an argument
 
|list all PBIs installed on the system; same as running '''pbi_info''' without an argument
 
|-
 
|-
|'''-i'''
+
|'''-j <nowiki><jailname></nowiki>'''
|list all available PBIs from any repo
+
|list PBIs installed in the specified jail
 
|-
 
|-
 
|'''-v'''
 
|'''-v'''
|enable verbose output
+
|includes verbose information about each PBI
 
|-
 
|-
 
|}
 
|}
  
=== pbi_listrepo(1) === <!--T:151-->
+
=== pbi_makeindex === <!--T:177-->
  
<!--T:152-->
+
<!--T:196-->
The '''pbi_listrepo''' command manages installed repositories on a system. Table 7.3j summarizes this command's options:
+
This command is used to make the INDEX for a custom PBI repository which can then be used in [[AppCafe®/10.1|AppCafe®]]. Refer to [[Create Your Own PBI Repository/10.1|Create Your Own PBI Repository]] for instructions on how to create a custom repository.
  
<!--T:153-->
+
=== pbi_updateindex === <!--T:179-->
{{Tbl-init|caption=7.3j: pbi_listrepo Options}}
+
!width=15%|Switch
+
!width=85%|Description
+
|-
+
|'''--down'''
+
|move the targeted repoID down a single number in priority
+
|-
+
|'''-mirror URL'''
+
|change the specified repoID's mirror URL
+
|-
+
|'''--up'''
+
|move the targeted repoID up a single number in priority
+
|-
+
|}
+
 
+
<!--T:154-->
+
Run the command without any options to list the IDs of the available repositories.
+
 
+
=== pbi_makepatch(1) === <!--T:155-->
+
 
+
<!--T:156-->
+
The '''pbi_makepatch''' command is automatically used by '''pbi_autobuild''' to create small ''*.pbp'' (Push Button Patch) files. These files can be downloaded to a user's system in order to update a PBI's version without re-downloading the entire archive. This allows users to download only the incremental changes when a PBI is upgraded. The command can also be run manually by providing two PBI archives to compare and generate a patch file for.
+
 
+
<!--T:157-->
+
Table 7.3k summarizes the available options:
+
 
+
<!--T:158-->
+
{{Tbl-init|caption=7.3k: pbi_makepatch Options}}
+
!width=15%|Switch
+
!width=85%|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
+
|-
+
|'''--tmpfs'''
+
|can reduce building time for large PBIs
+
|-
+
|}
+
 
+
=== pbi_makeport(1) === <!--T:159-->
+
 
+
<!--T:160-->
+
The '''pbi_makeport''' command can be used by packagers to build a target FreeBSD port and convert it into a PBI file. Many options are provided to fine-tune the build process, and meta-data modules can also be specified to further improve the resulting PBI file. The first time this command is run, it will build a fresh chroot sandbox environment which can be used for clean-room building of the target port without affecting the host system. More details about how to create a PBI using this command, can be found in the ''{{local|link=PBI Module Builder Guide|anchor=Creating a New PBI with pbi makeport|PBI Module Builder Guide}}''.
+
 
+
<!--T:161-->
+
{{note|width=auto|icon64=The '''pbi_makeport''' command has support for using {{citelink|url=http://ccache.samba.org/|txt=ccache}} to speed up the compile process. If '''ccache''' is installed on the host system and the CCACHE_DIR variable is set, the '''pbi_makeport''' command will automatically utilize it for the port compile phase. This can be disabled by setting NO_CCACHE=yes in ''/etc/pbi-make.conf'' on the host system, or as an optional make flag in a module's ''pbi.conf'' file.}}
+
 
+
<!--T:162-->
+
'''pbi_makeport''', will attempt to create any users or groups that the underlying ports require during the PBI installation. If the PBI is being installed as non-root, it will instead provide a warning message regarding any users or groups that need to be manually created. For this functionality to work, the port must set ''USERS='' or ''GROUPS='' in its ''Makefile'' and provide the corresponding UID and/or GID entries.
+
 
+
<!--T:163-->
+
Table 7.3l summarizes the available options:
+
 
+
<!--T:164-->
+
{{Tbl-init|caption=7.3l: pbi_makeport Options}}
+
!width=15%|Switch
+
!width=85%|Description
+
|-
+
|'''-B'''
+
|build-only; generally used with '''-k''' to build a port before running '''pbi_create''' manually
+
|-
+
|'''-c confdir'''
+
|specify the metadata configuration directory; while not required it is highly recommended as metadata is required to create icons and binary entry-points
+
|-
+
|'''-d portsdir'''
+
|specify an alternative ports directory; defaults to ''/usr/ports''
+
|-
+
|'''-k'''
+
|keep the build files after 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 be installed on the end-user's system
+
|-
+
|'''--32'''
+
|include when building a 32-bit PBI on a 64-bit system
+
|-
+
|'''--delbuild'''
+
|remove any existing build directories before starting the build
+
|-
+
|'''--mkdebug'''
+
|will drop to a debugging shell should the port make fail
+
|-
+
|'''--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
+
|-
+
|'''--pkgdir dir'''
+
|uses the specified directory to cache the .txz package so subsequent builds will not rebuild the port from source
+
|-
+
|'''--tmpfs'''
+
|automatically create and mount a tmp filesystem and use it for WRKDIRPREFIX; can speed up port compiles on systems with available RAM
+
|-
+
|'''--sign keyfile'''
+
|digitally sign the PBI file with the specified openssl private key file
+
|-
+
|}
+
 
+
=== pbi_makerepo(1) === <!--T:165-->
+
 
+
<!--T:166-->
+
The '''pbi_makerepo''' command allows repository maintainers to create a single ''*.rpo'' file containing various information about the new repository. This ''.rpo'' file can then be installed on the target system with '''pbi_addrepo'''. Table 7.3m summarizes the available options.
+
 
+
<!--T:167-->
+
{{Tbl-init|caption=7.3m: pbi_makerepo Options}}
+
!Switch
+
!Description
+
|-
+
|'''--desc description'''
+
|required; description of the repo to be shown in the repo list
+
|-
+
|'''--key keyfile'''
+
|required; OpenSSL public key used to verify the digital signature of PBIs installed from this repo
+
|-
+
|'''--mirror URL'''
+
|required; URL in {{http}}, {{https}}, or {{ftp}} format to download PBIs and updates from
+
|-
+
|'''--url URL'''
+
|required; URL in {{http}}, {{https}}, or {{ftp}} format to use when downloading the master ''INDEX'' file of available PBIs
+
|-
+
|}
+
 
+
=== pbi_metatool(1) === <!--T:168-->
+
 
+
<!--T:169-->
+
The '''pbi_metatool''' command provides a way for repository maintainers to modify the PBI metadata in their repository in order to add or remove application categories or specified PBIs. An example of using this command can be found in {{local|link=Create Your Own PBI Repository}}. Table 7.3n summarizes the available options:
+
 
+
<!--T:170-->
+
{{Tbl-init|caption=7.3n: pbi_metatool Options}}
+
!Command
+
!Switch
+
!Description
+
|-
+
|rowspan=2|'''add''' or '''rem'''
+
|'''--cat'''
+
|indicates that a new category is being '''added to''' or ''removed from'' the target metafile
+
|-
+
<!-- handled by rowspan -->
+
|'''--app'''
+
|adds or removes a new PBI to/from the target metafile
+
|-
+
|rowspan=6 style="background: #eeeeee;"|'''add'''
+
|'''-a author'''
+
|adds the name of the application's author to the target metafile
+
|-
+
<!-- handled by rowspan -->
+
|'''-c category'''
+
|name of new category to add to the target metafile
+
|-
+
<!-- handled by rowspan -->
+
|'''-d desc'''
+
|mandatory description of PBI or category being added
+
|-
+
<!-- handled by rowspan -->
+
|'''-i icon'''
+
|mandatory URL to 64x64 ''.png'' icon of PBI or category being added
+
|-
+
<!-- handled by rowspan -->
+
|'''-k keywords'''
+
|comma delimited list (with no spaces) of search keywords
+
|-
+
<!-- handled by rowspan -->
+
|'''-l license'''
+
|type of license (e.g. BSD, GPL, Commercial)
+
|-
+
<!-- handled by rowspan -->
+
|'''-m email'''
+
|address of application/port maintainer
+
|-
+
|rowspan=1|'''add''' or '''rem'''
+
|'''-n name'''
+
|mandatory name of category or PBI being ''added to'' or ''removed from'' the target metafile
+
|-
+
|rowspan=3|'''add'''
+
|'''-t type'''
+
|type of application (e.g. Graphical, Text, Service)
+
|-
+
<!-- handled by rowspan -->
+
|'''-u URL'''
+
|website of application being added
+
|-
+
<!-- handled by rowspan -->
+
|'''-r'''
+
|include if application needs to be installed as the superuser
+
|-
+
|'''add'''
+
|'''-s shortdesc'''
+
|short description of application
+
|-
+
|}
+
 
+
=== pbi_patch(1) === <!--T:171-->
+
 
+
<!--T:172-->
+
The '''pbi_patch''' command is used to update an installed PBI to a different version using a small diff Push Button Patch ''*.pbp'' file. This allows the user to perform an incremental upgrade of an installed PBI. The available options are summarized in Table 7.3o.
+
 
+
<!--T:173-->
+
{{Tbl-init|caption=7.3o: pbi_patch Options}}
+
!Switch
+
!Description
+
|-
+
|'''-e'''
+
|extract only, do not install; will extract the archive to ''~/<pbidirname>'' unless '''-o''' 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 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 directory which uses hard links to share files between applications
+
|-
+
|}
+
 
+
=== pbi_update(1) === <!--T:174-->
+
 
+
<!--T:175-->
+
The '''pbi_update''' command is used to display information about which PBIs have available updates and to perform the updates. Table 7.3p summarizes the available options.
+
 
+
<!--T:176-->
+
{{Tbl-init|caption=7.3p: pbi_update 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
+
|-
+
|'''-disable-auto'''
+
|disable auto-updating of the target PBI
+
|-
+
|'''--enable-auto'''
+
|enable auto-updating of the target PBI
+
|-
+
|'''--update-all'''
+
|update all installed PBIs to the latest versions
+
|-
+
|}
+
 
+
=== pbi_update_hashdir(1) === <!--T:177-->
+
 
+
<!--T:178-->
+
The '''pbi_update_hashdir''' command is used by the '''pbid''' daemon to merge the contents of a PBI into the hash directory.
+
 
+
=== pbid(8) === <!--T:179-->
+
 
+
<!--T:180-->
+
The '''pbid''' command runs a small daemon which performs maintenance of installed PBIs, merges files into the shared hashdir, fetches the repository ''INDEX'' and meta files, and makes the adding and removing of PBIs much faster. It will automatically be started from the''/usr/local/etc/rc.d/pbid'' startup script if ''pbid_enable="YES"'' is in the ''/etc/rc.conf'' file.
+
 
+
<!--T:181-->
+
This utility supports the option summarized in table 7.3q:
+
 
+
<!--T:182-->
+
{{Tbl-init|caption=7.3q: pbid Options}}
+
!Switch
+
!Description
+
|-
+
|'''-v'''
+
|enable verbose output when the daemon starts
+
|-
+
|'''--refresh'''
+
|schedule a refresh of index and meta files
+
|-
+
|}
+
  
<!--T:183-->
+
<!--T:197-->
This command logs its output to ''/var/log/pbid.log''. Check this log for errors should you experience any problems with PBI maintenance.
+
To check for a newer version of the PC-BSD® ''PBI-INDEX.txz'' file, type '''sudo pbi_updateindex''' and input your password when prompted. If a newer version is available, this command fetches and extracts it so that the system has the most recent list of available PBIs.
  
<!--T:184-->
+
<!--T:198-->
 
<noinclude>
 
<noinclude>
 
{{refheading}}
 
{{refheading}}

Revision as of 07:37, 17 June 2014


Contents


PBI Manager is a suite of command line utilities which can be used to install, remove, and manage PBIs.

This chapter provides an overview of the commands that are installed by PBI Manager. When using these commands, note that single character options can not be stacked. As an example, you must type pbi_add -i -v as pbi_add -iv will fail with a syntax error.

pbi

The pbi meta-command can be used to install, uninstall, and get information about PBIs. Unlike the other pbi_* commands, it uses a space instead of an underscore. For example, pbi add is equivalent to pbi_add and either command can be used to install a PBI.

This meta-command expects to be given a sub-command, and then a suitable option for that sub-command. To see the available options for a sub-command, use the built-in help system. For example, to see the available options for the add sub-command, type pkg help add. Table 7.3a summarizes the available sub-commands.

Table 7.3a: pbi Sub-Commands [tables 1]
Sub-Command Description
add installs the specified PBI
delete uninstalls the specified PBI
help shows the options for the specified sub-command
icon adds or deletes the PBI's desktop icon, menu icon, or MIME registration
info shows all available PBIs or lists the packages installed into a specified jail
install equivalent to add

pbi_add

The pbi_add command is used to install a specified PBI. Table 7.3b summarizes the available options.

Table 7.3b: pbi_add Options [tables 2]
Switch Description
-f force installation, overwriting an already installed copy of the application
-i display information about specified PBI; if combined with -v, will display all of the files that will be installed with the PBI
-j <jailname> installs the PBI into the specified jail
-l display LICENSE text for specified PBI
-v enable verbose output

The following example installs the alpine PBI. When prompted, input your password.

sudo pbi_add alpine

Password: Updating repository catalogue Installing: alpine The following 2 packages will be installed:

       Installing pico-alpine: 2.00_1
       Installing alpine: 2.00_4

The installation will require 9 MB more space 2 MB to be downloaded pico-alpine-2.00_1.txz 100% 314KB 313.9KB/s 313.9KB/s 00:01 alpine-2.00_4.txz 100% 1701KB 1.7MB/s 1.4MB/s 00:01 Checking integrity... done The following 2 packages will be installed:

       Installing pico-alpine: 2.00_1
       Installing alpine: 2.00_4

The installation will require 9 MB more space 0 B to be downloaded Checking integrity... done [1/2] Installing pico-alpine-2.00_1... done [2/2] Installing alpine-2.00_4... done ******************************************************************************* *** To use GnuPG with Alpine, take a look at the mail/pine-pgp-filters port ***

*******************************************************************************

pbi.conf

The pbi_* commands support several environment variables which can be stored in the ASCII text configuration file, /usr/local/etc/pbi.conf. These proxy variables are only needed if the system uses a proxy server to access the Internet. Table 7.3c lists the supported variables.

Table 7.3c: pbi.conf Variables [tables 3]
Variable Description
PBI_PROXYURL proxy server IP address
PBI_PROXYPORT proxy server port number
PBI_PROXYTYPE can be HTTP or SOCKS5
PBI_PROXYUSER username used to authenticate with proxy server
PBI_PROXYPASS password used to authenticate with proxy server
PBI_FBSDMAJOR can be set to the major FreeBSD version when running -CURRENT or some other version with no PBIs

pbi_delete

The pbi_delete command removes an installed PBI from the system. Table 7.3d summarizes its one available option:

Table 7.3d: pbi_delete Options [tables 4]
Switch Description
-v enable verbose output

The following example uninstalls the previously installed alpine PBI:

sudo pbi_delete alpine

Password: Updating repository catalogue Deinstallation has been requested for the following 1 packages:

       alpine-2.00_4

The deinstallation will free 8 MB [1/1] Deleting alpine-2.00_4... done Deinstallation has been requested for the following 2 packages:

       openjpeg-2.1.0
       pico-alpine-2.00_1

The deinstallation will free 2 MB [1/2] Deleting openjpeg-2.1.0... done

[2/2] Deleting pico-alpine-2.00_1... done

pbi_icon

The pbi_icon command provides a number of options for adding desktop icons, menu entries, and MIME data for an installed PBI. Not all PBIs will contain desktop/menu/MIME data. Additionally, the window manager must be XDG[1]-compliant to understand a PBI's icon and mime settings. Table 7.3e summarizes this command's options:

Table 7.3e: pbi_icon Options [tables 5]
Switch Description
add-desktop installs desktop icon; should be run as regular user
add-mime installs mime information; should be run as root
add-menu installs menu icons; should be run as root
del-desktop removes desktop icon; should be run as regular user
del-menu removes menu icons; should be run as root
del-mime removes mime information; should be run as root

pbi_info

The pbi_info command is used to determine which PBIs are currently installed. Table 7.3f summarizes the available options:

Table 7.3f: pbi_info Options [tables 6]
Switch Description
-a list all PBIs installed on the system; same as running pbi_info without an argument
-j <jailname> list PBIs installed in the specified jail
-v includes verbose information about each PBI

pbi_makeindex

This command is used to make the INDEX for a custom PBI repository which can then be used in AppCafe®. Refer to Create Your Own PBI Repository for instructions on how to create a custom repository.

pbi_updateindex

To check for a newer version of the PC-BSD® PBI-INDEX.txz file, type sudo pbi_updateindex and input your password when prompted. If a newer version is available, this command fetches and extracts it so that the system has the most recent list of available PBIs.


References


  1. http://en.wikipedia.org/wiki/Xdg

List of Tables


  1. Table 7.3a: pbi Sub-Commands
  2. Table 7.3b: pbi_add Options
  3. Table 7.3c: pbi.conf Variables
  4. Table 7.3d: pbi_delete Options
  5. Table 7.3e: pbi_icon Options
  6. Table 7.3f: pbi_info Options
Other languages:German 11% • ‎English 100%
Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox