(Sorry for the inconvenience)
EasyPBI is a graphical application that makes it easy to build a PBI module from a FreeBSD port. EasyPBI version 2 ships with PC-BSD® rolling releases and can be found in the Control Panel. If you are running PC-BSD® 9.1-RELEASE, the EasyPBI found in the control panel is for the original version. You can upgrade this version following the instructions in the next section.
The new features built into EasyPBI version 2 include:
- The ability to package a local directory into a PBI without using the FreeBSD Ports Collection.
- Adds an additional build option to build 32-bit PBIs on 64-bit systems.
- Complete support for editing installation wrapper scripts, as well as a basic template for creating new binary wrapper scripts.
- Improved support for full creation/editing of XDG desktop/menu entries with easy MIME type integration.
- Support for the OptionsNG format for setting port build options is enabled by default.
- Support for multiple-lines when specifying build options.
Additionally, the following UI improvements were made:
- New "Settings" dialog for setting/changing default directory paths, PBI build settings, and any external utilities.
- New "Ports" dialog displays the last time the ports tree was updated and simplifies the process of using portsnap or svn to update the system ports tree.
- New "About" dialog for quickly viewing information about EasyPBI such as its license information and development history.
Getting EasyPBI Version 2
If you are running a rolling release, you already have EasyPBI version 2. You can verify this by going to Control Panel ➜ EasyPBI ➜ Information ➜ About EasyPBI.
If you are running PC-BSD® 9.1-RELEASE, you can install EasyPBI version 2 Using AppCafe®. You will need to specify the full path to EasyPBI2 in order to run this version by typing /usr/pbi/easypbi-amd64/bin/EasyPBI.
If you are running FreeBSD, you can install the sysutils/easypbi/ package or port. To start the application, type EasyPBI.
The rest of this section demonstrates how to use EasyPBI version 2 to convert an existing FreeBSD port into a PC-BSD® PBI. You may wish to skim the section on how to Create PBIs first, as well as refer to that section should you have trouble creating a PBI or wish to create a more complex PBI.
When EasyPBI starts up, it will automatically check for a few external utilities that are necessary for full usage of EasyPBI. If there are any that are missing, you will receive a message like the one shown in figure 8.1a.
Figure 8.1a: Missing External Utilities
If this message appears, click “Options” → “EasyPBI Settings” → “Detected Utilities” tab. Any missing utilities will not have the path to that utility filled in. For most PC-BSD® users, this warning occurs if the FreeBSD ports tree is not installed, as seen in the example in Figure 8.1b..
Figure 8.1b: Ports Tree not Installed
Updating the FreeBSD Ports Tree
To fetch or update the FreeBSD ports tree, you will need to start by clicking on the “System” → “Get FreeBSD Ports” menu button. This opens up the window shown in figure 8.1b, and will allow you to fetch/update the FreeBSD ports tree for just in current user (in the user's EasyPBI directory) or for the entire system (in /usr/ports). If you have administrator/root priveleges on your system, I recommend using the system ports tree since it will be available for all users, and the default PC-BSD® settings for ZFS usually compress that directory to save disk space.
Figure 8.1b: Updating FreeBSD Ports
PBI Build Settings
To setup the options for building PBI's with EasyPBI, you will need to click on the “Options” → “EasyPBI Settings” menu button to open up the settings window. In figure 8.1c you can see the first tab that shows what PBI build options are available.
Figure 8.1c: PBI Build Settings
If you choose to digitally sign your PBI's, you will need to supply the location of the file that contains your openssl signature. This will digitally sign all of the important pieces of a PBI so that it is ready for for tamper-evident distribution.
The TMPFS option allows the PBI build process to save all of the relevant port build pieces into memory rather than saving it to disk. This will speed up the build process, but you want to make sure that you have a decent amount of memory available ( >2GB). If you happen to get “Out of memory” errors from a PBI build, you will need to turn this option off for that particular build. This can happen occationally when rather large ports (like office programs and such).
The package caching option is recommended for all users. This option saves all compiled ports as packages in the cache on your system, allowing the PBI build process to become much faster by using the pre-build packages from the cache whenever possible rather than re-compiling every port dependency for the PBI's you build. Just in case you run into problems with any packages in your cache, there are two additional options for dealing with the cache. The first option is to simply clear all packages from the cache and start fresh. The second option is for the situation where a particular package consistently causes problems with PBI builds. In this case, you can add that particular package to the “Ignore” list. This will remove the designated packages from the cache immediately before you start each build, ensuring that it will always compile that port for each build that requires it.
Default Path Settings
The next tab in the settings window is shown in figure 8.1d, and lets the user set some default search paths for EasyPBI. The first option lets you set the default directory to use when loading PBI modules, and it is also the directory that any new modules get created in. The option labelled “Icon Dir” sets the initial search location for icons and other resources. The last option lets you set the default icon that is gset when you initially create a new module.
Figure 8.1d: Local Paths Settings
The last tab in the EasyPBI Settings window is the External Utilities tab. This tab (as shown in figure 8.1e) shows the detected location of the external utilities required for all of EasyPBI's features to be available. This allows you to be able to manually set the location of any of these utilities if you happen to have them installed into non-standard locations. In addition, there is a button that allows you to return to the auto-detected configuration paths, just in case it gets all messed up somehow.
Figure 8.1e: Detected External Utilities
The module editor for EasyPBI version 2.0 now supports complete control over all the options available for PBI's. Most of these options will not be necessary for the majority of PBI use cases, but they are available for those few programs that just need some extra tweaking to be able to work properly. EasyPBI provides suggestions and default settings whenever there is a green arrow next to an option within the editor. Just click on the arrow to see any available suggestions, then click on the one that you wish to select to have EasyPBI add it to the proper option within the module for you. Now let's go through each of the tabs within the editor and explain the options. NOTE: For tutorials on how to produce a PBI for the majority of use cases, please look at the examples at the end of the guide.
In figure 8.1f we can see the PBI Configuration tab of the module editor. This tab is probably the most important out of all of them, because it lets you set the required information about the program being packaged as a PBI.
Figure 8.1f: PBI Configuration
When you create a new module from a FreeBSD port, EasyPBI will try to automatically fill in this information for you from the available port information, but it is a good idea to look through it and make corrections as necessary. The value that I generally have to adjust is the program name, because quite often the FreeBSD port does not have the full program name list with the proper capitalization. The next thing to definitely check is the program author, since if the author is not listed in the FreeBSD port, EasyPBI will supply the email for the FreeBSD port maintainer instead (because that is the first person to contact about isues with the program). The icons that are available in the pulldown box are dependent upon what PNG images files have been added to the PBI resources. See the resources tab for additional information on adding icon files. The build information box provides all of the options available for building a PBI. For a PBI from local sources, this just contains the directory that you are going to package as a PBI, while for a PBI from a FreeBSD port there are a number of other options. For converting a FreeBSD port to a PBI, the only option that is required is the “Main FreeBSD Port” option. This should be set for you automatically based upon the port that you selected when creating a new module, but you can also change it here by clicking on the “Change Port” button. If there are any special options available for the port (click the “Information” → “FreeBSD Ports” menu button to open up a web browser with information about the port), you can enable them in the “Port Build Options” box. EasyPBI will try to autodetect the options that are available, and clicking on an available option from the recommendations will automatically add it to the box in the proper format. If you discover that the port appears to be missing a dependancy for the main program you are packaging as a PBI, you can add additional FreeBSD ports to the “Make Port Before/After” options. If the missing dependency is causing the main port to not even build properly, then you will want to add it to the “Make Port Before” option, otherwise if it is a missing runtime dependency you will want to add it to the “Make Port After” option. The last option available is for both local and port PBI modules. The “Requires Root Permissions” checkbox lets you set whether the PBI can only be installed/uninstalled with administrator (root) privileges. This is important if the program requires special users/groups to be created, or an installation script needs access to the local system to make modifications.
NOTE: Changes to the PBI configuration will not be saved to the module until you click the “Save” button. So be sure to save your work before moving to other tabs!
The resources tab displays any extra files that will be included in the PBI (as shown in figure 8.1g). If you click on a file, for images it will show the full size image with size and type information, for other files it will attempt to display the text inside the file (for editing scripts). This tab is mainly used for adding PNG images to be used as icons for the program, but is not restricted to this. One additional use for resources that is more common is to create a wrapper script for starting the program. This is generally used for applications that have some some special environment variable that needs to be set before starting the program (such as JAVA_HOME). EasyPBI can now help in setting up a wrapper script byt clicking on the “+Wrapper Script” button. This will prompt you for a filename (I recommend <binary-name>.sh), and will generate a template for the script that sets a couple of the most commonly used variables. Creating a wrapper script is considered an “advanced” task that requires knowledge of shell programming, so feel free to ask for help on the forums or the PBI developers mailing list if you need some assistance.
Figure 8.1g: Resources
This tab allows the user to create desktop icons and menu entries for the application to be easily started from within a desktop environment. This is the most important step for graphical applications after the PBI configuration, as it lets you configure the primary method that users will interact with the program. You can see the entries that are currently in the module on the left side of the tab, and clicking on any of the files will display its details on the right. You may remove an entry by clicking the “minus” button, or create a new entry by clicking on the white paper button under the entry list. On the right side of the tab you can edit the currently selected entry and click the “Save” button to overwrite it, or click “Add” to save the details as a new entry, easily letting you make copies of any entry.
Figure 8.1h: Desktop Entries
Figure 8.1h shows the options that are available for desktop entries, and while the labels are fairly self-explanatory, lets go through and explain them. First is the “Name” for the entry. This is the text that the application user will see for the entry, and usually you just make it the full name of the application that the entry starts up. Next is the actual binary/executable that is used to start the application. EasyPBI will try to make recommendations based upon the main FreeBSD port being used, but you can manually set this as needed. After that is the icon to be used for the application. Just as with the program configuration, the available options are dependent upon the PNG resources available in the PBI. The two checkboxes at the end are more for special-case options. The “Open in Terminal” checkbox let you 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. The “Make Invisible” option lets you setup the entry to not actually be shown. This is not as useful for desktop entries (where the whole purpose is to be seen), but will come in much more handy with menu entries.
Figure 8.1i: Menu Entries
Figure 8.1i shows the options that are available for menu entries. Most of them are exactly the same as the ones for desktop entries, but there are two new ones that will be rather important. The first new option is labelled “Category” and this is the menu category that the entry will be placed under when listed in the desktop environment. The available menu categories are listed by EasyPBI in the suggestions box, with a small arrow next to the one that EasyPBI recommends for the application based upon the main FreeBSD port information. The last option is called “MIME Patterns” and lets you associate a space-seperated list of file types with the application. This becomes extremely useful when paired with the “Make Invisible” option. For example, let's assume that your application has three main binaries, one each for two different aspects of the program, and an additional one that basically askes which of the other two you want to use. You could setup 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 (as shown in figure 8.1j) allows you to view and edit any installation scripts that are included within the PBI. If you click on the pulldown box, you will see a list of the scripts that are available, with icons next to them indicating if that script exists in the module. Selecting a script will give you the option to either create it (if it does not exist) or will display the full script in a box for editing.
NOTE: Changes to the script of any kind (including creating one) will not be saved to the module until you click the “Save” button. So be sure to save your work before moving to other tabs or scripts!
ADDITIONAL NOTE: For “Local Source” PBI's, the only valid scripts are "pre-install.sh", “post-install.sh”, and “pre-remove.sh”. Later versions of EasyPBI will automatically change the list of valid scripts appropriately.
Figure 8.1j: Installation Scripts
This tab lets you setup links for files within the PBI onto the local system. This is generally used only for additional command-line program binaries, or binaries in dependencies to the main FreeBSD port being packaged as a PBI. This becomes very important when you start adding additional files (such as wrapper scripts) to the PBI that are not included in the port. If you are packaging a local directory into a PBI instead of using the FreeBSD ports, this is the method by which you setup what the main binaries are for the application. The “File” entry is for the file location in the PBI directory, and the “Link To” option is where you want to link it on the base system (relative to /usr/local/). The “File Type” option lets you set what type of link it needs to be, with options available from the suggestions button. Details about the different file types are available below. EasyPBI will suggest any binaries that it detects from the main port (in case you want to set a different file type), but in general this is not used very often.
NOTE: The files that you want to have listed here are any files that need to be available on the users general system path. For FreeBSD ports, the binaries from the main port are already setup for this by default (you don't need to add them here unless you want to change the file type).
- binary: indicates that this is an executable. The PBI will automatically create the necessary wrapper and PATH links for you.
- linux: indicates that this is a Linux executable. EasyPBI will automatically create the necessary Linux wrapper and PATH links for you.
- 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. Note that the glue for the crash handler is not built into the base system yet.
Figure 8.1k: External Links
EasyPBI provides a front-end to the PBI build structure, allowing you to use a PBI module to build the full PBI on your local system. As shown in figure 8.1l, this interface is relatively simple, with buttons to start and stop the build, as well as save the build log (in case you need to seek assistance). If you are using a 64-bit system, there is also an additional checkbox allowing you to build a 32-bit PBI rather than keeping with the system architecture. Performing a PBI build will require administrator (root) access on your system, as well as an active internet connection if building a PBI from a FreeBSD port. The current options for the PBI build process can be configured in the EasyPBI settings. EasyPBI can only perform one build at a time, and you are able to load and edit other PBI modules while a PBI is building in the background. You will receive a notification about the success/failure of the PBI build when it is finished, or you can keep an eye on the build log to see how it is progressing.
Figure 8.1l: PBI Builder
Example: Converting a FreeBSD port to a PBI
Step 1: Create a PBI module
Click on the "New" button at the top of the window to open up the small dialog shown in figure 8.1m.
Figure 8.1m: New Module Dialog
Make sure that the "FreeBSD Port" option is selected, then click select the FreeBSD port that you wish to convert. You may either type in the port directory/name manually, or click the "Select" button to open up the current FreeBSD ports directory for selecting a port. Once this is done, you may either select a PNG icon to use for the application, or simply use the default icon supplied by EasyPBI. Click "OK" to create the new module.
Step 2: (OPTIONAL) Checking the new module
Once a new module has been created, it is usually a good idea to just browse through the module in the editor and make sure that everything looks good. The main things to check are on the "PBI Configuration" tab (figure 8.1n), but if it is a graphical application you will also want to go to the "XDG Entries" tab and create a desktop/menu entry for the application (figure 8.1o).
Figure 8.1n: Example Module Configuration
Figure 8.1o: Example Menu Entry
Step 3: Build the PBI
Open up the PBI Builder, then click on "Build PBI" to start the build process. This will require root permissions as well as an internet connection, and might take a while to finish (depending on your system hardware and PBI build settings). Once the PBI build is finished, a notification window will appear telling you whether the build was successful or not.
NOTE: While a PBI build is running, you may go ahead and create/edit other PBI modules without interfering with the build process.
NOTE 2: To install a newly-created PBI, you can either open up the PBI output directory in a file manager and double-click on the PBI file, or you can run "pbi_add <pbi-file>" from the command line.
Figure 8.1p: Example PBI Build
Example: Creating a PBI from a local directory
Submit the Module
Once you are satisfied with a PBI, make sure that the module is loaded, then click on the “Options” → “Package Module” menu button. A pop-up window will indicate that the module has been compressed and that a .tar.gz file has been added to the PBI module directory. This means that if you look at the path for the currently loaded module at the top of the screen, you can find the packaged form of the module in the same directory.
If you send that file to the, it will be added to the PC-BSD® build servers so that the 32- and 64-bit versions of 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.