= 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...