Creating an OptionalPackage

With the introduction of package management, optional packages - and therefore this page - became obsolete.

This page details the steps in creating an OptionalPackage. In addition to being a regular binary distribution archive, an OptionPackage includes a plain text file called .OptionalPackageDescription and possibly the license file.

NOTE: With the recent incorporation of package management, OptionalPackages are obsolete. Haiku package files (HPKG) replace them. See PackageManagement/BuildingPackages and HaikuPorter / BuildRecipes for instructions on creating HPKG's.

.OptionalPackageDescription

In changeset 25050, support for these files was introduced. The contents of .OptionalPackageDescription is appended to AboutSystem's "COPYRIGHTS" attribute, which will cause the respective info to be shown in the about view.

Creating from scratch

When creating a new .OptionalPackageDescription file, it is advisable to use a monospaced font, such as "DejaVu Sans Mono". This will make it easier to ensure the accuracy of white space formatting. Every .OptionalPackageDescription file must contain the same six fields, "Package:", "Version:", "Copyright:", "License:", "URL:", "SourceURL:". The whitespace separating the fields from the values are tabs and not spaces. "Copyright:" lists copyright years and the copyright holders. Multiple "Copyright:" lines are allowed. Each is displayed on a separate line in AboutSystem. "License:" refers to the filename of the license used by a particular OptionalPackage. Haiku includes several often-used licenses, which can be used. If the OptionalPackage uses a different license, it is suggested to simply rename its license file to the Package name. In addition, multiple "License:" lines can be used when necessary. "SourceURL:" is used to provide links to patched source code, build instructions, and the like. There can be multiple "SourceURL:" line, each displaying as an embedded url in a comma separated list. eg: "Source Code: Instructions, Download".

Example

This is the .OptionalPackageDescription file from the OptionalPackage openssl-0.9.8k-gcc2-haiku-2009-05-09.zip. For the sake of this example, it has been modified by the addition of dummy SourceURL lines.

Package:	OpenSSL
Version:	0.9.8k
Copyright:	1995-1998 Eric Young , 1998-2008 The OpenSSL Project.
License:	OpenSSL
URL:		http://www.openssl.org/
SourceURL:	Instructions <http://ports.haiku-files.org/wiki/dev-libs/openssl/0.9.8k/1>
SourceURL:	Download <http://www.haiku-files.org/files/optional-packages-sources/openssl>
<end with a blank line>

License File

Depending on the type of license, it may be necessary to include a copy of it with the binary distributions. Due to the multitude and variance of open-source licenses, the safest way to be sure of what to do is to simply read the license file.

Possible Locations

These are all of the supported locations for licenses.

/boot/common/data/licenses/
/boot/home/config/data/licenses/
/boot/system/data/licenses/ Technically this is a valid location for licenses. However by convention, third-party apps and end-users should never place files in /boot/system/.

Filename

It is necessary to rename that particular license file to the name of the software package. For example, LICENSE from openssl-0.9.8k.tar.gz should be renamed to "OpenSSL". Details such as version number, gcc, and build date are omitted. Renaming of the license file must be done because licenses from other software packages will reside in the same folder and it is important to be able to easily determine which license belongs to which software package. As mentioned above, the filename must be the values for "License:".

Packaging Archive

Create your archive as you typically would. HaikuPorts has a wiki page describing some methods for creating an archive from ported software. Include .OptionalPackageDescription in the top-most directory of the binary distribution archive. If the license file declares that a copy must accompany binary distributions, be certain to include the renamed license as noted above. It is preferable to use the following naming scheme for the archive: <softwareName>-<softwareVersion>-<platform>-<buildDate>.zip

Notes:

when <platform> is x86, differentiate between x86_gcc2 and x86_gcc13
<buildDate> is YYYY-MM-DD format, also known as ISO 8601

Creating and Submitting Patch

Most of the time, OptionalPackages is the file that needs to be edited to add or update your OptionalPackage. Once in a while, OptionalPackageDependencies may need to be updated. Below is an example on how to properly create a patch for /path/haiku/build/jam/OptionalPackages.

cd /path/haiku/
git diff build/jam/OptionalPackages > ~/OptionalPackage-<new-pkg>.patch

From the above OpenSSL example, "<new-pkg>" could be "openssl-0.9.8k". Submit this patch to Haiku's Bug Tracker as a new enhancement ticket. It is advisable to have a subject similar to
"[patch] OptionalPackages - Updated <new-pkg>"

Notes

See Ticket #3930 and haiku-development ML thread for some relevant information. These two links discuss the issue of giving attribution to an OptionalPackage's included dependencies and that AboutSystem needs a mechanism for handling duplicate entries.

Multiple OptionalPackageDescriptions can be encapsulated within the same file. Simply separate them with a blank line.

Some software uses multiple licenses. To handle this, simply mention each "License: " on a separate line.

Sharing Your Optional Package

Now that you have created an optional package, it's time to suggest having it included as part of Haiku's build system. Just be aware that the Haiku Project may not want every package to be part of the build system.

The next steps include creating a patch of Haiku's build system and creating a new ticket on the development tracker. The patch should be for build/jam/OptionalPackages, build/jam/OptionalLibPackages,build/jam/OptionalPackageDependencies , depending on what the software is and if it depends upon other packages. See Submitting Patches for more information on how to create a patch for reviewal. In the new ticket mention why the package should be made available in Haiku's build system. For instance, does it make contributing to Haiku easier? Does it fill a common need for many people? If the program is accepted, the binary will then be mirrored on one of Haiku's mirrors.