Difference between revisions of "EasyPBI2/9.2"

From PC-BSD Wiki
Jump to: navigation, search
 
(62 intermediate revisions by 2 users not shown)
Line 2: Line 2:
  
 
<!--T:1-->
 
<!--T:1-->
{{NavHeader|back=Control Panel|forward=About}}</noinclude>
+
{{UseTOC{{putVers}}|Nav}}</noinclude>
 
+
<!--T:2-->
+
{{note|width=55%|icon64=This page is for EasyPBI version 2.0 and later, which was introduced after PC-BSD® 9.1. [[EasyPBI]] explains the 9.1 version of EasyPBI. Since this version adds many features, users are encouraged to install version 2 as described in the next section.}}
+
  
 
<!--T:3-->
 
<!--T:3-->
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.
+
EasyPBI is a graphical application that makes it easy to build a PBI module from a FreeBSD port. PC‑BSD® 9.2 uses EasyPBI version 2 which can be launched from Control Panel or by typing '''EasyPBI'''.
  
 
<!--T:78-->
 
<!--T:78-->
Line 40: Line 37:
 
* New "About" dialog for quickly viewing information about EasyPBI such as its license information and development history.
 
* New "About" dialog for quickly viewing information about EasyPBI such as its license information and development history.
  
== Getting EasyPBI Version 2 == <!--T:89-->
+
== Quick Start to Creating a PBI Module== <!--T:98-->
 
+
<!--T:90-->
+
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.
+
 
+
<!--T:91-->
+
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'''.
+
 
+
<!--T:92-->
+
If you are running FreeBSD, you can install the sysutils/easypbi/ package or port. To start the application, type '''EasyPBI'''.
+
 
+
<!--T:93-->
+
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.
+
 
+
== Quick Start to Creating a PBI Module==
+
  
 +
<!--T:99-->
 
Before building a PBI, refer to the [http://forums.pcbsd.org/forumdisplay.php?f=61 PBI Requests] forum to determine which PBIs have been requested by users. You should also check that a module does not already exist for the PBI in the [https://github.com/pcbsd/pbi/tree/master/modules PBI Modules repository]. Existing PBI modules are listed alphabetically, according to their category in the ports collection.  
 
Before building a PBI, refer to the [http://forums.pcbsd.org/forumdisplay.php?f=61 PBI Requests] forum to determine which PBIs have been requested by users. You should also check that a module does not already exist for the PBI in the [https://github.com/pcbsd/pbi/tree/master/modules PBI Modules repository]. Existing PBI modules are listed alphabetically, according to their category in the ports collection.  
  
 +
<!--T:100-->
 
When EasyPBI starts up, it automatically checks to see if the FreeBSD ports tree is installed. If it is not, the message shown in Figure 8.1a will appear.
 
When EasyPBI starts up, it automatically checks to see if the FreeBSD ports tree is installed. If it is not, the message shown in Figure 8.1a will appear.
  
Line 66: Line 51:
 
[[File:EasypbiMissingUtils2.png]]
 
[[File:EasypbiMissingUtils2.png]]
  
 +
<!--T:101-->
 
Since the ports tree is needed to create PBIs, click OK to close this message then go to Options → EasyPBI Settings → FreeBSD Ports to access the screen shown in Figure 8.1b.
 
Since the ports tree is needed to create PBIs, click OK to close this message then go to Options → EasyPBI Settings → FreeBSD Ports to access the screen shown in Figure 8.1b.
  
 +
<!--T:102-->
 
'''Figure 8.1b: Updating FreeBSD Ports'''
 
'''Figure 8.1b: Updating FreeBSD Ports'''
  
 +
<!--T:103-->
 
[[File:EasypbiFreebsdports1.png]]
 
[[File:EasypbiFreebsdports1.png]]
  
Click the "Ports Tree" drop-down menu to select to install the ports tree to a specified directory ("Other"), only within the current user's home directory, or in ''/usr/ports'' so that it is available to other users. After making your selection, clock "OK" to install the ports collection.
+
<!--T:104-->
 +
Click the "Ports Tree" drop-down menu to select to install the ports tree to a specified directory ("Other"), only within the current user's home directory, or in ''/usr/ports'' so that it is available to other users. After making your selection, click the "Create Dir" button to be prompted for your password in order to install the ports collection.
  
 +
<!--T:105-->
 
Once the ports tree is installed, you are ready to create a new module. Click the “New” button to access the screen shown in Figure 8.1c.  
 
Once the ports tree is installed, you are ready to create a new module. Click the “New” button to access the screen shown in Figure 8.1c.  
  
 +
<!--T:106-->
 
'''Figure 8.1c: Creating a New Module'''
 
'''Figure 8.1c: Creating a New Module'''
  
 +
<!--T:107-->
 
[[File:Newmodule1.png]]
 
[[File:Newmodule1.png]]
  
 +
<!--T:108-->
 
Use the FreeBSD Port “Select” button to browse to the desired port from the FreeBSD ports tree. 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”.
 
Use the FreeBSD Port “Select” button to browse to the desired port from the FreeBSD ports tree. 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”.
  
 +
<!--T:109-->
 
EasyPBI will automatically supply the port information for the PBI and display the results. In the example shown in Figure 8.1d, the ''net-p2p/linuxdcpp'' port has been selected.  
 
EasyPBI will automatically supply the port information for the PBI and display the results. In the example shown in Figure 8.1d, the ''net-p2p/linuxdcpp'' port has been selected.  
 
   
 
   
 
'''Figure 8.1d: Module Program Information'''
 
'''Figure 8.1d: Module Program Information'''
  
 +
<!--T:110-->
 
[[File:Newmodule2.png]]
 
[[File:Newmodule2.png]]
  
Click the “Save Configuration” button to save the automatically generated PBI module settings. You can then expand the “PBI Builder” tab and click the “Build PBI” button to build the PBI. This screen is shown in Figure 8.1e.
+
<!--T:111-->
 +
You are now ready to build and test the PBI.
  
'''Figure 8.1e: Building the PBI Module'''
+
<!--T:112-->
 +
The next section describes all of the EasyPBI settings should you wish to further customize the module before building it. Otherwise, you can skip ahead to the section on [[EasyPBI2#Build.2C_Test.2C_and_Submit_the_PBI|building and testing the PBI module]].
  
[[File:Newmodule3.png]]
+
== Advanced Configuration == <!--T:113-->
 
+
The next section describes all of the EasyPBI settings should you wish to further customize the module before building it. Otherwise, you can skip to the section on Testing and Submitting the Module.
+
 
+
== Advanced Configuration ==
+
  
 +
<!--T:114-->
 
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.
 
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.
  
Line 103: Line 97:
 
To setup the options for building PBIs, click “Options” → “EasyPBI Settings”. There are three available tabs which are discussed in this section.
 
To setup the options for building PBIs, click “Options” → “EasyPBI Settings”. There are three available tabs which are discussed in this section.
  
==== FreeBSD Ports Tab ====
+
==== FreeBSD Ports Tab ==== <!--T:115-->
  
Figure 8.1f shows the FreeBSD Ports tab on a system that already has FreeBSD ports installed to ''/usr/ports''.
+
<!--T:116-->
 +
Figure 8.1e shows the FreeBSD Ports tab on a system that already has FreeBSD ports installed to ''/usr/ports''.
  
'''Figure 8.1f: FreeBSD Ports Settings'''
+
<!--T:117-->
 +
'''Figure 8.1e: FreeBSD Ports Settings'''
  
 +
<!--T:118-->
 
[[File:Freebsdports.png]]
 
[[File:Freebsdports.png]]
  
 +
<!--T:119-->
 
In this example, the ports tree was last updated on July 2. To update the ports tree, click the "Update" button. To install the ports tree into another directory, click the drop-down "Ports Tree" menu.
 
In this example, the ports tree was last updated on July 2. To update the ports tree, click the "Update" button. To install the ports tree into another directory, click the drop-down "Ports Tree" menu.
  
==== PBI Builds Tab ====
+
==== PBI Builds Tab ==== <!--T:120-->
  
The PBI Builds tab is shown in Figure 8.1g.
+
<!--T:121-->
 +
The PBI Builds tab is shown in Figure 8.1f.
  
'''Figure 8.1g: PBI Build Settings'''
+
<!--T:122-->
 +
'''Figure 8.1f: PBI Build Settings'''
  
 +
<!--T:123-->
 
[[File:Builds.png]]
 
[[File:Builds.png]]
  
 +
<!--T:124-->
 
The options in this screen can be summarized as follows:
 
The options in this screen can be summarized as follows:
  
 +
<!--T:125-->
 
'''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.  
 
'''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.  
  
 +
<!--T:126-->
 
'''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.  
 
'''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.  
  
 +
<!--T:127-->
 
'''Use TMPFS:''' if your build system has more than 2GB of RAM, checking this option can 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 you get “Out of memory” errors when building a large port, you can uncheck this option for that particular build.  
 
'''Use TMPFS:''' if your build system has more than 2GB of RAM, checking this option can 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 you get “Out of memory” errors when building a large port, you can uncheck this option for that particular build.  
  
 +
<!--T:128-->
 
'''Use Package Caching:''' this setting is recommended as it saves all compiled ports as packages in the system cache in order to speed up subsequent builds by using the pre-built packages from the cache whenever possible rather than re-compiling every port dependency. Two additional options for dealing with the cache are available. The first option is to clear all packages from the cache and start fresh. The second option is to add a problematic package to the “Ignore” list. This will remove the specified package from the cache before starting each build, ensuring that it will always compile that port for each build that requires it.
 
'''Use Package Caching:''' this setting is recommended as it saves all compiled ports as packages in the system cache in order to speed up subsequent builds by using the pre-built packages from the cache whenever possible rather than re-compiling every port dependency. Two additional options for dealing with the cache are available. The first option is to clear all packages from the cache and start fresh. The second option is to add a problematic package to the “Ignore” list. This will remove the specified package from the cache before starting each build, ensuring that it will always compile that port for each build that requires it.
  
==== Local Paths Tab ====
+
==== Local Paths Tab ==== <!--T:129-->
  
The Local Paths tab is shown in Figure 8.1h.
+
<!--T:130-->
 +
The Local Paths tab is shown in Figure 8.1g.
  
'''Figure 8.1h: Local Paths Settings'''
+
<!--T:131-->
 +
'''Figure 8.1g: Local Paths Settings'''
  
 +
<!--T:132-->
 
[[File:Paths.png]]
 
[[File:Paths.png]]
  
 +
<!--T:133-->
 
The options in this screen allow you to configure the following paths:
 
The options in this screen allow you to configure the following paths:
  
 +
<!--T:134-->
 
'''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.
 
'''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.
  
 +
<!--T:135-->
 
'''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.
 
'''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.
  
Line 148: Line 160:
 
The module editor pane for EasyPBI2 supports complete control over all the options available when creating PBI modules. Most of these options are not necessary for the majority of PBI modules, but they are available for applications that need some extra tweaking to work properly.
 
The module editor pane for EasyPBI2 supports complete control over all the options available when creating PBI modules. Most of these options are not necessary for the majority of PBI modules, but they are available for applications that need some extra tweaking to work properly.
  
 +
<!--T:136-->
 
EasyPBI provides suggestions and default settings whenever there is a green arrow next to an option within the module editor. Click the arrow to view the suggestions, then click a suggestion to instruct EasyPBI to add it to the proper option within the module.  
 
EasyPBI provides suggestions and default settings whenever there is a green arrow next to an option within the module editor. Click the arrow to view the suggestions, then click a suggestion to instruct EasyPBI to add it to the proper option within the module.  
  
 +
<!--T:137-->
 
This section describes the five tabs that are available within the module editor pane.
 
This section describes the five tabs that are available within the module editor pane.
  
 
==== PBI Configuration ==== <!--T:25-->
 
==== PBI Configuration ==== <!--T:25-->
Figure 8.1i shows the PBI Configuration tab of the module editor pane. This tab is used to set the required information about the program being packaged as a PBI.  
+
Figure 8.1h shows the PBI Configuration tab of the module editor pane. This tab is used to set the required information about the program being packaged as a PBI.  
  
 
<!--T:26-->
 
<!--T:26-->
'''Figure 8.1i: PBI Configuration'''
+
'''Figure 8.1h: PBI Configuration'''
  
 
<!--T:27-->
 
<!--T:27-->
 
[[File:Newmodule2.png]]
 
[[File:Newmodule2.png]]
  
As seen in the [[EasyPBI2#Quick_Start_to_Creating_a_PBI_Module|Quick Start]], EasyPBI automatically fill in the port information when you browse to a FreeBSD port to convert into a PBI. Under "Program Information" the port's name, website, author (FreeBSD maintainer), and default icon are filled in for you. You should review these fields for accuracy:
+
<!--T:138-->
 +
As seen in the {{local|link=EasyPBI2|anchor=Quick_Start_to_Creating_a_PBI_Module|Quick Start}}, EasyPBI automatically fill in the port information when you browse to a FreeBSD port to convert into a PBI. Under "Program Information" the port's name, website, author (FreeBSD maintainer), and default icon are filled in for you. You should review these fields for accuracy:
  
 +
<!--T:139-->
 
* if necessary, correct the capitalization in "Name".
 
* if necessary, correct the capitalization in "Name".
  
 +
<!--T:140-->
 
* if the application's author is not listed in the port information, it will instead list the email address of the FreeBSD port maintainer. If the application has a specific author, this should be corrected.
 
* if the application's author is not listed in the port information, it will instead list the email address of the FreeBSD port maintainer. If the application has a specific author, this should be corrected.
  
 +
<!--T:141-->
 
* 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 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.
  
 +
<!--T:142-->
 
The "Build Information" box provides all of the options available for building the PBI. If you selected to build a PBI from local sources in Figure 8.1c, this section will only contain the local directory to be packaged as a PBI. If you are building a PBI from a FreeBSD port, there are a number of other options as seen in Figure 8.1i.  
 
The "Build Information" box provides all of the options available for building the PBI. If you selected to build a PBI from local sources in Figure 8.1c, this section will only contain the local directory to be packaged as a PBI. If you are building a PBI from a FreeBSD port, there are a number of other options as seen in Figure 8.1i.  
  
 +
<!--T:143-->
 
When converting a FreeBSD port to a PBI, the only required option is the “Main FreeBSD Port”. This is set automatically based upon the port that you selected in Figure 8.3c, but you can change your initial port selection by clicking the “Change Port” button.
 
When converting a FreeBSD port to a PBI, the only required option is the “Main FreeBSD Port”. This is set automatically based upon the port that you selected in Figure 8.3c, but you can change your initial port selection by clicking the “Change Port” button.
  
Some FreeBSD port provide build options. If you click “Information” → “FreeBSD Ports”, the [http://freshports.org FreshPorts] entry for that port will open up in a web browser. Look for the "Configuration Options" for that entry. If there are any options, you can enable them in the “Port Build Options” box. EasyPBI will autodetect the available options and provide them as suggestions. Clicking the button with the green arrow to see the options and to select the build options to use. The selected options will be added to the "Port Build Options" box. If the port does not have any options, no suggestions will appear when you click the green arrow.
+
<!--T:144-->
 +
Some FreeBSD ports provide build options. If you click “Information” → “FreeBSD Ports”, the [http://freshports.org FreshPorts] entry for that port will open up in a web browser. Look for the "Configuration Options" for that entry. If there are any options, you can enable them in the “Port Build Options” box. EasyPBI will autodetect the available options and provide them as suggestions. Clicking the button with the green arrow to see the options and to select the build options to use. The selected options will be added to the "Port Build Options" box. If the port does not have any options, no suggestions will appear when you click the green arrow.
  
 +
<!--T:145-->
 
If you discover that the port appears to be missing a dependancy for the application 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 port to not build properly, add it to the “Make Port Before” option. If it is a missing runtime dependency, add it to the “Make Port After” option.
 
If you discover that the port appears to be missing a dependancy for the application 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 port to not build properly, add it to the “Make Port Before” option. If it is a missing runtime dependency, add it to the “Make Port After” option.
  
 +
<!--T:146-->
 
The last option is for both local and port PBI modules. The “Requires Root Permissions” checkbox lets you set whether the PBI can only be installed and uninstalled using root privileges. 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.
 
The last option is for both local and port PBI modules. The “Requires Root Permissions” checkbox lets you set whether the PBI can only be installed and uninstalled using root privileges. 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.
  
Line 183: Line 206:
  
 
==== Resources ==== <!--T:30-->
 
==== Resources ==== <!--T:30-->
The resources tab, shown in Figure 8.1j, 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.  
+
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.  
  
'''Figure 8.1j: Resource Options'''
+
<!--T:147-->
 +
'''Figure 8.1i: Resource Options'''
  
 +
<!--T:148-->
 
[[File:Easypbiresources1.png]]  
 
[[File:Easypbiresources1.png]]  
  
This tab is mainly used to add PNG images to be used as PBI icons. One additional 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''.
+
<!--T:149-->
 +
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.
  
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.1k, 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 the [http://forums.pcbsd.org/forumdisplay.php?f=12 PBI Discussion forum] or on the [http://lists.pcbsd.org/mailman/listinfo/pbi-dev PBI developers mailing list].
+
<!--T:150-->
 +
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.
  
'''Figure 8.1k: Edit the Automatically Generated Script'''
+
<!--T:151-->
 +
If the application uses custom installer graphics, add them using this screen.
  
 +
<!--T:152-->
 +
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.
 +
 +
<!--T:153-->
 +
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 the [http://forums.pcbsd.org/forumdisplay.php?f=12 PBI Discussion forum] or on the [http://lists.pcbsd.org/mailman/listinfo/pbi-dev PBI developers mailing list].
 +
 +
<!--T:154-->
 +
'''Figure 8.1j: Edit the Automatically Generated Script'''
 +
 +
<!--T:155-->
 
[[File:Script.png]]
 
[[File:Script.png]]
  
 
==== XDG Entries ==== <!--T:33-->
 
==== XDG Entries ==== <!--T:33-->
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.
+
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.
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.
+
  
<!--T:34-->
+
<!--T:156-->
'''Figure 8.1h: Desktop Entries'''
+
'''Figure 8.1k: Desktop Entries'''
  
<!--T:35-->
+
<!--T:157-->
 
[[File:Easypbixdgdesktop.png]]
 
[[File:Easypbixdgdesktop.png]]
  
<!--T:36-->
+
<!--T:158-->
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.
+
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 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.
+
  
<!--T:37-->
+
<!--T:159-->
'''Figure 8.1i: Menu Entries'''
+
The "Entry Details" section of this tab are as follows when the "Desktop" button is selected:
  
<!--T:38-->
+
<!--T:160-->
[[File:Easypbixdgmenu.png]]
+
* '''Name:''' this is the text that will appear for the desktop menu entry, and is usually the full name of the application.
 +
 
 +
<!--T:161-->
 +
* '''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.
 +
 
 +
<!--T:162-->
 +
* '''Icon:''' the available icons will include the default icon and any that you added in the Resources tab.
 +
 
 +
<!--T:163-->
 +
* '''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.
 +
 
 +
<!--T:164-->
 +
* '''Make Invisible:''' if checked, the entry will be hidden. This is not as useful for desktop entries but can be handy with menu entries.
 +
 
 +
<!--T:165-->
 +
* '''Requires Root:''' if checked, the user will be prompted for their password when the application starts.
  
 
<!--T:39-->
 
<!--T:39-->
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.
+
Figure 8.1l shows the "Entry Details" that are available when "Menu" is selected.  
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.
+
  
==== Scripts ==== <!--T:40-->
+
<!--T:166-->
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.
+
'''Figure 8.1l: Menu Entry Details'''
  
<!--T:41-->
+
<!--T:167-->
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!
+
[[File:Easypbixdgmenu.png]]
  
<!--T:42-->
+
<!--T:168-->
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.
+
This screen adds two fields:
+
'''Figure 8.1j: Installation Scripts'''
+
  
<!--T:43-->
+
<!--T:169-->
[[File:Easypbiscripts.png]]
+
* '''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.  
  
==== External Links ==== <!--T:44-->
+
<!--T:170-->
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.
+
* '''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.
  
<!--T:45-->
+
==== Scripts ==== <!--T:40-->
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).
+
This tab, shown in figure 8.1m, is used to view and edit installation scripts used by the PBI.  
  
<!--T:46-->
+
<!--T:171-->
File Types:
+
'''Figure 8.1m: Installation Scripts'''
* '''binary:''' indicates that this is an executable. The PBI will automatically create the necessary wrapper and PATH links for you.
+
  
<!--T:47-->
+
<!--T:172-->
* '''linux:''' indicates that this is a Linux executable. EasyPBI will automatically create the necessary Linux wrapper and PATH links for you.
+
[[File:Easypbiscripts.png]]
  
<!--T:48-->
+
<!--T:173-->
* '''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''.
+
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.
  
<!--T:49-->
+
<!--T:174-->
* '''replace:''' instructs the PBI to overwrite an existing file when linking a file into the LOCALBASE.
+
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.
  
<!--T:50-->
+
<!--T:41-->
* '''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.
+
'''NOTE:''' changes to the scripts in this screen will not be saved until you click the “Save ” button. Be sure to save your work before leaving this tab.
  
<!--T:51-->
+
==== External Links ==== <!--T:44-->
'''Figure 8.1k: External Links'''
+
This tab, shown in Figure 8.1n, is used to setup links for additional binaries within the PBI.
  
<!--T:52-->
+
<!--T:175-->
 +
'''Figure 8.1n: External Links'''
 +
 
 +
<!--T:176-->
 
[[File:Easypbiexternallinks.png]]
 
[[File:Easypbiexternallinks.png]]
  
=== PBI Builder === <!--T:53-->
+
<!--T:177-->
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.
+
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.  
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.  
+
  
<!--T:54-->
+
<!--T:178-->
'''Figure 8.1l: PBI Builder'''
+
When adding an entry, configure the following fields:
  
<!--T:55-->
+
<!--T:179-->
[[File:Easypbibuildsettings.png]]
+
* '''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".
  
== Example: Converting a FreeBSD port to a PBI == <!--T:56-->
+
<!--T:180-->
 +
*  '''Link To:''' input the path to link the binary to on the base system, relative to ''/usr/local/''.
  
<!--T:57-->
+
<!--T:181-->
'''Step 1''': Create a PBI module
+
* '''File Type:''' click the green arrow to set the type of link.
  
<!--T:58-->
+
<!--T:182-->
Click on the "New" button at the top of the window to open up the small dialog shown in figure 8.1m.
+
The following "File Type"s are supported:
  
<!--T:59-->
+
<!--T:183-->
'''Figure 8.1m: New Module Dialog'''
+
* '''binary:''' indicates that this is an executable. The PBI will automatically create the necessary wrapper and PATH links.
  
<!--T:60-->
+
<!--T:47-->
[[File:Easypbinewmoduleport.png]]
+
* '''linux:''' indicates that this is a Linux executable. EasyPBI will automatically create the necessary Linux wrapper and PATH links.
  
<!--T:61-->
+
<!--T:48-->
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.
+
* '''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''.
  
 +
<!--T:49-->
 +
* '''replace:''' instructs the PBI to overwrite an existing file when linking a file into the LOCALBASE.
  
<!--T:62-->
+
<!--T:50-->
'''Step 2''': (OPTIONAL) Checking the new module
+
* '''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.
  
<!--T:63-->
+
== Build, Test, and Submit the PBI == <!--T:53-->
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).
+
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.  
  
<!--T:64-->
+
<!--T:184-->
'''Figure 8.1n: Example Module Configuration'''
+
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.
  
<!--T:65-->
+
<!--T:185-->
[[File:Easypbiportexampleconfig.png]]
+
'''Figure 8.1o: PBI Builder'''
  
<!--T:66-->
+
<!--T:186-->
'''Figure 8.1o: Example Menu Entry'''
+
[[File:Easypbibuildsettings.png]]
  
<!--T:67-->
+
<!--T:187-->
[[File:Easypbiportexamplemenu.png]]
+
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.
  
 +
<!--T:188-->
 +
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.
  
<!--T:68-->
+
<!--T:189-->
'''Step 3''': Build the PBI
+
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.
  
<!--T:69-->
+
<!--T:190-->
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.  
+
If you wish to build a 32-bit version of the PBI on a 64-bit system, check the box "Build 32-bit".
  
<!--T:70-->
+
<!--T:191-->
NOTE: While a PBI build is running, you may go ahead and create/edit other PBI modules without interfering with the build process.
+
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.
  
<!--T:71-->
+
<!--T:192-->
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.
+
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 [http://lists.pcbsd.org/mailman/listinfo/pbi-dev pbi-dev mailing list].
  
<!--T:72-->
+
===Test the PBI=== <!--T:193-->
'''Figure 8.1p: Example PBI Build'''
+
  
<!--T:73-->
+
<!--T:194-->
[[File:Easypbiportexamplebuild.png]]
+
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.  
  
== Example: Creating a PBI from a local directory == <!--T:74-->
+
<!--T:195-->
 +
{{txtbox|box='''su'''
 +
Password:
 +
'''cd ~dru/EasyPBI/PBI'''
 +
'''ls'''
 +
p7zip-9.20.1-amd64.pbi    p7zip-9.20.1-amd64.pbi.sha256{{nbsp|25}}
 +
'''pbi_add --no-checksig p7zip-9.20.1-amd64.pbi'''
 +
Verifying Checksum...OK
 +
Extracting to: /usr/pbi/p7zip-amd64
 +
Installed: p7zip-9.20.1}}
  
 +
<!--T:196-->
 +
If the module installs successfully, perform the following tests:
  
 +
<!--T:197-->
 +
* 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.
  
 +
<!--T:198-->
 +
* 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.
  
== Submit the Module == <!--T:75-->
+
<!--T:199-->
 +
* 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 [http://lists.pcbsd.org/mailman/listinfo/pbi-dev pbi-dev mailing list].
  
<!--T:76-->
+
<!--T:200-->
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 modify any settings in the PBI's module, rebuild the PBI then test again to see if the changes fixed the PBI.
  
<!--T:77-->
+
===Submit the PBI Module=== <!--T:201-->
If you send that file to the {{citelink|url=http://lists.pcbsd.org/mailman/listinfo/pbi-dev|txt=pbi-dev mailing list}}, 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.
+
 
 +
<!--T:202-->
 +
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 [http://lists.pcbsd.org/mailman/listinfo/pbi-dev pbi-dev mailing list], 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.
  
<!--T:97-->
+
<!--T:203-->
 
<noinclude>
 
<noinclude>
 
{{refheading}}
 
{{refheading}}

Latest revision as of 00:39, 16 December 2013


Contents


EasyPBI is a graphical application that makes it easy to build a PBI module from a FreeBSD port. PC‑BSD® 9.2 uses EasyPBI version 2 which can be launched from Control Panel or by typing EasyPBI.

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.
  • An additional option for building 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 the creation and editing of XDG desktop and menu entries with easy MIME type integration.
  • The OptionsNG format for setting port build options is enabled by default.
  • Support for multiple lines when specifying build options.
  • New "Settings" dialog for setting and changing default directory paths, PBI build settings, and 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.

[edit] Quick Start to Creating a PBI Module

Before building a PBI, refer to the PBI Requests forum to determine which PBIs have been requested by users. You should also check that a module does not already exist for the PBI in the PBI Modules repository. Existing PBI modules are listed alphabetically, according to their category in the ports collection.

When EasyPBI starts up, it automatically checks to see if the FreeBSD ports tree is installed. If it is not, the message shown in Figure 8.1a will appear.

Figure 8.1a: Ports Tree not Installed

EasypbiMissingUtils2.png

Since the ports tree is needed to create PBIs, click OK to close this message then go to Options → EasyPBI Settings → FreeBSD Ports to access the screen shown in Figure 8.1b.

Figure 8.1b: Updating FreeBSD Ports

EasypbiFreebsdports1.png

Click the "Ports Tree" drop-down menu to select to install the ports tree to a specified directory ("Other"), only within the current user's home directory, or in /usr/ports so that it is available to other users. After making your selection, click the "Create Dir" button to be prompted for your password in order to install the ports collection.

Once the ports tree is installed, you are ready to create a new module. Click the “New” button to access the screen shown in Figure 8.1c.

Figure 8.1c: Creating a New Module

Newmodule1.png

Use the FreeBSD Port “Select” button to browse to the desired port from the FreeBSD ports tree. 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 automatically supply the port information for the PBI and display the results. In the example shown in Figure 8.1d, the net-p2p/linuxdcpp port has been selected.

Figure 8.1d: Module Program Information

Newmodule2.png

You are now ready to build and test the PBI.

The next section describes all of the EasyPBI settings should you wish to further customize the module before building it. Otherwise, you can skip ahead to the section on building and testing the PBI module.

[edit] Advanced Configuration

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.

[edit] EasyPBI Settings

To setup the options for building PBIs, click “Options” → “EasyPBI Settings”. There are three available tabs which are discussed in this section.

[edit] FreeBSD Ports Tab

Figure 8.1e shows the FreeBSD Ports tab on a system that already has FreeBSD ports installed to /usr/ports.

Figure 8.1e: FreeBSD Ports Settings

Freebsdports.png

In this example, the ports tree was last updated on July 2. To update the ports tree, click the "Update" button. To install the ports tree into another directory, click the drop-down "Ports Tree" menu.

[edit] PBI Builds Tab

The PBI Builds tab is shown in Figure 8.1f.

Figure 8.1f: PBI Build Settings

Builds.png

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.

Use TMPFS: if your build system has more than 2GB of RAM, checking this option can 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 you get “Out of memory” errors when building a large port, you can uncheck this option for that particular build.

Use Package Caching: this setting is recommended as it saves all compiled ports as packages in the system cache in order to speed up subsequent builds by using the pre-built packages from the cache whenever possible rather than re-compiling every port dependency. Two additional options for dealing with the cache are available. The first option is to clear all packages from the cache and start fresh. The second option is to add a problematic package to the “Ignore” list. This will remove the specified package from the cache before starting each build, ensuring that it will always compile that port for each build that requires it.

[edit] Local Paths Tab

The Local Paths tab is shown in Figure 8.1g.

Figure 8.1g: Local Paths Settings

Paths.png

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.

[edit] Module Editor

The module editor pane for EasyPBI2 supports complete control over all the options available when creating PBI modules. Most of these options are not necessary for the majority of PBI modules, but they are available for applications that need some extra tweaking to work properly.

EasyPBI provides suggestions and default settings whenever there is a green arrow next to an option within the module editor. Click the arrow to view the suggestions, then click a suggestion to instruct EasyPBI to add it to the proper option within the module.

This section describes the five tabs that are available within the module editor pane.

[edit] PBI Configuration

Figure 8.1h shows the PBI Configuration tab of the module editor pane. This tab is used to set the required information about the program being packaged as a PBI.

Figure 8.1h: PBI Configuration

Newmodule2.png

As seen in the Quick Start, EasyPBI automatically fill in the port information when you browse to a FreeBSD port to convert into a PBI. Under "Program Information" the port's name, website, author (FreeBSD maintainer), and default icon are 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, it will instead list the email address of the FreeBSD port maintainer. If 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.

The "Build Information" box provides all of the options available for building the PBI. If you selected to build a PBI from local sources in Figure 8.1c, this section will only contain the local directory to be packaged as a PBI. If you are building a PBI from a FreeBSD port, there are a number of other options as seen in Figure 8.1i.

When converting a FreeBSD port to a PBI, the only required option is the “Main FreeBSD Port”. This is set automatically based upon the port that you selected in Figure 8.3c, but you can change your initial port selection by clicking the “Change Port” button.

Some FreeBSD ports provide build options. If you click “Information” → “FreeBSD Ports”, the FreshPorts entry for that port will open up in a web browser. Look for the "Configuration Options" for that entry. If there are any options, you can enable them in the “Port Build Options” box. EasyPBI will autodetect the available options and provide them as suggestions. Clicking the button with the green arrow to see the options and to select the build options to use. The selected options will be added to the "Port Build Options" box. If the port does not have any options, no suggestions will appear when you click the green arrow.

If you discover that the port appears to be missing a dependancy for the application 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 port to not build properly, add it to the “Make Port Before” option. If it is a missing runtime dependency, add it to the “Make Port After” option.

The last option is for both local and port PBI modules. The “Requires Root Permissions” checkbox lets you set whether the PBI can only be installed and uninstalled using root privileges. 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.

NOTE: changes within this screen will not be saved until you click the “Save Configuration” button. Be sure to save any changes before leaving this tab.

[edit] Resources

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.

Figure 8.1i: Resource Options

Easypbiresources1.png

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 the PBI Discussion forum or on the PBI developers mailing list.

Figure 8.1j: Edit the Automatically Generated Script

Script.png

[edit] XDG Entries

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.

Figure 8.1k: Desktop Entries

Easypbixdgdesktop.png

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.

Figure 8.1l: Menu Entry Details

Easypbixdgmenu.png

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.

[edit] Scripts

This tab, shown in figure 8.1m, is used to view and edit installation scripts used by the PBI.

Figure 8.1m: Installation Scripts

Easypbiscripts.png

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.

NOTE: changes to the scripts in this screen will not be saved until you click the “Save ” button. Be sure to save your work before leaving this tab.

[edit] External Links

This tab, shown in Figure 8.1n, is used to setup links for additional binaries within the PBI.

Figure 8.1n: External Links

Easypbiexternallinks.png

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.

[edit] 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.

Figure 8.1o: PBI Builder

Easypbibuildsettings.png

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 pbi-dev mailing list.

[edit] 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.

su

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-amd64

Installed: 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 pbi-dev mailing list.

If you modify any settings in the PBI's module, rebuild the PBI then test again to see if the changes fixed the PBI.

[edit] 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 pbi-dev mailing list, 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.


References


Other languages:German 5% • ‎English 100% • ‎French 28%