PBI Module Builder Guide - Revision history

Tigersharke at 02:54, 30 April 2013

2013-04-30T02:54:55Z

Tigersharke: /* Creating a New PBI with pbi_makeport */

2013-04-01T12:35:38Z

‎Creating a New PBI with pbi_makeport

Tigersharke: /* Creating a New PBI with pbi_makeport */

2013-03-31T22:09:34Z

‎Creating a New PBI with pbi_makeport

Tigersharke: /* Creating a New PBI with pbi_makeport */

2013-03-31T22:07:32Z

‎Creating a New PBI with pbi_makeport

Tigersharke: /* Testing the PBI */ section moved to 'Create PBIs' page

2013-03-31T22:03:22Z

‎Testing the PBI: section moved to 'Create PBIs' page

Tigersharke: /* Creating a New PBI with pbi_makeport */

2013-03-31T22:02:15Z

‎Creating a New PBI with pbi_makeport

Tigersharke: /* Testing the PBI */

2013-03-31T21:57:50Z

‎Testing the PBI

Tigersharke: Some of this page may be redundant or out-dated, need to compare with PBI Manager page.

2013-03-31T21:37:51Z

Some of this page may be redundant or out-dated, need to compare with PBI Manager page.

Tigersharke: further refinement needed

2013-03-31T21:34:43Z

further refinement needed

Tigersharke at 20:09, 7 March 2013

2013-03-07T20:09:43Z

@@ Line 63: / Line 63: @@
 {{Tbl-init|caption=11.7a: Commonly Used pbi.conf Variables}}
-{{Tbl-title|width=15%|'''Variable'''}}
+!Variable
-{{Tbl-title|width=85%|'''Description'''}}
+!Description
 |-
-{{Tbl-cell|row=1|content='''PBI_PROGNAME='''}}
+|'''PBI_PROGNAME='''
-{{Tbl-cell|row=1|content=mandatory; should be the same value as PORTNAME= in the port's ''Makefile'', but capitalized}}
+|mandatory; should be the same value as PORTNAME= in the port's ''Makefile'', but capitalized
 |-
-{{Tbl-cell|row=2|content='''PBI_PROGWEB='''}}
+|'''PBI_PROGWEB='''
-{{Tbl-cell|row=2|content=mandatory unless does not exist; should be the same value as WWW= in the port's ''pkg-descr''}}
+|mandatory unless does not exist; should be the same value as WWW= in the port's ''pkg-descr''
 |-
-{{Tbl-cell|row=3|content='''PBI_PROGAUTHOR='''}}
+|'''PBI_PROGAUTHOR='''
-{{Tbl-cell|row=3|mandatory; often found in the port's ''pkg-descr'' or at the website for the application}}
+|mandatory; often found in the port's ''pkg-descr'' or at the website for the application
 |-
-{{Tbl-cell|row=4|content='''PBI_PROGICON='''}}
+|'''PBI_PROGICON='''
-{{Tbl-cell|row=4|mandatory path, relative to ''%%PBI_APPDIR%%'', to application icon file in ''.png'' format}}
+|mandatory path, relative to ''%%PBI_APPDIR%%'', to application icon file in ''.png'' format
 |-
-{{Tbl-cell|row=5|content='''PBI_PROGREVISION='''}}
+|'''PBI_PROGREVISION='''
-{{Tbl-cell|row=5|bump up a PBI's revision number; useful when rebuilding a port with new PBI specific options}}
+|bump up a PBI's revision number; useful when rebuilding a port with new PBI specific options
 |-
-{{Tbl-cell|row=6|content='''PBI_MAKEPORT='''}}
+|'''PBI_MAKEPORT='''
-{{Tbl-cell|row=6|mandatory; the path to the port within ''/usr/ports/''}}
+|mandatory; the path to the port within ''/usr/ports/''
 |-
-{{Tbl-cell|row=7|content='''PBI_MAKEOPTS='''}}
+|'''PBI_MAKEOPTS='''
-{{Tbl-cell|row=7|content=optional; set this to the options that you want saved to ''make.conf'' for the port building process (e.g. WITH_CUPS=YES)}}
+|optional; set this to the options that you want saved to ''make.conf'' for the port building process (e.g. WITH_CUPS=YES)
 |-
-{{Tbl-cell|row=8|content='''PBI_MKPORTBEFORE='''}}
+|'''PBI_MKPORTBEFORE='''
-{{Tbl-cell|row=8|content=optional; port(s) to build before building the PBI}}
+|optional; port(s) to build before building the PBI
 |-
-{{Tbl-cell|row=9|content='''PBI_MKPORTAFTER='''}}
+|'''PBI_MKPORTAFTER='''
-{{Tbl-cell|row=9|optional; port(s) to build after building the PBI}}
+|optional; port(s) to build after building the PBI
 |-
-{{Tbl-cell|row=10|content='''PBI_BUILDKEY='''}}
+|'''PBI_BUILDKEY='''
-{{Tbl-cell|row=10|should not be included; this variable is used on the PBI build server to force the rebuild of a PBI that has failed to build}}
+|should not be included; this variable is used on the PBI build server to force the rebuild of a PBI that has failed to build
 |-
-{{Tbl-cell|row=11|content='''PBI_REQUIRESROOT='''}}
+|'''PBI_REQUIRESROOT='''
-{{Tbl-cell|row=11|set to to YES to require this app to be installed as root; default is NO which allows it to be installed as a regular user }}
+|set to to YES to require this app to be installed as root; default is NO which allows it to be installed as a regular user
 |-
-{{Tbl-cell|row=12|content='''PBI_EXCLUDELIST='''}}
+|'''PBI_EXCLUDELIST='''
-{{Tbl-cell|row=12|list of files or directories to exclude from the final archive, such as ''./include'' or ''./share''}}
+|list of files or directories to exclude from the final archive, such as ''./include'' or ''./share''
 |-
-{{Tbl-cell|row=13|content='''PBI_AB_PRIORITY='''}}
+|'''PBI_AB_PRIORITY='''
-{{Tbl-cell|row=13|may be set by build server administrator; a higher number indicates a greater priority and will be built before lower priority PBIs}}
+|may be set by build server administrator; a higher number indicates a greater priority and will be built before lower priority PBIs
 |-
-{{Tbl-cell|row=14|content='''PBI_AB_NOTMPFS='''}}
+|'''PBI_AB_NOTMPFS='''
-{{Tbl-cell|row=14|set to YES to disable using tmpfs when doing auto-builds on a server}}
+|set to YES to disable using tmpfs when doing auto-builds on a server
 |-
-{{Tbl-cell|row=15|content='''PBI_HASH_EXCLUDES='''}}
+|'''PBI_HASH_EXCLUDES='''
-{{Tbl-cell|row=15|set to a space delimited list of files to exclude from merging into the shared hash-dir}}
+|set to a space delimited list of files to exclude from merging into the shared hash-dir
 |-
-{{Tbl-cell|row=16|'''export'''}}
+|'''export'''
-{{Tbl-cell|row=16|mandatory; followed by a list of all of the variables that will be included when the PBI is built}}
+|mandatory; followed by a list of all of the variables that will be included when the PBI is built
 |-
 |}
@@ Line 168: / Line 168: @@
 {{Tbl-init|caption=11.7b Supported Variables}}
-{{Tbl-title|width=15%|'''Variable'''}}
+!Variable
-{{Tbl-title|width=85%|'''Description'''}}
+!Description
 |-
-{{Tbl-cell|row=1|content='''PBI_PROGNAME='''}}
+|'''PBI_PROGNAME='''
-{{Tbl-cell|row=1|content=mandatory; should be the same value as PORTNAME= in the port's ''Makefile'', but capitalized}}
+|mandatory; should be the same value as PORTNAME= in the port's ''Makefile'', but capitalized
 |-
-{{Tbl-cell|row=2|content='''PBI_PROGDIRNAME='''}}
+|'''PBI_PROGDIRNAME='''
-{{Tbl-cell|row=2|name of the subdirectory that is created for the PBI in ''/usr/pbi/'' (e.g. "firefox-amd64" for the 64-bit Firefox PBI)}}
+|name of the subdirectory that is created for the PBI in ''/usr/pbi/'' (e.g. "firefox-amd64" for the 64-bit Firefox PBI)
 |-
-{{Tbl-cell|row=3|content='''PBI_PROGDIRPATH='''}}
+|'''PBI_PROGDIRPATH='''
-{{Tbl-cell|row=3|full path to the PBI install directory (e.g. ''/usr/pbi/firefox-amd64/'' for the 64-bit Firefox PBI)}}
+|full path to the PBI install directory (e.g. ''/usr/pbi/firefox-amd64/'' for the 64-bit Firefox PBI)
 |-
-{{Tbl-cell|row=4|content='''PBI_PROGVERSION='''}}
+|'''PBI_PROGVERSION='''
-{{Tbl-cell|row=4|version of the program - should be the same value as the DISTVERSION in the port's Makefile }}
+|version of the program - should be the same value as the DISTVERSION in the port's Makefile
 |-
-{{Tbl-cell|row=5|content='''PBI_RCDIR='''}}
+|'''PBI_RCDIR='''
-{{Tbl-cell|row=5|location of ''rc.d/'' directory used by PBIs, usually ''/usr/local/etc/rc.d'' }}
+|location of ''rc.d/'' directory used by PBIs, usually ''/usr/local/etc/rc.d''
 |-
-{{Tbl-cell|row=6|content='''SYS_LOCALBASE='''}}
+|'''SYS_LOCALBASE='''
-{{Tbl-cell|row=6|LOCALBASE of the default system, typically ''/usr/local'' }}
+|LOCALBASE of the default system, typically ''/usr/local''
 |-
-{{Tbl-cell|row=7|content='''PBI_FAKEBIN_DIR<nowiki>=</nowiki>'''}}
+|'''PBI_FAKEBIN_DIR='''
-{{Tbl-cell|row=7|the binary wrapper directory, typically ''/usr/pbi/<pbidir>/.sbin/'' }}
+|the binary wrapper directory, typically ''/usr/pbi/<pbidir>/.sbin/''
 |-
 |}

@@ Line 274: / Line 274: @@
 The first time you run the '''pbi_makeport''' command, a clean chroot environment will automatically download and install. This chroot environment will be used for all PBI builds. If the filesystem is UFS, installing the chroot may take a few minutes. If the filesystem is ZFS and you accepted the default ZFS layout (which includes ''/usr/pbi/''), installing the chroot should happen almost instantaneously.
-'''NOTE:''' each time you run '''pbi_makeport''', it cleans up its environment, including all of the files that it downloaded and built. Since you may have to rebuild your PBI after testing it, you can save re-downloading and re-building all of these files again by including the '''--pkgdir <dir>''' option. You can manually remove that directory when you are finished if you need to save disk space.
+{{note|icon64=each time you run '''pbi_makeport''', it cleans up its environment, including all of the files that it downloaded and built. Since you may have to rebuild your PBI after testing it, you can save re-downloading and re-building all of these files again by including the '''--pkgdir <dir>''' option. You can manually remove that directory when you are finished if you need to save disk space.}}
 FreeBSD ports may contain build dependencies, runtime dependencies, and required libraries. When building a PBI, '''pbi_makeport''' automatically compiles all of the required dependencies. When the build is finished, it prunes the build dependencies before packaging the PBI file, leaving only the runtime packages and libraries that are required for the program to work. This means that any files which are included in the PBI are necessary for the program to run, and manually removing them will cause the program to fail.

@@ Line 303: / Line 303: @@
 AutoUpdate: NO}}
-Once the process completes and a PBI is built successfully, it is very important to [[create PBIs#test the PBI|test the PBI]], especially if the intent is to submit it for inclusion in AppCafe. Even quality control for your own sake is good because it will aid in learning the PBI build process, also, it will be easier to make corrections while everything is still fresh in your mind and little else has changed.
+Once the process completes and a PBI is built successfully, it is very important to [[create PBIs#test the PBI|test the PBI]], especially if the intent is to submit it for inclusion in AppCafe. Even quality control for your own sake is good because it will aid in learning the PBI build process. It will be easier to make corrections while everything is still fresh in your mind and little else has changed.
 <noinclude>

@@ Line 303: / Line 303: @@
 AutoUpdate: NO}}
-Once the process completes and a PBI is built successfully, it is very important to [[create PBIs#test the PBI|test the PBI]], especially if the intent is to submit it for inclusion in AppCafe.
+Once the process completes and a PBI is built successfully, it is very important to [[create PBIs#test the PBI|test the PBI]], especially if the intent is to submit it for inclusion in AppCafe. Even quality control for your own sake is good because it will aid in learning the PBI build process, also, it will be easier to make corrections while everything is still fresh in your mind and little else has changed.
 <noinclude>

← Older revision		Revision as of 22:03, 31 March 2013
Line 304:		Line 304:

	Once the process completes and a PBI is built successfully, it is very important to [[create PBIs#test the PBI\|test the PBI]], especially if the intent is to submit it for inclusion in AppCafe.		Once the process completes and a PBI is built successfully, it is very important to [[create PBIs#test the PBI\|test the PBI]], especially if the intent is to submit it for inclusion in AppCafe.
−
−	~~=== Testing the PBI ===~~
−
−	~~Once your PBI has built, test the PBI to ensure that it installs and that the application works.~~
−
−	~~As the superuser, use the '''pbi_add''' command with the '''--no-checksig''' option:~~
−
−	~~{{txtbox\|pre\|box='''pbi_add --no-checksig /path_to_pbi'''}}~~
−
−	Once installed, start the application from the command line to determine if there are any error messages at application launch. When testing the executable, use the one located in ''/usr/pbi/(pbi-name)/bin/'' so all the linking will be properly set up. Otherwise you can get some interesting errors about missing files.
−
−	If the executable does not start the application, the executable may actually be a wrapper script rather than a binary file. If so, check the first line of the script to make sure that it is using the right path for the scripting language. For example, ''#!/bin/python'' is an incorrect path which should be changed to ''#!/usr/pbi/(pbi-name)/bin/python''.
−
−	The suggested path works because each program is packaged with the proper version of the language it uses and you want to make sure it uses that one. This is usually accomplished by putting a quick '''sed''' line in the ''post-install.sh'' script to fix the first line as seen in the post install script for {{citelink\|url=http://trac.pcbsd.org/browser/pbi/modules/games/fretsonfire/scripts/post-install.sh?rev=13019\|txt=frets on fire}}.
−
−	~~If the application starts and it is a GUI 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 to the {{citelink\|url=http://lists.pcbsd.org/mailman/listinfo/pbi-dev\|txt=pbi-dev mailing list}}.
−
−	~~If your PBI works and you would like to submit its module to be included on the build server, compress it after changing to your module directory (%%PBI_APPDIR%%):~~
−
−	~~{{txtbox\|pre\|box=>'''cd /usr/local/my_pbis'''<br>>'''tar czvf ~/your_pbi_name.tar.gz .'''}}~~
−
−	This will create a compressed tarball named ''your_pbi_name.tar.gz'' in your home directory. Send this file to the {{citelink\|url=http://lists.pcbsd.org/mailman/listinfo/pbi-dev\|txt=pbi-dev mailing list}}.

	<noinclude>		<noinclude>

@@ Line 302: / Line 302: @@
 Signature: Not Signed
 AutoUpdate: NO}}
 === Testing the PBI ===

@@ Line 319: / Line 319: @@
 If the application starts and it is a GUI 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 {{citelink|url=http://lists.pcbsd.org/mailman/listinfo/pbi-dev|txt=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 to the {{citelink|url=http://lists.pcbsd.org/mailman/listinfo/pbi-dev|txt=pbi-dev mailing list}}.
 If your PBI works and you would like to submit its module to be included on the build server, compress it after changing to your module directory (%%PBI_APPDIR%%):

← Older revision		Revision as of 21:37, 31 March 2013
Line 1:		Line 1:
−	<noinclude>{{~~NavHeader\|back=Test PBIs\|forward=Purchase PC-BSD® Swag\|custompagename=Create PBIs~~}}</noinclude>	+	<noinclude>{{NavHome}}</noinclude>

	PC-BSD® provides a unique file format known as a PBI (push button installer). PBI files end with the ''.pbi'' extension and are self-contained installation programs. This means that even novice users can safely install and uninstall PBIs without inadvertently overwriting or deleting files needed by the operating system or other applications.		PC-BSD® provides a unique file format known as a PBI (push button installer). PBI files end with the ''.pbi'' extension and are self-contained installation programs. This means that even novice users can safely install and uninstall PBIs without inadvertently overwriting or deleting files needed by the operating system or other applications.

← Older revision		Revision as of 21:34, 31 March 2013
Line 2:		Line 2:

	PC-BSD® provides a unique file format known as a PBI (push button installer). PBI files end with the ''.pbi'' extension and are self-contained installation programs. This means that even novice users can safely install and uninstall PBIs without inadvertently overwriting or deleting files needed by the operating system or other applications.		PC-BSD® provides a unique file format known as a PBI (push button installer). PBI files end with the ''.pbi'' extension and are self-contained installation programs. This means that even novice users can safely install and uninstall PBIs without inadvertently overwriting or deleting files needed by the operating system or other applications.
−
−	A PBI file includes all the runtime and library dependencies required by the application. This means that a PBI is a large file, but this does not necessarily mean that the installed PBI will be that large. During installation, the PBI system compares the currently installed libraries and files with the ones contained within the PBI file and only installs the ones that are not already installed on the system. A hash database is used to eliminate dependency problems while allowing the computer to share libraries between different programs.
−
−	~~Once a PBI is created, it can be installed using the graphical [[Using AppCafe® \| AppCafe®]] utility or from the command line using [[PBI Manager]].~~
−
−	In order to create a PBI, the software must already be ported to FreeBSD. The easiest way to confirm whether or not a FreeBSD port exists is to search for the software at {{citelink\|url=http://www.freshports.org\|txt=FreshPorts.org}}. If a port does not exist, you can issue a port request at the PC-BSD® Port Requests forum using {{citelink\|url=http://forums.pcbsd.org/showthread.php?t=13743\|txt=these instructions}}. Alternately, if you have ported software before, the {{citelink\|fbsdph\|\|txt=Porters Handbook}} contains detailed instructions for porting software to FreeBSD.
−
−	Creating a PBI from an existing FreeBSD port is a mostly automated process that does not require development skills. Some ports are effortless to convert while more complex ports may require some thought and simple scripting. Two utilities are available for converting a FreeBSD port into a PBI:
−	~~# '''EasyPBI:''' provides a graphical interface and is available in Control Panel. See the [[Using EasyPBI \| EasyPBI ]] section of the Handbook for instructions on how to use this utility.<br>~~
−	~~# '''pbi_makeport:''' provides a command line utility.~~
−
−	~~This section explains the components of a PBI module, demonstrates how to use the '''pbi_makeport''' utility, and provides some troubleshooting tips.~~
−
−	{{note\|before creating a PBI, check to see if one exists using the instructions in [[Submit PBI Requests]]. If you decide that you prefer to request a PBI that you need rather than to create one, that page also contains instructions for submitting a PBI request.}}

	=== PBI Module Components ===		=== PBI Module Components ===

@@ Line 15: / Line 15: @@
 This section explains the components of a PBI module, demonstrates how to use the '''pbi_makeport''' utility, and provides some troubleshooting tips.
-'''NOTE:''' before creating a PBI, check to see if one exists using the instructions in [[Submit PBI Requests]]. If you decide that you prefer to request a PBI that you need rather than to create one, that page also contains instructions for submitting a PBI request.
+{{note|before creating a PBI, check to see if one exists using the instructions in [[Submit PBI Requests]]. If you decide that you prefer to request a PBI that you need rather than to create one, that page also contains instructions for submitting a PBI request.}}
 === PBI Module Components ===
@@ Line 75: / Line 75: @@
 Table 11.7a describes the most commonly used variables. When creating your ''pbi.conf'' file, refer to the FreeBSD port's ''Makefile'' and ''pkg-descr'' to determine which values to use.
 {{Tbl-init|caption=11.7a: Commonly Used pbi.conf Variables}}
@@ Line 181: / Line 180: @@
 Table 11.7b summarizes the variables that may be used in these scripts:
 {{Tbl-init|caption=11.7b Supported Variables}}
@@ Line 343: / Line 341: @@
 This will create a compressed tarball named ''your_pbi_name.tar.gz'' in your home directory. Send this file to the {{citelink|url=http://lists.pcbsd.org/mailman/listinfo/pbi-dev|txt=pbi-dev mailing list}}.
 <noinclude>
 [[category:handbook]]
 [[category:Supporting PC-BSD®]]