EasyPBI is a graphical application that makes it easy to build a PBI module from a FreeBSD port. EasyPBI can be launched from Control Panel or by typing EasyPBI.
Quick Start to Creating a PBI Module
Before building a PBI, refer to theto determine which PBIs have been requested by users. You should also check that a module does not already exist for the PBI in the . Existing PBI modules are listed alphabetically, according to their category in the ports collection.
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. In the screen shown in Figure 8.1b, click the "Select" button next to "FreeBSD Port". This will open a list of the FreeBSD port categories. Expand the category that contains the port you wish to convert, and select that port from the list of ports in that category. In this example, the net-p2p/linuxdcpp port has been selected.
A generic icon will be supplied for the module. You can change the default icon by clicking the Icon File “Select” button. When selecting a custom icon, use a 64x64 .png file with a transparent background. After making your selections, click “OK”. EasyPBI will load the module as seen in Figure 8.1c.
To build the PBI with its default configuration, click the "Save Configuration" button, click the "Build PBI" tab, then click the "Build PBI" button.
The next section describes all of the EasyPBI settings should you wish to further customize the module before building it. Otherwise, skip ahead to the section on building and testing the PBI module.
The previous section demonstrated how to quickly generate a PBI using the default module settings. This section describes which options are available for customizing PBI modules.
To setup the options for building PBIs, click Options → EasyPBI Settings. There are two available tabs which are discussed in this section.
PBI Builds Tab
The PBI Builds tab is shown in Figure 8.1d. The options in this screen can be summarized as follows:
PBI Output Dir: specifies the directory to store the built module. By default, it is the EasyPBI/PBI subdirectory of the user's home directory. Click the “Select” button to browse to another location.
Digitally Sign PBI: if you check this box, you will be prompted to select the location of the file containing the OpenSSL signature which will be used to digitally sign the PBI so that it is ready for for tamper-evident distribution. Create Your Own PBI Repository provides instructions for creating a signature file.
Local Paths Tab
The Local Paths tab is shown in Figure 8.1e. The options in this screen allow you to configure the following paths:
External Utilities: the default paths of the utilities used by EasyPBI to build PBI modules. The "Auto-Detect" button can be used to detect a new path if a missing utility is installed onto a FreeBSD system running EasyPBI.
Default Search Paths: the default directory that new modules are saved to, the initial search location for icons and other resources, and the default icon used by PBI modules.
PBI Configuration Tab
As seen in the Figure 8.1c, EasyPBI automatically fills in some information when you browse to a package to convert into a PBI. Under "Program Information" the port's name, author (FreeBSD maintainer), and default icon are typically filled in for you. You should review these fields for accuracy:
- if necessary, correct the capitalization in "Name".
- if the application's author is not listed in the port information and the application has a specific author, this should be corrected.
- if you wish to change the default icon, see the next section on the Resources tab to add additional icons to the drop-down selection list.
If the application should only be installed and uninstalled using root privileges, check the box "Requires Root Permissions". 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.
By default, the PBI will be built using the default options provided by the port. Some defaults can be overridden by checking the following boxes to view the available options. Figure 8.1f shows this screen with each of these boxes checked.
- View Package Overrides: this section allows you to override the default version number, URL for the application's website, and license. 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.
- View Repository Information: this section allows you to add search tags which are used by AppCafe®. You can specify the application type as Graphical, Text, or Server as well as specify which category the application will appear in in AppCafe®. Click the suggestions button with the green arrow to view the available types or categories. You can also specify the URL to an icon to use for the PBI.
- View Repository Management: the "Build Key", "Revision #", and "Priority" fields are typically only used by the maintainers of the official PBI repository and users who create and manage their own PBI repositories. By default, the PBI build process uses TMPFS to speed up the build as it instructs the PBI build process to save all of the relevant port build pieces into memory rather than disk. If your build system has less than 2GB of RAM or you get “Out of memory” errors when building a large port, check the "No TMPFS" box.
The resources tab, shown in Figure 8.1i, displays any extra files to included in the PBI. If you click the entry for an image file, the full size image with size and type information will be displayed. For other types of files, such as scripts, EasyPBI will attempt to display the text inside the file.
This tab is mainly used to add PNG images to be used as PBI icons. If you add an icon, use a 64x64 .png file with a transparent background.
An example of an additional file would be an application that requires the user to accept a License. Use the “+Add File” button to browse to the location of the LICENSE file.
If the application uses custom installer graphics, add them using this screen.
Another use is to create a wrapper script for starting the application. This is generally used for applications that have an environment variable that needs to be set before starting the program, such as JAVA_HOME. A custom script could also be used to verify that the service is enabled or to generate a custom configuration file.
EasyPBI will assist in creating a wrapper script if you click the “+Wrapper Script” button. This will prompt for a filename in the format application_name.sh. Click the "OK" button and an entry will appear as EasyPBI automatically generates the script from a template that sets the most commonly used variables. In the example shown in Figure 8.1j, click the area below the DO SOMETHING HERE comment to customize the script. Creating a wrapper script is considered an advanced task that requires some knowledge of shell scripting, so feel free to ask for help on theor on the .
XDG Entries Tab
This tab, shown in Figure 8.1k, 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.
As seen in this example, the 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 an 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: click the green arrow to select the executable or script that is used to start the application. Some ports have multiple binaries, so select the one associated with the program. If you created a script in the Resources tab, it will be added to the list and should be selected.
- Icon: the available icons will include the default icon and any that you added in the Resources tab.
- Open in Terminal: used to specify whether 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.
Figure 8.1l shows the "Entry Details" that are available when "Menu" is selected.
This screen adds two fields:
- 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.
This tab, shown in figure 8.1m, is used to view and edit installation scripts used by the PBI.
If you click on the drop-down menu, you will see a list of available scripts, with an icon indicating whether or not that script exists in the module. Selecting a script will activate a "Create" button if the script does not exist, or will display the full script in a box for editing.
For “Local Source” PBIs, the only valid scripts are pre-install.sh, post-install.sh, and pre-remove.sh. EasyPBI will only display the list of valid scripts.
External Links Tab
This tab, shown in Figure 8.1n, is used to setup links for additional binaries within the PBI.
This screen becomes important if you add additional files to the PBI, such as wrapper scripts, that are not included in the FreeBSD port. Also, if you are packaging a local directory into a PBI instead of using a FreeBSD port, this screen is needed to setup the main binaries for the application.
When adding an entry, configure the following fields:
- File: the binary location in the PBI directory. Click the green arrow to select the binary to link. For FreeBSD ports, the binaries from the port are already configured, so you do not need to add them here unless you want to change the "File Type".
- Link To: input the path to link the binary to on the base system, relative to /usr/local/.
- File Type: click the green arrow to set the type of link.
The following "File Type"s are supported:
- binary: indicates that this is an executable. The PBI will automatically create the necessary wrapper and PATH links.
- linux: indicates that this is a Linux executable. EasyPBI will automatically create the necessary Linux wrapper and PATH links.
- keep: instructs the PBI to not overwrite an existing file when linking a file into the LOCALBASE. By default, LOCALBASE is set to /usr/local.
- replace: instructs the PBI to overwrite an existing file when linking a file into the LOCALBASE.
- nocrash: disables the crashhandler GUI from running on this PBI. However, the glue for the crash handler is not built into the base system yet.
Build, Test, and Submit the PBI
The PBI Builder pane provides a graphical front-end to the PBI build structure. Once you have finished using "Module Editor", click the "PBI Builder" pane to build the PBI on your local system.
In the example shown in Figure 8.1o, the user has created a PBI module for the FreeBSD port p7zip. Since this is the module that appears at the top of the screen, this is the module that will be built if the user clicks the "Build PBI" button.
To build a different module, either click the "Load" button to browse to the location of a previously saved PBI module or the "New" button to select a different FreeBSD port or local source to build.
To start the build of the PBI module, click the "Build PBI" button. A pop-up message will remind you that a working Internet connection is required so that the build process can download the source required to build the port. It will also prompt for the user's password.
The first time you build a PBI, EasyPBI will download the chroot environment used to build PBIs. Subsequent builds will reuse this environment. The build process itself may take some time, depending upon the size of the port selected and the speed of your computer. Build messages will be displayed in the white window. EasyPBI will inform you when the PBI build is finished, and whether it was successful or not.
If you wish to build a 32-bit version of the PBI on a 64-bit system, check the box "Build 32-bit".
During the build, you can create additional PBI modules by clicking the "Module Editor" pane. Click the "PBI Builder (Working)" pane to check on the status of the build. However, you can only build one PBI module at a time. If you need to stop the build process, click the "Cancel Build" button.
If the build fails, you may need to modify the module using "Module Editor". Click the "Save Build Log" button and browse to the location to save the log file which can be read with any ASCII text editor. Read the saved log to determine the error so that you can modify the module as needed. If you are unsure how to fix the PBI module, send the log for the failure to the.
Test the PBI
Once your build is finished, test the PBI to ensure that it installs and that the application works.
To install the PBI, become the superuser, cd to your PBI directory, and use the pbi_add command. Unless you have specified your own digital signature, include the --no-checksig option.
Password: cd ~dru/EasyPBI/PBI ls p7zip-9.20.1-amd64.pbi p7zip-9.20.1-amd64.pbi.sha256 pbi_add --no-checksig p7zip-9.20.1-amd64.pbi Verifying Checksum...OK Extracting to: /usr/pbi/p7zip-amd64Installed: p7zip-9.20.1
If the module installs successfully, perform the following tests:
- for a graphical application, verify that a desktop icon was created (from a desktop that supports icons), that an entry was added to that desktop's application menu, and that the application successfully launches from the application menu. If you used a custom icon, verify that the icon was used.
- start the application from the command line to determine if there are any error messages at application launch. When starting the application, specify the full path to the application's binary to make sure that you are testing the PBI's binary.
- for a graphical application, go through the various menus to see if they produce any errors. If you encounter any error messages in either starting or using the application, record them. If the fix for resolving the error messages is not clear to you, send the error report the .
If you modify any settings in the PBI's module, rebuild the PBI then test again to see if the changes fixed the PBI.
Submit the PBI Module
Once you are satisfied with the PBI, go to Options → Package Module. A pop-up window will indicate that the module has been successfully packaged within the default "Modules" directory. The file name for the example PBI would be ~dru/EasyPBI/Modules/p7zip.tar.gz.
If you send that file to the, it will be added to the PC-BSD® build servers so that the PBI can be built. Once the built PBIs are tested, they will be added to AppCafe® so that other PC-BSD® users can benefit from the PBI.