|
||
PC-BSD is a free operating system with ease of use in mind. Like any modern system, you can listen to your favorite music, watch your movies, work with office documents and install your favorite applications with a setup wizard at a click.
| PBI Documentation |
|
|
|
PC-BSD provides a home for the PBI (Push Button Installer) package management system, which allows users to easily load & remove applications in an entirely self-contained manner. The format is easy to use, and allows developers to define menu and desktop icons, along with registering mime types. This document is meant to help assist software developers in packaging with this format. Table of Contents
e first thing you will need to do is download a copy of the PBI Creator program and load it onto your PC-BSD desktop. (Simply double-click the PBI creator file to start the installation) After entering your root password, you will be presented with the main install screen. Simply click next a few times and the software will be loaded.
Thats it! The PBI creator is now loaded on your system. You should have a desktop icon and menu icon to run the creator now. But first, we need to start populating your program directory.
Populating your program directory Before you run the PBI creator GUI for the first time, you will need to setup the program directory that you plan on packaging. In this example we will be working with the Wine application. Below is our default directory structure:
The PBI format is designed to be entirely self contained. Whatever is placed into your program directory as shown above will be installed on the users system under /Programs/<ProgramName + ProgramVersion>/ or as in this example, /Programs/Wine0.9.48/ The bin/ directory is where you would normally place all the binaries your program will need for operation. When a user runs your program, the bin/ directory you include here will be placed as the first search path for your application. (I.E. When the user runs "wine" and the "wine" program tries to call the application "wineserver" it will look in /Programs/Wine0.9.48/bin/ for the "wineserver" binary before looking in the system folders). This allows you to package your application with any specific supporting binaries they may need, reguardless of what else is installed on the system. The autolibs/ directory is also special, in that this is where the PBI creator will try to copy any required libraries that your application needs for runtime. Any binaries you place in bin/ will be queried with "ldd" to determine its library requirements, and these libs will be placed in the autolibs directory. This is apart of what makes the PBI format self-contained, by allowing applications to have all the necessary libs for operation available at runtime. By creating this directory beforehand, you can also place any libraries / files which your application may need, but may not show up with the "ldd" command. In this example, we have also created a few other directories and copied some icons over which we will use during the PBI creation process.
After you have placed all the files you need for your application in a directory, its time to start the PBI creator. After you load the application, you will be presented with the initial setup screen:
On the first screen of the PBI creator wizard, you will need to fill out some information about your PBI to continue. The name and version you specify here will become the directory name of your application during the install. (I.E. /Programs/Wine0.9.48") Also the PBI Version number may be specified, this will be used for the final creation of your install file in the "PV" string such as "Wine0.9.48-PV01.pbi". This is helpful when you want to issue updated versions of your PBI, but the actual version number of your application has not changed. The "Load saved preset" button allows you to load a previously saved "*.pbc" file, which will contain a previous PBI configuration that you may have made. You will be given the option to create this .pbc file at the end of the wizard, which comes in handy for re-making PBI's down the road, and using the command-line creation option. After you have filled out the necessary values, simply hit "Next" to continue onto the next screen.
On this screen you may specify if you want the user to agree to a license before installing your application. Simply paste any license text and choose "Yes" to "Display License" if you want this feature. In this example we will set it to "No" and the user will not be prompted to accept any license to install. When finished with your license text, simply hit "Next" to continue.
Now it's time to specify the location for your application directory that we created previously. After setting this directory you will also need to choose your library options. The default option is to auto-populate the program libraries, using the autolibs/ directory as discussed previously. This will run the "ldd" command on any binaries you place in bin/ or list on the next screen, and copy their necessary libraries into the autolibs/ directory. Also, if you instead want to manually populate your program libraries you can choose "Specify library directory" to use any other directory in your main application structure. At the bottom of this screen we have three buttons for setting up scripts you may wish to run during the PBI install / removal. These scripts are used as follows:
Lets start by taking a look at a working PBI.FirstRun.sh script
In this example, the script is very simple. It is only checking to ensure that Wine isn't already loaded on the users system, and halting if it is. By exiting with a status of "2" that informs the PBI installer that it shouldn't continue with the install, and exit / cleanup. There are also several important variables which you can use in this script:
Also you may notice that we are using the "kdialog" command to interface with the user. "kdialog" should be present on every version of PC-BSD down the road, so it is a safe way to communicate with the user in a graphical format. There are also a few comments about the "echo" commands you may use, which will be discussed in the "Advanced" section of this guide. Now lets take a look at an example of the PBI.SetupScript.sh in action:
In this example we are making use of the ${PROGDIR} variable to ensure that a few of our binaries we will be using are also available system-wide. Notice that we are linking to the ".sbin/" directory. This is a special directory that the PBI program will make during an installation. Any binaries that you specify on the next wizard screen as menu / desktop icons will have a corresponding script created with the same name in .sbin/ of your applications install folder. This script sets up the access to the autolibs directory, and enables the CrashHandler utility to run with your program. (CrashHandler is used when your program crashes, and displays all the stdout / stderr messages in a GUI for the user to troubleshoot) The PBI.RemoveScript.sh is similar to both of these, and in this case we would only need to remove the /usr/local/bin/wine links we created upon program removal. On this screen you can setup all the kmenu & desktop icons you want with your program. Also you may setup the "Default Icon" above, which is used for menu folders, and in the add / remove programs tool. Lets take a look at the setup for the main "Wine" application.
On this screen you are provided with many options for your icon / menu link. First you are able to override whatever your default program icon happens to be, if you need to do so, then you would enter the name for this application. After that you can set various options for how this is to function. In this case we have told the PBI creator to not make a desktop or kmenu icon for this binary. This is done because the "wine" binary itself doesn't have an associated GUI, but we still want to create our .sbin/ entry for this application during run-time. (See above for description on .sbin/ scripts) After we have setup our program icons, and their placement, its time to move onto the Mime setup.
Most programs will probably not need to define a mime type, but in the case of wine we want to register the .exe extension as being opened with "Wine" automatically. Simply enter the extension pattern as shown, and select the program you want to open this with. The PBI creator will handle the rest automatically. Once you are finished with mime-types, clicking next will start the actual build of the PBI file. Notice that you are provided with an option to "Save Preset". This allows you to create a .pbc file, saving all the configuration information for this PBI you've created. This .pbc file can be loaded at the start of the wizard, saving you time from having to re-enter all the setup configuration. Also with this .pbc, you can automate the process of creating your PBI file with the createpbi.sh script at the command-line. (Please see the Advanced section for more information about this and other topics)
|
