Build Recipes

Overview

A build recipe is a special kind of shell script that tells HaikuPorter the specific details about how a particular version of a port should be built and which packages should be created from the build results.

There's a two-way "communication" (using environment variables and shell functions) between HaikuPorter and the build recipe script:

Input (HaikuPorter -> Build Recipe Script)

A set of environment variables is set up by HaikuPorter and passed down to the script at invocation time. These variables can be inspected by the recipe script in order to adjust details of the build configuration. Most notably, a lot of variables correspond to directories where files should be put by the build. Additionally, several shell functions are being made available to the recipe script, which can (and should!) be invoked by the recipe in order to do some specific tasks (e.g. invoking the configure script or processing built static libraries).

Output (Build Recipe Script -> HaikuPorter)

Several environment variables need to be initialized by the recipe script in order to pass information about build details back to HaikuPorter. Additionally, shell functions implementing the different build phases have to be defined by the recipe script. HaikuPorter will invoke these functions when needed (e.g. the actual commands to be used for building a port must be defined in a shell function named BUILD).

Input

Environment Variables

Most of the environment variables passed from HaikuPorter to the build recipe script define a directory for putting a certain type of files created by the build process. Many of these can/should be passed to the configure-script used by many ports.

Whenever an absolute path is required by the build process, HaikuPorter uses the package-links folder to abstract the actual installation path, such that the resulting packages will work, no matter to which packages-folder (e.g. /boot/common/packages or /boot/home/config/packages) they are being installed.

Here's a list of all input environment variables:

• $addOnsDir: The absolute directory for add-ons.
• $appsDir: The absolute directory for applications.
• $binDir: The absolute directory for binaries.
• $buildArchitecture: The Haiku architecture HaikuPorter is running on (e.g. x86_gcc2).
• $configureDirArgs: A string containing all the standard configure options with their respective value. This can be used instead of passing all the individual variables to configure (but you should use runConfigure() instead, anyway).
• $configureDirVariables: A string containing a space separated list of names of all directory variable names.
• $dataDir: The absolute directory for data.
• $dataRootDir: The absolute base directory for data. On Haiku, this is the same as $dataDir.
• $developDir: The absolute path to the directory underneath of which all development-related files should be put.
• $developDocDir: The absolute base directory for development-related documentation specific to the port being built. Documentation in html- or pdf-format should be put here, manpages should be put into $manDir.
• $developLibDir: The absolute directory for development libraries (i.e. static and shared libraries provided by a devel package). Shared libraries required at runtime don't belong here, they should be put into $libDir.
• $docDir: The absolute base directory for (non-development) documentation specific to the port being built. Documentation in html- or pdf-format should be put here, manpages should be put into $manDir.
• $documentationDir: The absolute base directory underneath of which all documentation should be put. This is not a port-specific directory.
• $fontsDir: The absolute directory for fonts.
• $haikuVersion: The version of Haiku for which the port is being built.
• $includeDir: The absolute directory for header files
• $infoDir: The absolute directory for documentation in info-format (which is frowned upon by Haiku ports)
• $isCrossRepository: Is true if the ports tree being used is the one dealing with cross-building the bootstrap packages.
• $jobArgs: If HaikuPorter has been invoked with --jobs=<num>, this contains the job-number specification applicable to make (i.e. -j<num>)
• $jobs: The number of build jobs to run concurrently (can be set with haikuporter --jobs=<num>
• $libDir: The absolute directory for shared libraries to be used at runtime (i.e. by Haiku's runtime loader)
• $libExecDir: The absolute directory for executables that a port may invoke internally. On Haiku, this is the same as $libDir.
• $localStateDir: The absolute directory for putting files created at runtime. This corresponds to the var-hierarchy.
• $manDir: The absolute directory for man-pages. For each man section, a subdir exists underneath this directory.
• $oldIncludeDir: Another name of the absolute directory for putting header files ($includeDir).
• $portBaseDir: The absolute directory (on the build host!) of this build recipe file. This can be useful if you'd like to use local (i.e. file:///-) URLs to other ports. An example is the gcc-recipe using a local URL to reference the source directory of the binutils port (which both live in the same git repository).
• $portDir: The absolute directory (on the build host!) where the files of the current port (patches, license, recipes) can be found.
• $portFullVersion: Full version of the current port, including revision (e.g. 2.14-1)
• $portName: Name of the current port.
• $portPackageLinksDir: The absolute path to the package-links directory of this port's base (main) package. This is useful if the current port needs to reference files from another (required) ports via absolute path. Again, this make use of the package-links abstraction, such that these cross-package references will work, no matter where a specific package is installed.
• $portRevision: The revision of the current port (e.g. 1).
• $portRevisionedName: The name of the current port, extended by version and revision (e.g. grep-2.14-1)
• $portVersion: The version of the current port (e.g. 2.14).
• $portVersionedName: The name of the current port, extended by version (e.g. grep-2.14).
• $preferencesDir: The absolute directory for preflets.
• $prefix: The absolute base directory of the port (i.e. the installation location).
• $relativeAddOnsDir: $addOnsDir as a relative directory (to prefix).
• $relativeAppsDir: $appsDir as a relative directory (to prefix).
• $relativeBinDir: $binDir as a relative directory (to prefix).
• $relativeDataDir: $dataDir as a relative directory (to prefix).
• $relativeDataRootDir: $dataRootDir as a relative directory (to prefix).
• $relativeDevelopDir: $developDir as a relative directory (to prefix).
• $relativeDevelopDocDir: $developDocDir as a relative directory (to prefix).
• $relativeDevelopLibDir: $developLibDir as a relative directory (to prefix).
• $relativeDocDir: $docDir as a relative directory (to prefix).
• $relativeDocumentationDir: $documentationDir as a relative directory (to prefix).
• $relativeFontsDir: $fontsDir as a relative directory (to prefix).
• $relativeIncludeDir: $includeDir as a relative directory (to prefix).
• $relativeInfoDir: $infoDir as a relative directory (to prefix).
• $relativeLibDir: $libDir as a relative directory (to prefix).
• $relativeLibExecDir: $libExecDir as a relative directory (to prefix).
• $relativeLocalStateDir: $localStateDir as a relative directory (to prefix).
• $relativeManDir: $manDir as a relative directory (to prefix).
• $relativeOldIncludeDir: $oldIncludeDir as a relative directory (to prefix).
• $relativePreferencesDir: $preferencesDir as a relative directory (to prefix).
• $relativeSbinDir: $sbinDir as a relative directory (to prefix).
• $relativeSettingsDir: $settingsDir as a relative directory (to prefix).
• $relativeSharedStateDir: $sharedStateDir as a relative directory (to prefix).
• $sbinDir: Absolute directory for super-user binaries. On Haiku, this is the same as $binDir.
• $settingsDir: Absolute directory for settings files.
• $sharedStateDir: Absolute directory for shared state files. On Haiku, this is the same as $localStateDir, i.e. it corresponds to the var-hierarchy.
• $sourceDir: Absolute path to the source directory of the build. This contains the files implementing the actual build process (configure, Makefile, ...).
• $targetArchitecture: The Haiku architecture HaikuPorter for which the current port is being build (e.g. x86_gcc2). Unless the ports tree in use is the one related to cross-builds, this is the same as $buildArchitecture.

When the ports tree for cross-builds is active, there are some more variables available:

• buildMachineTriple: The machine-triple for the machine HaikuPorter is running on (e.g. i586-pc-haiku_gcc2)
• buildMachineTripleAsName: The machine-triple for the machine HaikuPorter is running on as a name usable in requires/provides definitions (e.g. i586_pc_haiku_gcc2)
• crossSysrootDir: [Only for cross builds]: ="/boot/cross-sysroot/x86_gcc2"
• targetMachineTriple: The machine-triple for the machine this port is being built for (e.g. i586-pc-haiku_gcc2)
• targetMachineTripleAsName: The machine-triple for the machine this port is being built for as a name usable in requires/provides definitions (e.g. i586_pc_haiku_gcc2)

TODO

it would be useful to be able to specify some kind of prefix for all of the above variables, as otherwise there can be namespace clashes with the actual build process used by specific port (git is an example).

Shell Functions

The following shell functions are defined by HaikuPorter to make them available to the build recipe script:

fixDevelopLibDirReferences()

usage

fixDevelopLibDirReferences <file> ...

purpose

Replaces instances of $libDir in the given files with $developLibDir. This is useful for fixing a <portname>-config script with respect to where it locates development libraries. Usually, those believe libraries to be found in $libDir, but on Haiku, those live in $developLibDir.

fixPkgconfig()

usage

fixPkgConfig

purpose

Moves pkgconfig-subfolder from $libDir to $developLibDir and adjusts all files in there to reference libraries via $prefix/develop/lib and headers via $prefix/develop/headers.

packageEntries()

usage

packageEntries <packageSuffix> <entry> ...

purpose

Moves the given entries to the packaging directory for the sibling package specified by packageSuffix. In effect, the given entries will not be put into the main package, but they will be put into the sibling package instead.

params

• packageSuffix; The suffix of the sibling package where the entries should be moved to.
• entry; Specifies a single entry to be moved from the main package to the sibling package. The given entry paths can be absolute or relative to $prefix.

prepareInstalledDevelLib()

usage

prepareInstalledDevelLib <libBaseName> [ <soPattern> [ <pattern> ] ]

purpose

Moves all libraries matching a given base name from $prefix/lib to $prefix/develop/lib and creates symlinks as required.

params

• libBaseName: The base name of the library, e.g. "libfoo".
• soPattern: The glob pattern to be used to enumerate the shared library entries. Is appended to $libDir/${libBaseName}' to form the complete pattern. Defaults to ".so*".
• pattern: The glob pattern to be used to enumerate all library entries. Is appended to $libDir/${libBaseName} to form the complete pattern. Defaults to ".*".

prepareInstalledDevelLibs()

usage

prepareInstalledDevelLibs <libBaseName> ...

purpose

Invokes prepareInstalledDevelLib() for all given library base names (using the defaults for soPattern and pattern).

runConfigure()

usage

runConfigure [ --omit-dirs <dirsToOmit> ] <configure> <argsToConfigure> ...

purpose

Helper function to invoke a configure script with the correct directory arguments.

params

• configure: The configure program to be called.
• dirsToOmit: Space-separated list of directory arguments not to be passed to configure, e.g. "docDir manDir" (as a single argument!).
• argsToConfigure: The additional arguments passed to configure.

Output

Environment Variables

...TODO...

Shell Functions

The following shell functions will be invoked by HaikuPorter to execute the corresponding build stage. If a recipe doesn't provide a definition for one of these functions, the corresponding build stage will be empty, i.e. nothing will happen.

PATCH()

purpose

Apply algorithmic patches to the port's sources. Usually, sources are patched by providing a patchset, but sometimes it is just more convenient to apply the patches programatically, which can be done in this function.

generic example

PATCH()
{
	find . -name '*.py' -exec sed -i -e 's|/usr/bin/env|/bin/env|g' {} \;
}

BUILD()

purpose

Execute the build stage for the current port. For a port based on autotools, this usually involves invocation of configure and make.

generic example

BUILD()
{
	libtoolize --force --copy --install
	runConfigure ./configure
	make $jobArgs
}

INSTALL()

purpose

Collect the build results into one or more subfolders of the /packaging directory (one for each resulting package).

generic example

INSTALL()
{
	make install
	strip $binDir/*
}

TEST()

purpose

Run any tests on the build results.

generic example

TEST()
{
	make check
}

Example

...TODO...