Difference between revisions of "EasyPBI"

From PC-BSD Wiki
Jump to: navigation, search
(Generate the Repository's Meta-Data)
m (Test and Fine-Tune the Module)
(19 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
<noinclude>{{NavHeader|back=Control Panel|forward=About}}</noinclude>
 
<noinclude>{{NavHeader|back=Control Panel|forward=About}}</noinclude>
  
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.
+
EasyPBI is a graphical application that makes it easy to build a PBI module from a FreeBSD port. Beginning with PC-BSD®&nbsp;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 section on how to [[Create PBIs]] first, as well as refer to that Guide should you have trouble creating a PBI or wish to create a more complex PBI.
+
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 section on how to [[PBI Module Builder Guide | Create PBIs]] first, as well as refer to that Guide should you have trouble creating a PBI or wish to create a more complex PBI.
  
 
To start EasyPBI, double-click its icon in Control Panel or type '''EasyPBI''' from within an X terminal as your regular user account.
 
To start EasyPBI, double-click its icon in Control Panel or type '''EasyPBI''' from within an X terminal as your regular user account.
Line 13: Line 13:
 
[[File:Easypbi1d.png]]
 
[[File:Easypbi1d.png]]
  
If multiple users will be using the EasyPBI utility, go to Control Panel -> System Manager -> [[System Manager#Install FreeBSD Source and Ports|Tasks]] and click the "Fetch Ports Tree" button. Alternately, use the following command as the superuser: '''portsnap fetch extract.''' Either of these methods will install the ports collection into ''/usr/ports.''
+
If multiple users will be using the EasyPBI utility, go to ''[[Control Panel]]'' ➜ [[System Manager#Install FreeBSD Source and Ports| ''System Manager'' ➜ ''Tasks'']] and click the ''Fetch Ports Tree'' button. Alternately, use the following command as the superuser '''portsnap fetch extract'''. Either of these methods will install the ports collection into ''/usr/ports''.
  
If you are the only user who will be using the EasyPBI utility, click OK to launch the main EasyPBI screen, shown in Figure 8.1b. Click File ➜ Get Ports which will download the ports collection to the ''EasyPBI'' subdirectory located in your home directory.  
+
If you are the only user who will be using the EasyPBI utility, click ''OK'' to launch the main EasyPBI screen, shown in Figure 8.1b. Click ''File'' ''Get Ports'' which will download the ports collection to the ''[[EasyPBI]]'' subdirectory located in your home directory.  
  
 
'''Figure 8.1b: EasyPBI Graphical Interface'''
 
'''Figure 8.1b: EasyPBI Graphical Interface'''
Line 21: Line 21:
 
[[File:Easypbi1b.png]]
 
[[File:Easypbi1b.png]]
  
If the ports collection was already installed or was installed using System Manager or '''portsnap''', the message in the bottom area of the screen will instead indicate "To get started, please push the "New Module" button.
+
If the ports collection was already installed or was installed using System Manager or '''portsnap''', the message in the bottom area of the screen will instead indicate To get started, please push the ''New Module'' button.
  
 
== Creating a PBI Module ==
 
== Creating a PBI Module ==
  
Before building a PBI, refer to the {{citelink|url=http://forums.pcbsd.org/forumdisplay.php?f=61|PBI Requests forum}} to determine which PBI's have been requested by users. You should also check that a module does not already exist for the PBI in the {{citelink|url=http://trac.pcbsd.org/browser#pbi/modules|PBI Modules}} section of trac. Existing modules are listed alphabetically, according to their category in the ports collection.
+
Before building a PBI, refer to the {{citelink|url=http://forums.pcbsd.org/forumdisplay.php?f=61|txt=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 {{citelink|url=http://trac.pcbsd.org/browser#pbi/modules|txt=PBI Modules}} section of trac. Existing modules are listed alphabetically, according to their category in the ports collection.
  
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 in the GUI. In the example shown in Figure 8.1c, the ''net/trickle'' port has been selected and the fields have been auto-filled in.  
+
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 in the GUI. In the example shown in Figure 8.1c, the ''net/trickle'' port has been selected and the fields have been auto-filled in.  
  
 
'''Figure 8.1c: Review the New Module'''
 
'''Figure 8.1c: Review the New Module'''
Line 33: Line 33:
 
[[File:Easypbi1c.png]]
 
[[File:Easypbi1c.png]]
  
You should review these fields for accuracy. If you click "Get Port Info" {{citelink|url=http://freshports.org|FreshPorts.org}} will open in the default web browser so that you can view additional information about the port.  
+
You should review these fields for accuracy. If you click "Get Port Info" {{citelink|url=http://freshports.org|txt=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 a 64x64 ''.png'' file with a transparent background.  
+
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 a 64x64 ''.png'' file with a transparent background.  
  
Check the "Create Desktop/Menu Entries" if you wish the program's icon to be available on the desktop and in the desktop's application menu.
+
Check the ''Create Desktop/Menu Entries' if you wish the program's icon to be available on the desktop and in the desktop's application menu.
  
Once the port information is complete, click the "Create Module" button and EasyPBI will produce the PBI module. The module will be named after the port and will be stored in a subdirectory of the ''EasyPBI/Modules'' directory in your home directory. In this example, the module is located in ''EasyPBI/Modules/trickle.''
+
Once the port information is complete, click the ''Create Module'' button and EasyPBI will produce the PBI module. The module will be named after the port and will be stored in a subdirectory of the ''EasyPBI/Modules'' directory in your home directory. In this example, the module is located in ''EasyPBI/Modules/trickle''.
  
 
=== Build the Module ===
 
=== Build the Module ===
Line 45: Line 45:
 
Creating the module itself is very quick and takes less than a minute. However, you still need to build and test the module to make sure that the application works as expected. Depending upon the complexity of the application, you may have to edit the initial module then rebuild and retest it until you are satisfied with the PBI for the application.
 
Creating the module itself is very quick and takes less than a minute. However, you still need to build and test the module to make sure that the application works as expected. Depending upon the complexity of the application, you may have to edit the initial module then rebuild and retest it until you are satisfied with the PBI for the application.
  
Once the module is created, you are ready to build a PBI from the module. Click on the "Build PBI" tab and click the "Select Module" button to browse to the module you created. Figure 8.1d shows this tab with our example PBI selected.
+
Once the module is created, you are ready to build a PBI from the module. Click on the ''Build PBI'' tab and click the ''Select Module'' button to browse to the module you created. Figure 8.1d shows this tab with our example PBI selected.
  
 
'''Figure 8.1d: The Build PBI Tab'''
 
'''Figure 8.1d: The Build PBI Tab'''
Line 51: Line 51:
 
[[File:Easypbi3b.png]]
 
[[File:Easypbi3b.png]]
  
The top half of this screen contains editable settings which are used when building PBIs:
+
The top half of this screen contains modifiable settings which are used when building PBIs:
  
 
'''Save Settings as Defaults:''' the settings in this section revert back to the default settings when you exit EasyPBI. This allows you to override the default settings for a particular build. If you wish your changes to be permanent, click this button.
 
'''Save Settings as Defaults:''' the settings in this section revert back to the default settings when you exit EasyPBI. This allows you to override the default settings for a particular build. If you wish your changes to be permanent, click this button.
  
'''Output Directory:''' specifies the directory to store the built module. By default, it is the ''EasyPBI/PBI'' subdirectory of the user's home directory. Click the "Change Directory" button to select another location.
+
'''Output Directory:''' specifies the directory to store the built module. By default, it is the ''EasyPBI/PBI'' subdirectory of the user's home directory. Click the ''Change Directory'' button to select another location.
  
'''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, click the "Change File" button to select your own digital signature file. [[#Create Your Own PBI Repository|Create Your Own PBI Repository]] provides instructions for creating a signature file.
+
'''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, click the ''Change File'' button to select your own digital signature file. [[Create Your Own PBI Repository]] provides instructions for creating a signature file.
  
 
'''Use TMPFS:''' if your build system has a lot of RAM, selecting this option can speed up the build.
 
'''Use TMPFS:''' if your build system has a lot of RAM, selecting this option can speed up the build.
Line 69: Line 69:
 
'''Build PBI:''' starts the build of the PBI module. It will prompt you for the superuser password and requires a working Internet connection in order 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.
 
'''Build PBI:''' starts the build of the PBI module. It will prompt you for the superuser password and requires a working Internet connection in order 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.
+
'''Stop Build:''' stops the build process. Click the ''Build PBI'' button to resume the build.
  
 
'''Save Build Log:''' useful if the build fails. Will prompt you to select the location to store ''build.log'' which can be read with any ASCII text editor.
 
'''Save Build Log:''' useful if the build fails. Will prompt you to select the location to store ''build.log'' which can be read with any ASCII text editor.
  
You can produce additional modules from the "Create Module" tab while a PBI build is running.
+
You can produce additional modules from the ''Create Module'' tab while a PBI build is running.
  
If the PBI build fails for some reason, you may need to modify the module as described in the next section. 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 to the {{citelink|url=http://lists.pcbsd.org/mailman/listinfo/pbi-dev|pbi-dev mailing list}}.
+
If the PBI build fails for some reason, you may need to modify the module as described in the next section. 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 to the {{citelink|url=http://lists.pcbsd.org/mailman/listinfo/pbi-dev|txt=pbi-dev mailing list}}.
  
 
=== Test and Fine-Tune the Module ===
 
=== Test and Fine-Tune the Module ===
Line 95: Line 95:
 
If the module installs successfully, perform the following tests:
 
If the module installs successfully, perform the following tests:
  
* if you checked the box "Create Desktop/Menu Entries", 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.
+
* if you checked the box ''Create Desktop/Menu Entries'', 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.
 
* 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.
Line 101: Line 101:
 
* for GUI applications, go through the various menus to see if they produce any errors.
 
* for GUI applications, 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 {{citelink|url=http://lists.pcbsd.org/mailman/listinfo/pbi-dev|pbi-dev mailing list}}.
+
* 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 {{citelink|url=http://lists.pcbsd.org/mailman/listinfo/pbi-dev|txt=pbi-dev mailing list}}.
  
The "Module Editor" tab, seen in Figure 8.1e, can be used to modify the module's settings. Use the "Select Module" button to browse to the location of the module and to ungrey out the settings in this screen.
+
The ''Module Editor'' tab, seen in Figure 8.1e, can be used to modify the module's settings. Use the ''Select Module'' button to browse to the location of the module and to un-grey-out the settings in this screen.
  
 
'''Figure 8.1e: EasyPBI Module Editor'''
 
'''Figure 8.1e: EasyPBI Module Editor'''
Line 109: Line 109:
 
[[File:easypbi4a.png]]
 
[[File:easypbi4a.png]]
  
Several tabs are provided, allowing you to customize the PBI module. It should be noted 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 require additional FreeBSD ports or scripts which are not provided by the default FreeBSD port.
+
Several tabs are provided, allowing you to customize the PBI module. It should be noted 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 require additional FreeBSD ports or scripts which are not provided by the default FreeBSD port.
  
 
The rest of this section describes the actions available within each tab. If you modify any settings in the PBI module, rebuild it then test again to see if the changes fixed the PBI.
 
The rest of this section describes the actions available within each tab. If you modify any settings in the PBI module, rebuild it then test again to see if the changes fixed the PBI.
  
==== pbi.conf ====
+
==== pbi.conf ====
  
Typically the "Program Name", "Program Website", and "Program Author" are left at their default values. If this information is incorrect, you should email the FreeBSD port maintainer shown in the Program Author field so that the information can be corrected in the FreeBSD port.  
+
Typically the ''Program Name'', ''Program Website'', and ''Program Author'' are left at their default values. If this information is incorrect, you should email the FreeBSD port maintainer shown in the ''Program Author'' field so that the information can be corrected in the FreeBSD port.  
  
If you choose to replace the "Program Icon", use a 64x64 ''.png'' file with a transparent background.  
+
If you choose to replace the ''Program 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 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.
+
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''.
+
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.
+
If the resulting PBI needs to be run as the root user, check the ''Require Root Permissions'' box.
  
 
==== Resources ====  
 
==== Resources ====  
Line 135: Line 135:
 
[[Image:Easypbi5a.png]]
 
[[Image:Easypbi5a.png]]
  
An example of an additional file would be an application that requires the user to accept a License. Use the "+Add Resource" button to browse to the location of the ''LICENSE'' file.  
+
An example of an additional file would be an application that requires the user to accept a License. Use the ''+&nbsp;Add Resource'' button to browse to the location of the ''LICENSE'' file.  
  
 
Another example would be when you wish to use a custom script to start the application rather than starting the application binary directly. A custom script could also be used to verify that the service is enabled or to generate a custom configuration file.
 
Another example would be when you wish to use a custom script to start the application rather than starting the application binary directly. A custom script could also be used to verify that the service is enabled or to generate a custom configuration file.
Line 149: Line 149:
 
[[Image:Easypbi6a.png]]
 
[[Image:Easypbi6a.png]]
  
If the "Create Desktop/Menu Entries" box was checked when creating the module and EasyPBI detects that the application is graphical, the default entries for the application will be listed. In our PBI example, '''trickle''' is a command line application so no entries were created by default. If your application is graphical but EasyPBI did not detect it, you can manually add the desired entries using the "Remove Desktop Entry" and "Remove Menu Entry" buttons.
+
If the ''Create Desktop/Menu Entries'' box was checked when creating the module and EasyPBI detects that the application is graphical, the default entries for the application will be listed. In our PBI example, '''trickle''' is a command line application so no entries were created by default. If your application is graphical but EasyPBI did not detect it, you can manually add the desired entries using the ''Remove Desktop Entry'' and ''Remove Menu Entry'' buttons.
  
Under "Executable", the drop-down menu will display all of the binaries that came with the application. Select the binary that should launch when the user clicks the desktop icon or selects the application from the application menu. Alternately, you can select "Custom Binary" and input the path to the desired executable.
+
Under ''Executable'', the drop-down menu will display all of the binaries that came with the application. Select the binary that should launch when the user clicks the desktop icon or selects the application from the application menu. Alternately, you can select ''Custom Binary'' and input the path to the desired executable.
  
The "Entry Label" field allows you to customize the name that will appear with the icon and application menu entry.
+
The ''Entry Label'' field allows you to customize the name that will appear with the icon and application menu entry.
  
The "Icon" drop-down menu allows you to select the ''.png'' file to use for the icon. This file must exist in ''~/EasyPBI/Modules/PBI_name/resources'' in order to appear in the drop-down menu. Use the "Select Module" button to re-select the module if you add the icon after loading the module.
+
The ''Icon'' drop-down menu allows you to select the ''.png'' file to use for the icon. This file must exist in ''~/EasyPBI/Modules/PBI_name/resources'' in order to appear in the drop-down menu. Use the ''Select Module'' button to re-select the module if you add the icon after loading the module.
  
The "Menu Category" drop-down menu is used to select the category the application menu entry will be added to.
+
The ''Menu Category'' drop-down menu is used to select the category the application menu entry will be added to.
  
To add a desktop entry, select an "Executable", input an "Entry Label", and click the "+Add Desktop Entry" button. This will generate the ''.desktop'' file to be used by XDG-compliant desktops. The entry will appear under "Current Desktop Entries".
+
To add a desktop entry, select an ''Executable'', input an ''Entry Label'', and click the ''+&nbsp;Add Desktop Entry'' button. This will generate the ''.desktop'' file to be used by XDG-compliant desktops. The entry will appear under ''Current Desktop Entries''.
  
To add an application menu entry, select an "Executable", input an "Entry Label", and click the "+Add Menu Entry" button. The generated ''.desktop'' file will appear under "Current Menu Entries".
+
To add an application menu entry, select an ''Executable'', input an ''Entry Label'', and click the ''+&nbsp;Add Menu Entry'' button. The generated ''.desktop'' file will appear under ''Current Menu Entries''.
  
 
==== External-Links ====  
 
==== External-Links ====  
Line 171: Line 171:
 
[[Image:Easypbi7a.png]]
 
[[Image:Easypbi7a.png]]
  
To customize how a binary starts, highlight it and click the "Action" drop-down menu. The possible actions are:
+
To customize how a binary starts, highlight it and click the ''Action'' drop-down menu. The possible actions are:
  
 
* '''binary:''' indicates that this is an executable. EasyPBI will automatically create the necessary wrapper and PATH links for you.
 
* '''binary:''' indicates that this is an executable. EasyPBI will automatically create the necessary wrapper and PATH links for you.
Line 183: Line 183:
 
* '''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.
 
* '''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.
  
If you select an Action, use the up arrow to add it. If you change your mind, click the "Clear Changes" button.
+
If you select an ''Action'', use the up arrow to add it. If you change your mind, click the ''Clear Changes'' button.
  
 
=== Submit the Module ===
 
=== Submit the Module ===
Line 189: Line 189:
 
Once you are satisfied with the PBI, go to the "Module Editor" tab and use the "Select Module" button to select the PBI's module. Then click the "Package Module" 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. The file name for our example PBI is ''~dru/EasyPBI/Modules/trickle.tar.gz''.
 
Once you are satisfied with the PBI, go to the "Module Editor" tab and use the "Select Module" button to select the PBI's module. Then click the "Package Module" 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. The file name for our example PBI is ''~dru/EasyPBI/Modules/trickle.tar.gz''.
  
If you send that file to the {{citelink|url=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 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.
+
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.
 
+
== Create Your Own PBI Repository ==
+
 
+
By default, AppCafe® displays the PBIs which are available from the official PC-BSD repository. It also supports custom repositories, allowing organizations to create PBIs for their own applications and to make them available to their users within AppCafe®.
+
 
+
In order to create a custom repository, you need to:
+
 
+
* create the OpenSSL key which will be used to sign custom PBIs
+
 
+
* generate a repository file and populate it with custom PBIs
+
 
+
* generate the meta-data for the PBIs which are available within the repository
+
 
+
This section describes these steps in more detail.
+
 
+
=== Generate the Signing Key ===
+
 
+
Running a repository requires that all the PBIs in the custom repository be digitally signed for security and identification purposes. In order to sign the PBIs, generate an OpenSSL key pair using the following commands:
+
 
+
'''openssl genra -out privkey.pem 4096'''
+
Generating RSA private key, 4096 bit long modulus
+
..................++
+
.............................................................................++
+
e is 65537 (0x10001)
+
'''openssl rsa -in privkey.pem -pubout > pub.key'''
+
writing RSA key
+
 
+
These commands will create the files ''privkey.pem'' and ''pub.key''. The ''privkey.pem'' file will be used to digitally sign your created PBI files and the ''pub.key'' file will be included with the repository configuration (''.rpo'') file.
+
 
+
=== Create the Repository ===
+
 
+
In order to create the repository you will need a FTP, HTTP, or HTTPS server to host your repository’s meta-data files and to store the repository's PBIs.  The server can be a public URL on the Internet or a private LAN server, as long as it is accessible to your target audience.
+
 
+
Once you have the URL to the server, create the repository's ''.rpo'' file using the [[PBI_Manager#pbi_makerepo.281.29 | '''pbi_makerepo''']] command. Replace the values in the following example with your own description, path to your generated ''pub.key'' file, the URL to the location where the PBIs will be hosted, the URL to the location to contain the repository's meta-data files, and the directory to place the created ''.rpo'' file.
+
 
+
'''pbi_makerepo --desc “My Example Repository”  --key pub.key --mirror <nowiki>“ftp://ftp.example.org/pbi-files”</nowiki> --url <nowiki>“http://www.example.org/pbi-meta”</nowiki> /root'''
+
 
+
This command will generate the ''pbi-repo.rpo'' file in the specified directory on the server. This file is needed for clients to register and begin using the new repository. Clients also need to install this file on their PC-BSD desktop using this command as the superuser:
+
 
+
'''pbi_addrepo pbi-repo.rpo'''
+
 
+
Once the repository is registered on the clients system, their pbi daemon will automatically keep track of downloading and updating both meta-files and PBIs from the URLs you specified in the repository configuration file.
+
 
+
=== Generate the Repository's Meta-Data ===
+
 
+
On a PC-BSD system, you can now create the meta-data and PBI files so that clients have something to download. The meta-data file is used to give the client information about the PBIs available from the repository, such as categories, application names, and descriptions. When creating categories, you can use the same category names that appear in AppCafe®, or you can create your own categories. Each category and each PBI will need its own icon. These icons need to already exist on the server before generating the meta-data file.
+
 
+
When you are ready, create an empty meta-data file in the format ''pbi-meta-<Major Version Number>.'' This command should be used for 9.x series PBIs:
+
 
+
'''touch pbi-meta-9'''
+
 
+
Then use the [[PBI_Manager#pbi_metatool.281.29 | '''pbi_metatool''']] command to add the category for a PBI. The following command adds the Archivers category, its description, and the URL pointing to the mandatory 64x64 ''.png'' icon file to the specified meta-data file.
+
 
+
'''pbi_metatool add --cat -n “Archivers” -d “File Archivers and Utilities” -i <nowiki>“http://www.example.org/pbiicons/archivers.png”</nowiki> pbi-meta-9'''
+
 
+
Next, add the following information about the PBI: the name of the application, the category, the application author, a description of the application, the URL pointing to the mandatory 64x64 ''.png'' icon file for the application, a comma delimited list (with no spaces)  of search keywords, the type of license, the type of application (Graphical, Text, or Service), the URL to the application's website, and the name of the meta-data file to add the information to.
+
 
+
'''pbi_metatool add --app -n “cabextract” -c “Archivers” -a “Stuart Caie” -d “Utility for reading and extracting .cab files.” -i <nowiki>“http://www.example.org/pbi-icons/cabextract.png”</nowiki> -k “cab,archive,extract” -l “LGPL” -t “Text” -u <nowiki>“http://www.cabextract.org.uk” pbi-meta-9</nowiki>'''
+
 
+
Repeat this command for each PBI that will be available in the repository, creating new categories as you need to do so.
+
 
+
When you are finished adding the information for the repository's PBIs, compress the file with '''bzip2''' and upload it to the server. The location in our example would be  <nowiki>http://www.example.org/pbi-meta/pbi-meta-9.bz2</nowiki>. Once the file is uploaded, clients can use the [[PBI_Manager#pbi_browser.281.29 | '''pbi_browser''']] command or AppCafe® to browse the repository's PBIs.
+
 
+
You should now create your custom PBIs then upload them to their specified category in the download directory on the server. In our example, the download directory is <nowiki>ftp://ftp.example.org/pbi-files/</nowiki>. Refer to the section on [[PBI_Module_Builder_Guide#Building_PBIs_for_PC-BSD_9.x_and_higher | creating PBIs]] for instructions on creating PBIs using either the EasyPBI graphical utility or the '''pbi_makeport''' command line utility.
+
 
+
When creating your PBIs, remember to sign them with the private key. If you are using [[EasyPBI#Build_the_Module | EasyPBI]], specify the location to the ''privkey.pem'' file by clicking the Change File button shown in Figure 8.1d. If you are using the '''pbi_makeport''' command, include '''--sign privkey.pem''' in the command.
+
 
+
Lastly, create the ''pbi-index-9'' file and add the names of the uploaded PBIs to the file. Use the '''pbi_indextool''' to add each entry, specifying that PBI's filename (will end in ''.pbi''), the download location (in the format category/pbi_name), and the name of the index file.
+
 
+
'''touch pbi-index-9'''
+
'''pbi_indextool -f cabextract-1.2-amd64.pbi -u “archivers/cabextract-1.2-amd64.pbi” pbi-index-9'''
+
+
When you are finished adding entries to this file, use '''bzip2''' to compress it and upload the  ''pbi-index-9.bz2'' to the same location on the server which contains the ''pbi-meta-9.bz2'' file. Clients can now download and install PBIs from your custom repository, using the [[PBI_Manager#pbi_add.281.29 | '''pbi_add''']] command or AppCafe®.
+
  
 
<noinclude>{{refheading}}</noinclude>
 
<noinclude>{{refheading}}</noinclude>
Line 269: Line 196:
 
[[category:Control Panel]]
 
[[category:Control Panel]]
 
[[category:EasyPBI]]
 
[[category:EasyPBI]]
 +
[[category:webpage referred]]
 
</noinclude>
 
</noinclude>

Revision as of 12:59, 11 February 2013

(Sorry for the inconvenience)

Contents

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 section on how to Create PBIs first, as well as refer to that Guide should you have trouble creating a PBI or wish to create a more complex PBI.

To start EasyPBI, double-click its icon in Control Panel or type EasyPBI from within an X terminal as your regular user account.

If the ports collection is not installed, you will receive the message shown in Figure 8.1a the first time you start EasyPBI.

Figure 8.1a: Ports Must be Installed to Use EasyPBI

Easypbi1d.png

If multiple users will be using the EasyPBI utility, go to Control Panel System ManagerTasks and click the Fetch Ports Tree button. Alternately, use the following command as the superuser portsnap fetch extract. Either of these methods will install the ports collection into /usr/ports.

If you are the only user who will be using the EasyPBI utility, click OK to launch the main EasyPBI screen, shown in Figure 8.1b. Click FileGet Ports which will download the ports collection to the EasyPBI subdirectory located in your home directory.

Figure 8.1b: EasyPBI Graphical Interface

Easypbi1b.png

If the ports collection was already installed or was installed using System Manager or portsnap, the message in the bottom area of the screen will instead indicate To get started, please push the New Module button.

Creating a PBI Module

Before building a PBI, refer to the PBI Requests forum[1] 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[2] section of trac. Existing modules are listed alphabetically, according to their category in the ports collection.

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 in the GUI. In the example shown in Figure 8.1c, the net/trickle port has been selected and the fields have been auto-filled in.

Figure 8.1c: Review the New Module

Easypbi1c.png

You should review these fields for accuracy. If you click "Get Port Info" FreshPorts.org[3] 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 a 64x64 .png file with a transparent background.

Check the Create Desktop/Menu Entries' if you wish the program's icon to be available on the desktop and in the desktop's application menu.

Once the port information is complete, click the Create Module button and EasyPBI will produce the PBI module. The module will be named after the port and will be stored in a subdirectory of the EasyPBI/Modules directory in your home directory. In this example, the module is located in EasyPBI/Modules/trickle.

Build the Module

Creating the module itself is very quick and takes less than a minute. However, you still need to build and test the module to make sure that the application works as expected. Depending upon the complexity of the application, you may have to edit the initial module then rebuild and retest it until you are satisfied with the PBI for the application.

Once the module is created, you are ready to build a PBI from the module. Click on the Build PBI tab and click the Select Module button to browse to the module you created. Figure 8.1d shows this tab with our example PBI selected.

Figure 8.1d: The Build PBI Tab

Easypbi3b.png

The top half of this screen contains modifiable settings which are used when building PBIs:

Save Settings as Defaults: the settings in this section revert back to the default settings when you exit EasyPBI. This allows you to override the default settings for a particular build. If you wish your changes to be permanent, click this button.

Output Directory: specifies the directory to store the built module. By default, it is the EasyPBI/PBI subdirectory of the user's home directory. Click the Change Directory button to select another location.

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, click the Change File button to select your own digital signature file. Create Your Own PBI Repository provides instructions for creating a signature file.

Use TMPFS: if your build system has a lot of RAM, selecting this option can speed up the build.

Use Package Caching: this setting is recommended as it reuses previously built packages to speed up subsequent builds.

The rest of this screen is used to build the specified module:

Select Module: select the previously created module to build.

Build PBI: starts the build of the PBI module. It will prompt you for the superuser password and requires a working Internet connection in order 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. Will prompt you to select the location to store build.log which can be read with any ASCII text editor.

You can produce additional modules from the Create Module tab while a PBI build is running.

If the PBI build fails for some reason, you may need to modify the module as described in the next section. 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 to the pbi-dev mailing list[4].

Test and Fine-Tune the Module

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 the "Output 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
trickle-1.07_2_amd64.pbi    trickle-1.07_2_amd64.pbi.sha256
pbi_add --no-checksig trickle-1.07_2_amd64.pbi
Verifying Checksum...OK
Extracting to: /usr/pbi/trickle-amd64
Installed: trickle-1.07_2

If the module installs successfully, perform the following tests:

  • if you checked the box Create Desktop/Menu Entries, 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 GUI applications, 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[4].

The Module Editor tab, seen in Figure 8.1e, can be used to modify the module's settings. Use the Select Module button to browse to the location of the module and to un-grey-out the settings in this screen.

Figure 8.1e: EasyPBI Module Editor

Easypbi4a.png

Several tabs are provided, allowing you to customize the PBI module. It should be noted 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 require additional FreeBSD ports or scripts which are not provided by the default FreeBSD port.

The rest of this section describes the actions available within each tab. If you modify any settings in the PBI module, rebuild it then test again to see if the changes fixed the PBI.

pbi.conf

Typically the Program Name, Program Website, and Program Author are left at their default values. If this information is incorrect, you should email the FreeBSD port maintainer shown in the Program Author field so that the information can be corrected in the FreeBSD port.

If you choose to replace the Program 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.

Resources

This tab, shown in Figure 8.1f, is used to add additional files to the PBI module.

Figure 8.1f: PBI Module Resource Configuration

Easypbi5a.png

An example of an additional file would be an application that requires the user to accept a License. Use the + Add Resource button to browse to the location of the LICENSE file.

Another example would be when you wish to use a custom script to start the application rather than starting the application binary directly. A custom script could also be used to verify that the service is enabled or to generate a custom configuration file.

If the application uses custom installer graphics, add them using this screen.

Desktop/Menu Entries

This tab, shown in Figure 8.1g, is used to fine-tune the desktop icon and the application menu entry for the application.

Figure 8.1g: Customizing the PBI's Desktop and Menu Entries

Easypbi6a.png

If the Create Desktop/Menu Entries box was checked when creating the module and EasyPBI detects that the application is graphical, the default entries for the application will be listed. In our PBI example, trickle is a command line application so no entries were created by default. If your application is graphical but EasyPBI did not detect it, you can manually add the desired entries using the Remove Desktop Entry and Remove Menu Entry buttons.

Under Executable, the drop-down menu will display all of the binaries that came with the application. Select the binary that should launch when the user clicks the desktop icon or selects the application from the application menu. Alternately, you can select Custom Binary and input the path to the desired executable.

The Entry Label field allows you to customize the name that will appear with the icon and application menu entry.

The Icon drop-down menu allows you to select the .png file to use for the icon. This file must exist in ~/EasyPBI/Modules/PBI_name/resources in order to appear in the drop-down menu. Use the Select Module button to re-select the module if you add the icon after loading the module.

The Menu Category drop-down menu is used to select the category the application menu entry will be added to.

To add a desktop entry, select an Executable, input an Entry Label, and click the + Add Desktop Entry button. This will generate the .desktop file to be used by XDG-compliant desktops. The entry will appear under Current Desktop Entries.

To add an application menu entry, select an Executable, input an Entry Label, and click the + Add Menu Entry button. The generated .desktop file will appear under Current Menu Entries.

External-Links

This tab, shown in Figure 8.1h, is used to customize how the specified binary starts.

Figure 8.1h: Configuring Custom Links for the PBI

Easypbi7a.png

To customize how a binary starts, highlight it and click the Action drop-down menu. The possible actions are:

  • binary: indicates that this is an executable. EasyPBI 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 binary when linking a file into the LOCALBASE. By default, LOCALBASE is set to /usr/local.
  • replace: instructs the PBI to overwrite an existing binary 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.

If you select an Action, use the up arrow to add it. If you change your mind, click the Clear Changes button.

Submit the Module

Once you are satisfied with the PBI, go to the "Module Editor" tab and use the "Select Module" button to select the PBI's module. Then click the "Package Module" 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. The file name for our example PBI is ~dru/EasyPBI/Modules/trickle.tar.gz.

If you send that file to the pbi-dev mailing list[4], 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.

References


  1. http://forums.pcbsd.org/forumdisplay.php?f=61
  2. http://trac.pcbsd.org/browser#pbi/modules
  3. http://freshports.org
  4. 4.0 4.1 4.2 http://lists.pcbsd.org/mailman/listinfo/pbi-dev
Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox