| | 1 | = Build Recipes = |
| | 2 | |
| | 3 | == Overview == |
| | 4 | |
| | 5 | 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. |
| | 6 | |
| | 7 | There's a two-way "communication" (using environment variables and shell functions) between !HaikuPorter and the build recipe script: |
| | 8 | |
| | 9 | Input (!HaikuPorter -> Build Recipe Script):: |
| | 10 | 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. |
| | 11 | 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). |
| | 12 | Output (Build Recipe Script -> !HaikuPorter):: |
| | 13 | Several environment variables need to be initialized by the recipe script in order to pass information about build details back to !HaikuPorter. |
| | 14 | 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}}}). |
| | 15 | |
| | 16 | == Input == |
| | 17 | |
| | 18 | === Environment Variables === |
| | 19 | |
| | 20 | 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. |
| | 21 | |
| | 22 | 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. |
| | 23 | |
| | 24 | Here's a list of all input environment variables: |
| | 25 | |
| | 26 | TODO:: |
| | 27 | it would be useful to be able to specify some kind of prefix for those variables, as otherwise there can be namespace clashes with the actual build process used by specific port (git is an example). |
| | 28 | |
| | 29 | - '''addOnsDir:''' The absolute directory for add-ons. |
| | 30 | - '''appsDir:''' The absolute directory for applications. |
| | 31 | - '''binDir:''' The absolute directory for binaries. |
| | 32 | - '''buildArchitecture:''' The Haiku architecture !HaikuPorter is running on (e.g. `x86_gcc2`). |
| | 33 | - '''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). |
| | 34 | - '''configureDirVariables:''' A string containing a space separated list of names of all directory variable names. |
| | 35 | - '''dataDir:''' The absolute directory for data. |
| | 36 | - '''dataRootDir:''' The absolute base directory for data. On Haiku, this is the same as `dataDir`. |
| | 37 | - '''developDir:''' The absolute path to the directory underneath of which all development-related files should be put. |
| | 38 | - '''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`. |
| | 39 | - '''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`. |
| | 40 | - '''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`. |
| | 41 | - '''documentationDir:''' The absolute base directory underneath of which all documentation should be put. This is not a port-specific directory. |
| | 42 | - '''fontsDir:''' The absolute directory for fonts. |
| | 43 | - '''haikuVersion:''' The version of Haiku for which the port is being built. |
| | 44 | - '''includeDir:''' The absolute directory for header files |
| | 45 | - '''infoDir:''' The absolute directory for documentation in `info`-format (which is frowned upon by Haiku ports) |
| | 46 | - '''isCrossRepository:''' Is `true` if the ports tree being used is the one dealing with cross-building the bootstrap packages. |
| | 47 | - '''jobArgs:''' If !HaikuPorter has been invoked with `--jobs=<num>`, this contains the job-number specification applicable to make (i.e. `-j<num>`) |
| | 48 | - '''jobs:''' The number of build jobs to run concurrently (can be set with `haikuporter --jobs=<num>` |
| | 49 | - '''libDir:''' The absolute directory for shared libraries to be used at runtime (i.e. by Haiku's runtime loader) |
| | 50 | - '''libExecDir:''' The absolute directory for executables that a port may invoke internally. On Haiku, this is the same as `libDir`. |
| | 51 | - '''localStateDir:''' The absolute directory for putting files created at runtime. This corresponds to the `var`-hierarchy. |
| | 52 | - '''manDir:''' The absolute directory for man-pages. For each man section, a subdir exists underneath this directory. |
| | 53 | - '''oldIncludeDir:''' Another name of the absolute directory for putting header files. |
| | 54 | - '''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). |
| | 55 | - '''portDir:''' The absolute directory (on the build host!) where the files of the current port (patches, license, recipes) can be accessed. |
| | 56 | - '''portFullVersion:''' Full version of the current port, including revision (e.g. `2.14-1`) |
| | 57 | - '''portName:''' Name of the current port. |
| | 58 | - '''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. |
| | 59 | - '''portRevision:''' The revision of the current port (e.g. `1`). |
| | 60 | - '''portRevisionedName:''' The name of the current port, extended by version and revision (e.g. `grep-2.14-1`) |
| | 61 | - '''portVersion:''' The version of the current port (e.g. `2.14`). |
| | 62 | - '''portVersionedName:''' The name of the current port, extended by version (e.g. `grep-2.14`). |
| | 63 | - '''preferencesDir:''' The absolute directory for preflets. |
| | 64 | - '''prefix:''' The absolute base directory of the port (i.e. the installation location). |
| | 65 | - '''relativeAddOnsDir:''' `addOnsDir` as a relative directory (to `prefix`). |
| | 66 | - '''relativeAppsDir:''' `appsDir` as a relative directory (to `prefix`). |
| | 67 | - '''relativeBinDir:''' `binDir` as a relative directory (to `prefix`). |
| | 68 | - '''relativeDataDir:''' `dataDir` as a relative directory (to `prefix`). |
| | 69 | - '''relativeDataRootDir:''' `dataRootDir` as a relative directory (to `prefix`). |
| | 70 | - '''relativeDevelopDir:''' `developDir` as a relative directory (to `prefix`). |
| | 71 | - '''relativeDevelopDocDir:''' `developDocDir` as a relative directory (to `prefix`). |
| | 72 | - '''relativeDevelopLibDir:''' `developLibDir` as a relative directory (to `prefix`). |
| | 73 | - '''relativeDocDir:''' `docDir` as a relative directory (to `prefix`). |
| | 74 | - '''relativeDocumentationDir:''' `documentationDir` as a relative directory (to `prefix`). |
| | 75 | - '''relativeFontsDir:''' `fontsDir` as a relative directory (to `prefix`). |
| | 76 | - '''relativeIncludeDir:''' `includeDir` as a relative directory (to `prefix`). |
| | 77 | - '''relativeInfoDir:''' `infoDir` as a relative directory (to `prefix`). |
| | 78 | - '''relativeLibDir:''' `libDir` as a relative directory (to `prefix`). |
| | 79 | - '''relativeLibExecDir:''' `libExecDir` as a relative directory (to `prefix`). |
| | 80 | - '''relativeLocalStateDir:''' `localStateDir` as a relative directory (to `prefix`). |
| | 81 | - '''relativeManDir:''' `manDir` as a relative directory (to `prefix`). |
| | 82 | - '''relativeOldIncludeDir:''' `oldIncludeDir` as a relative directory (to `prefix`). |
| | 83 | - '''relativePreferencesDir:''' `preferencesDir` as a relative directory (to `prefix`). |
| | 84 | - '''relativeSbinDir:''' `sbinDir` as a relative directory (to `prefix`). |
| | 85 | - '''relativeSettingsDir:''' `settingsDir` as a relative directory (to `prefix`). |
| | 86 | - '''relativeSharedStateDir:''' `sharedStateDir` as a relative directory (to `prefix`). |
| | 87 | - '''sbinDir:''' Absolute directory for super-user binaries. On Haiku, this is the same as `binDir`. |
| | 88 | - '''settingsDir:''' Absolute directory for settings files. |
| | 89 | - '''sharedStateDir:''' Absolute directory for shared state files. On Haiku, this is the same as `localStateDir`, i.e. it corresponds to the `var`-hierarchy. |
| | 90 | - '''sourceDir:''' Absolute path to the source directory of the build. This contains the files implementing the actual build process (`configure`, `Makefile`, ...). |
| | 91 | - '''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`. |
| | 92 | |
| | 93 | When the ports tree for cross-builds is active, there are some more variables available: |
| | 94 | - '''buildMachineTriple:''' The machine-triple for the machine !HaikuPorter is running on (e.g. `i586-pc-haiku_gcc2`) |
| | 95 | - '''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`) |
| | 96 | - '''crossSysrootDir:''' [Only for cross builds]: ="/boot/cross-sysroot/x86_gcc2" |
| | 97 | - '''targetMachineTriple:''' The machine-triple for the machine this port is being built for (e.g. `i586-pc-haiku_gcc2`) |
| | 98 | - '''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`) |
| | 99 | |
| | 100 | === Shell Functions === |
| | 101 | |
| | 102 | The following shell functions are defined by !HaikuPorter to make them available to the build recipe script: |
| | 103 | |
| | 104 | ...TODO... |
| | 105 | |
| | 106 | == Output == |
| | 107 | |
| | 108 | === Environment Variables === |
| | 109 | |
| | 110 | ...TODO... |
| | 111 | |
| | 112 | === Shell Functions === |
| | 113 | |
| | 114 | ...TODO... |
| | 115 | |
| | 116 | == Example == |
| | 117 | |
| | 118 | ...TODO... |
