| EasyPBI |
EasyPBI is a graphical application that makes it easy to build a PBI module from a FreeBSD port. Beginning with PC-BSD 9.1, EasyPBI ships with PC-BSD and can be found in the Control Panel.
This section demonstrates how to use this utility to convert an existing FreeBSD port into a PC-BSD PBI. You may wish to skim the PBI Module Builder Guide first, as well as refer to the Builder Guide should you have trouble creating a PBI or wish to create a more complex PBI.
Creating a PBI Module
If you double-click the EasyPBI icon in Control Panel, you will see the screen shown in Figure 10.7a.
If ports is not installed, you will first receive the pop-up message: "The FreeBSD ports tree is not installed for this system or user. Please install the ports tree as root to make it available for all users, or push 'File'->'Get Ports' to retrieve the ports tree for this user only". Since EasyPBI is used to convert an existing FreeBSD port into a PBI module, you will need to install the FreeBSD ports collection using one of the methods in the message. If you want the ports tree to be available to any user, go to Control Panel -> System Manager -> Tasks. Use this method if multiple users will be using the EasyPBI utility. Alternatively, if you only want the ports tree to be available to the current user, click File ➜ Get Ports from within EasyPBI; this will fetch the ports tree and place it in the user's home directory.
Figure 10.7a: EasyPBI Graphical Interface
When determining which PBIs need to be built, refer to the PBI Requests forum to determine which PBI's have been requested by users. You should also check that a module does not already exist on the PBI Modules section of trac.
To create a new module, click the "New Module" button and use the browser to select the desired port from the FreeBSD ports tree. Once a port is selected, EasyPBI will attempt to automatically supply the port information for the PBI and display the results on the GUI. In the example shown in Figure 10.7b, the net/xrdesktop port has been selected and the fields have been auto-filled in.
Figure 10.7b: Reviewing the Port's Information
You should review these fields for accuracy. If you click "Get Port Info" FreshPorts.org will open in the default web browser so that you can view additional information about the port.
A generic icon will be supplied for the module; you can change the default icon by clicking the "Choose Icon" button. When using a custom icon, use 64x64 .png files with transparent backgrounds.
If the program provides a GUI, check the box "GUI App".
Once the port information is complete, click the "Create Module" button and EasyPBI will produce a generic PBI module. A message will indicate the location of the module, as seen in the example in Figure 10.7c:
Figure 10.7c: PBI Module Created
Build the Module
2. Build a PBI from the module: once your module is created, click on the "Build PBI" tab and click the Select Module button to browse to the module you just created. Figure 10.7d shows this tab with our example PBI selected.
Figure 10.7d: The Build PBI Tab
The options in this tab allow you to perform the following actions:
Save Settings as Defaults: once you are satisfied with your settings, click this button and EasyPBI will remember your settings between uses.
Change the Output Directory: allows you to specify which different directory will store the built module. By default, it is the EasyPBI/PBI subdirectory of the user's home directory.
Change the Digital Signature File: the PBIs available from the PC-BSD repositories are digitally signed by the PC-BSD project's signature file. If you are creating your own repository, you can use your own digital signature file by browsing to its location.
Use TMPFS: if your build system has a lot of RAM, selecting this option can speed up the build.
Select Module: select the previously created module which you would like to build.
Build PBI: starts the build of the PBI using the settings contained within the PBI module. It will prompt you for the superuser password and requires a working Internet connection to build the PBI. This process may take quite a while, depending upon the port selected and the speed of your computer. The build messages will be displayed in the window at the bottom of the tab. EasyPBI will inform you when the PBI build is finished, and whether it was successful or not.
Stop Build: stops the build process. Click the "Build PBI" button to resume the build.
Save Build Log: useful if the build fails.
You can produce additional modules from the "Create Module" tab while a PBI build is running.
More Advanced Modules
The Module Editor tab, shown in Figure 10.7e, allows you to further customize the PBI module.
Figure 10.7e: Module Customization Using Module Editor Tab
Several tabs are provided, allowing you to perform the following advanced actions. Note that most PBI modules do not require you to make any configuration changes in the Module Editor tab. This tab allows the creation of more complex PBI modules that are built with additional FreeBSD ports or scripts which are not provided by the default FreeBSD port.
1. pbi.conf: Typically the program name, website, and author are left at their defaults. If the information is incorrect, you should email the FreeBSD port maintainer (shown in the Program Author) field so that they can update the FreeBSD port. If you choose to replace the default icon, use a 64x64 .png file with a transparent background. If your PBI requires a dependency that is not provided by the FreeBSD port, use the + button next to "Make Port Before" to select the needed port. If you wish an additional port to be included with your PBI, use the + button next to "Make Port After" to select the desired port.
The "Make Options" field lets you specify a space separated list of options. The available options and their default settings will be listed in the OPTIONS= section of the port's Makefile.
If the resulting PBI needs to be run as the root user, check the "Require Root Permissions" box.
2. Resources: this tab, shown in Figure 10.7f, is used to
Figure 10.7f: PBI Module Resource Configuration
3. Desktop/Menu Entries: this tab, shown in Figure 10.7g, is used to
Figure 10.7g: Customizing the PBI's Desktop and Menu Entries
4. External-Links: this tab, shown in Figure 10.7h, is used to
Figure 10.7h: Configuring Custom Links for the PBI
If the PBI build fails for some reason, you may need to modify the module. Use the build log to determine the error and modify the module as needed. If you are unsure how to fix the module, send the build log for the failure as well as the module to the pbi-dev mailing list.
3. Test the PBI: once the PBI build is complete, a pop-up message will indicate that the PBI finished building successfully. You will find the PBI in the output directory that you specified in Figure 10.7c. To continue with our example, the following commands will install the PBI so that it can be tested. Note the error message that occurs since the PBI has not been signed yet.
cd /home/dru/EasyPBI/PBI pbi_add xrdesktop-1.2_2-i386.pbi pbi_add: No digital signature! If you are *SURE* you trust this PBI, re-install with --no-checksig option. pbi_add --no-checksig xrdesktop-1.2_2-i386.pbi Verifying Checksum...OK Extracting to /usr/pbi/xrdesktop-i386 Installed: xrdesktop-1.2.2
rehash /usr/pbi/xrdesktop-i386/bin/xrdesktop
Once installed, specify the full path to the application's binary to make sure that you are testing the PBI's binary. If the application starts and is a GUI, try using all of the menu items to make sure they work as expected. 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 after some Googling, send the error report the pbi-dev mailing list.
Alternately, if everything seems to be working, send the tarball of the PBI to the pbi-dev mailing list. You will find it in the EasyPBI/Modules/ subdirectory. In our example, the name of the tarball is /home/dru/EasyPBI/Modules/xrdesktop.tar.gz.
