PBIng provides an information wrapper around existing FreeBSD packages. This wrapper, known as a PBI module, contains the metadata which displays information about the PBI in AppCafe®, such as screenshots, similar applications, search terms, and plugins. With PBIng, you no longer have to build PBIs. Instead, you can modify the information contained in PBI modules in order to create a custom PBI repository which can be added to AppCafe®. Since PBI modules are comprised of ASCII text files, they can be easily edited using the graphical EasyPBI utility or manually with a text editor.
This chapter demonstrates how to use EasyPBI, which is the recommended method for customizing PBI modules. It then describes the files contained in a PBI module for those users who prefer to edit files manually or who want a better understanding of the components of a PBI module. Once you have created your custom modules, refer to Create Your Own PBI Repository for instructions on how to add the custom repository to AppCafe®.
Creating a PBI Module
EasyPBI can be launched from Control Panel or by typing EasyPBI.
When you first launch EasyPBI, everything will be greyed out, as seen in Figure 8.1a. This is because you have not created any modules yet.
Click the "New" button to create a PBI module and to open the screen shown in Figure 8.1b.
The following options are available when creating a new module:
- FreeBSD Package: click the “Find” button to browse the available categories and to select the package to convert into a PBI.
- Icon File: by default, a generic PBI icon will be used. If the application has its own icon, use the “Select” button to browse to the location of the icon. When selecting a custom icon, use a 64x64 .png file with a transparent background.
- Quick Module: check this box if the system is not currently connected to the Internet. Otherwise, EasyPBI does a scan of the package in order to automatically fill in the module's information. This information can be filled in manually, as described in the next screen.
After making your selections, click “OK”. The information for the module will appear as seen in the example in Figure 8.1c. In this example, the net-p2p/linuxdcpp port has been selected.
The "Port/Package" and "Author" fields are mandatory and should be auto-filled for you, unless you checked the "Quick Module" box. If the port does not supply the "Author" name, check the application's website to see if you can find one. Otherwise, input the email address of the port maintainer. A generic icon will be supplied for the module. You can change the default icon by clicking it.
The other items in the “PBI Configuration” tab are optional:
- App Type: if this is empty, the PBI will not appear in an AppCafe® search unless "Raw Packages" is checked in the "Browser View" menu. Otherwise, click the green arrow to select "Graphical", "Text", or "Server". The PBI will be assigned the icon for that search selection and will appear in that "Browser View".
- Search Tags: a comma delimited with no space list of tags. If a user types one of the tags into the search bar of AppCafe®, the PBI will be listed, assuming the "App Type" matches the user's configured "Browser View".
- Plugins: if the application, such as a web browser, has associated plugins, click the "+" button to browse to the location of the plugin packages. These will be added to the "Plugins" tab for the PBI in AppCafe®.
- Screenshots: to include a screenshot of the application, click the "+" button and browse to the location of the screenshot in .jpg or .png format. The added screenshot(s) will appear in the "Screenshots" tab for the PBI in AppCafe®.
- Similar Apps: if there are any other packages with similar functionality, click the "+" button to browse to the location of the plugin packages. These will be added to the "Similar" tab for the PBI in AppCafe®.
- View Package Overrides: check this box to display additional settings . By default, the PBI will be built using the default options provided by the package. Some defaults can be overridden in this section: the default PBI name, URL for the application's website, license text, summary, and description. You can also add additional packages to install with the PBI or delete a package that is typically installed with the application. Note that you typically should not need to make any of these changes.
XDG Shortcuts Tab
This tab, shown in Figure 8.1d, is used to create desktop icons and menu entries so that the application can be easily started from within a desktop environment. This is important step for graphical applications as it configures the primary method for interacting with the program.
Any entries currently configured for the module will appear in the left side of the tab. Click an existing entry to display its details on the right. You can remove a highlighted entry by clicking the “-” (minus sign) button, or create a new entry by clicking on the white paper button under the entry list. On the right side of this tab, you can edit the currently selected entry and click the “Save” button to overwrite the current entry with the new settings. Alternately, click “Add” to copy the existing details to a new entry.
The "Entry Details" section of this tab are as follows when the "Desktop" button is selected:
- Name: this is the text that will appear for the desktop menu entry, and is usually the full name of the application.
- Executable: input the name of the executable to run. EasyPBI will automatically generate the PBI-specific path to the binary.
- Icon: when using a custom icon, click “Custom Icon Path” and input the full path to the icon file.
- Open in Terminal: check this box if the application needs to be opened in an X terminal. This is useful for running some text-based programs that need to be embedded into a console for user interaction.
- Make Invisible: if checked, the entry will be hidden. This is not as useful for desktop entries but can be handy with menu entries.
- Requires Root: if checked, the user will be prompted for their password when the application starts. This is important if the program requires special users or groups to be created or an installation script needs access to the local system to make modifications.
If you click “Menu”, two more fields will be added to the “Entry Details” section:
- Category: indicates the menu category that the entry will be placed under when listed in the desktop environment. Click the green arrow to see the available menu categories. The recommended category will have a small black arrow next to it.
- MIME Patterns: used to associate a space-separated list of file types with the application. This is useful when paired with the “Make Invisible” option. For example, consider an application which has two binaries representing two different aspects of the program and an additional binary that asks which of the two you want to use. You could create menu entries for all three binaries, but make the two specific ones invisible and associate file types with them. This means that when a user tries to open one of those file types, it will automatically run the particular binary that uses it, rather than prompting the user for input about what to do with the file.
If you make any changes in this tab, click the “Save” button to save them.
This tab, shown in Figure 8.1e, is used to create custom installation and removal scripts for the PBI.
If you click on the drop-down menu, you will see a list of available script types, with an icon indicating whether or not a custom script exists in the module. Selecting a script type will activate a "Create" button if the script does not exist, or will display the full script in a box for editing.
The possible script types are:
- post-install.sh: script run after installation of the PBI.
- pre-remove.sh: script run before deletion of the PBI.
Service Configuration Tab
The "Service Configuration" tab, shown in Figure 8.1f, allows you to setup a remote graphical configuration interface for the application. This is generally used for services or daemons that do not have a configuration interface and lets the user perform tasks with that service such as modifying runtime configuration options or starting, stopping, and restarting the service. Any configurations will appear in the new AppCafe web interface (pc-softweb), which allows the user to manage those services from remote systems or phones.
The "Visual Options" list is used to setup the options for controlling the service. To add an entry to this list, click "New Option" which will open the screen shown in Figure 8.1g.
The following fields are available when adding a visual option. Examples for values to use in these fields can be found in the.
- Key: the option to set.
- Default Value: the default value for the option.
- Option Type: supported types are ComboBox, NumberBox, or TextBox.
- Name: the name that will appear.
- Description: the description that will appear.
- Options List: appears when the ComboBox "Option Type" is selected. Use the "+" and "-" buttons to add or remove options to appear in the list and the up and down arrow buttons to order the items in the list.
- Number Limits: appears when the NumberBox "Option Type" is selected. Set the "Maximum" and "Minimum" numbers for the selection, where the default of 0 is unlimited.
- Text Options: appears when the TextBox "Option Type" is selected. Set the "Max Length" of allowed user input, where the default of 0 is unlimited. If the text should be hidden, for example when the user is inputting a password, check the box "Hide Text".
If you create a new visual option, click the "Configuration Scripts" button as these are required for the service management configuration to work properly. Three configuration scripts are required:
- getconfig.sh: script for retrieving the current value for a given "Key" from the service configuration.
- setconfig.sh: script for changing a configuration value for the service.
- doneconfig.sh:script that is run after changing configuration values. Usually used for starting or restarting the service.
Since none of the configuration scripts are created by default, you will need to click the "Create Template" button for each script to open an editable version of the template. Each template includes a description of the script, how it is run, and lists its input variables. Edit the template as needed and click the "Save Script" button to save the script. Repeat for each of the three required scripts.
Once you have configured a PBI module, you can additional modules by clicking the “New” button. To edit an existing module, click the “Load” button and select the module name.
Bulk Module Creator
When creating a custom repository, it can be convenient to quickly create all of the modules for a port category, then customize the modules as needed. To do this, click File → Bulk Module Creator which will open the screen shown in Figure 8.1h.
Click the icon next to “Base Directory” and browse to the location to hold the modules. For example, if the custom repository is being created in ~/myrepo, browse to that directory.
Next, click the icon next to “Category” and select the ports category to recreate in the “Base Directory”. For example, if you select the “accessibility” category, it will create a directory called ~/myrepo/accessibility/ containing subdirectories which represent the PBI modules for the existing packages in that directory.
If the selected “Base Directory” and “Category” already exist and you want to overwrite any existing PBI modules, check the box for “Overwrite existing modules”. Otherwise, the Bulk Creator will ignore any existing modules.
If you only want to create certain types of applications, check or uncheck the boxes for the application types: graphical, text, server, other. “Other” is any package that does not install any graphical images, does not install any files into /usr/local/bin/ or /usr/local/sbin/, and does not install any files into /usr/local/etc/rc.d/. This generally occurs with packages that just install libraries or plugins, and meta-packages which do not install anything and just have a bunch of dependencies.
After making your selections, click the “Start” button. A progress bar will indicate the status, which goes by quickly, and then summarize the number of modules built. An example is shown in Figure 8.1i. After reviewing the summary, click the “Close” button to return to the main EasyPBI screen.
When creating modules, Bulk Creator will skip the following:
- any existing modules, unless “Overwrite existing modules” is checked
- any package types which were unchecked
- if the package is not found in the repository
Repeat for each category that you want to include in the custom repository.
To dit EasyPBI's settings, click Configure → Settings to open the screen shown in Figure 8.1j.
The options in this screen allow you to configure the following:
Switch User Utility: the full path to the binary which is used to switch to administrative access. By default, it is pc-su.
Auto-Detect: if this button is clicked, a pop-up message will indicate that it will return all of the EasyPBI settings back to their defaults. Click “Yes” to do so or “No” to cancel the operation.
Modules: the full path to the directory to save modules which are created with the “New” button.
Resources: the full path to the directory to store any extra resources. These are described in resources/.
Default Icon: the full path to the default icon used by PBI modules.
The “Configure” menu contains two other options:
- Package Module: when this option is clicked, a pop-up message will indicate that a copy of the current module has been packaged within the module directory.
- Refresh Module: click to refresh the module's settings.
The “Help” menu contains three options:
- About: displays the EasyPBI version, license, and development history.
- FreeBSD Ports: opens in the default browser.
- PBI Modules: opens the PBI Module Builder Guide in the default browser.
PBI Module Components
While EasyPBI is the recommended way for creating PBI modules, it is possible to manually create the various ASCII text files used in the modules. This section describes the various files that comprise a PBI module. A PBI module is simply a collection of files which controls the contents of the PBI and its appearance in AppCafe®.
When creating a PBI module, create a directory on your computer to hold the module's files. For example, if you are creating a PBI module for firefox, create the following directory using this command:
As you create the subdirectories and files needed by the PBI module, save them to the directory for that module.
If the application requires the user to read a license agreement, save that license as a file named LICENSE in the directory of the PBI module. 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.
The pbi.conf file is mandatory. It is a simple shell script that contains the information needed to build the PBI. 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.
export PBI_OTHERPKGS PBI_PLUGINSexport PBI_SCREENSHOTS PBI_RELATED
Table 8.1a 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.
|PBI_ORIGIN=||mandatory; the category/portname of the FreeBSD package|
|PBI_PROGNAME=||mandatory; name of the application|
|PBI_PROGWEB=||mandatory unless does not exist; website for the application|
|PBI_PROGAUTHOR=||mandatory; often found at the website for the application|
|PBI_LICENSE=||the type of open source license used by the application|
|PBI_TAGS=||a comma separated list (no spaces) of search terms associated with the application|
|PBI_PROGTYPE=||mandatory; use “Graphical” or “Text”|
|PBI_CATEGORY=||the category to place the application into; click “Browse Categories” within AppCafe® to see the list of categories|
|PBI_OTHERPKGS=||a space separated list in the format category/portname of other applications to bundle into the PBI|
|PBI_PLUGINS=||a space separated list in the format category/portname of similar “raw packages”|
|PBI_SCREENSHOTS=||a space separated list of URLs to screenshots in .png or .jpg format|
|PBI_RELATED=||a space separated list in the format category/portname of similar PBIs|
|export||mandatory; followed by a list of all of the variables that will be included when the PBI is built|
The resources/ directory can contain extra files you wish copied into the PBI application directory. This is often the best place for the LICENSE file and other files not included with a port.
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 8.1a shows the firefox.desktop files for the firefox PBI:
Example 8.1a: Firefox XDG Entries
more xdg-menu/firefox.desktop #!/usr/bin/env xdg-open [Desktop Entry] Value=1.0 Type=Application Exec=firefox %U Path= Icon=share/pixmaps/FireFox-128.png StartupNotify=true Name=Firefox more xdg-desktop/firefox.desktop #!/usr/bin/env xdg-open [Desktop Entry] Value=1.0 Type=Application Exec=firefox %U Path= Icon=share/pixmaps/FireFox-128.png StartupNotify=true Name=Firefox
Exec= should reference the PBI's executable and any required switches.
If Icon= is blank, the PBI will automatically use the icon.png located in the module's directory.
For more details on the XDG menu specifications, please refer to the.
The xdg-mime/ directory is used to register file associations according to the. This requires the creation of an XML file. The example shown in Figure 8.1b adds the MIME information for gimp, so that it can be available as an application choice in a web browser:
Example 8.1b: 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>
- Table 8.1a: Commonly Used pbi.conf Variables