Converting .bep Files to .recipe

This is a short guide to help you with the conversion of .bep files to the new .recipe format. The formats themselves aren't that different from each other, but the .recipe files contain a lot more meta information and require additional install actions.

1. Recipe files are shell scripts. The BUILD, INSTALL,... actions become regular shell functions.
2. Add a SUMMARY variable with a one-line description and make the DESCRIPTION more expressive. Often the website of the respective project sports a longer description. Don't be afraid to copy multiple paragraphs, if you think they contain information helpful to the user seeing the package in the package manager. If the description becomes more than a few lines in the recipe, move the DESCRIPTION variable to the very end of the file, so one doesn't always have to scroll past it.
3. For aesthetical reasons move the LICENSE and COPYRIGHT variables to the first block (they are often at the end of the .bep file).
4. Set REVISION to "1". It must be incremented whenever the recipe file or the associated patch(es) change (except for whitespace/comment changes).
5. Replace STATUS_HAIKU by ARCHITECTURES. It lists all packaging architectures for which the status is known. A value of "x86_gcc2 ?x86 !ppc" means stable on x86 gcc 2, untested/unstable on x86 gcc 4, broken/unsupported on ppc.
6. If the port requires one or more patches, specify them via the PATCHES variable. ATM haikuporter also picks up patches automatically when they are named accordingly, but this functionality will eventually be removed. Simple diffs as well as git mailbox format patches are supported (the latter need the file name extension ".patchset").
7. Remove DEPENDS and add PROVIDES, REQUIRES, BUILD_REQUIRES, BUILD_PREREQUIRES instead. E.g.:

   PROVIDES="
   	apr_util = $portVersion compat >= 1
   	lib:libaprutil_1 = 0.4.1 compat >= 0
   	"
   REQUIRES="
   	haiku >= $haikuVersion
   	lib:libapr_1
   	lib:libexpat
   	lib:libiconv
   	"
   BUILD_REQUIRES="
   	haiku_devel >= $haikuVersion
   	devel:libapr_1 >= 0.4.6
   	devel:libexpat >= 1.5.2
   	devel:libiconv
   	"
   BUILD_PREREQUIRES="
   	cmd:aclocal
   	cmd:autoconf
   	cmd:autoheader
   	cmd:gcc
   	cmd:ld
   	cmd:libtoolize
   	cmd:make
   	"
   

   PROVIDES must at least contain one entry for the package itself. It also must declare all commands exposed in the "bin" directory (with "cmd:" prefix), all libraries in "lib" (with "lib:" prefix) -- as version the library version should be used, which may differ from the package version -- and entries for the development files belonging to a library (with "devel:" prefix). Any "-" in a name must be replaced by a "_". Each PROVIDES entry can optionally have a compatibility version ("compat >= ..."), specifying how far backward compatible the entity is. This is most relevant for libraries, in which case it usually is the soname version. REQUIRES specifies the requirements to be fulfilled when the package is installed. It contains an entry for the Haiku version (unless the package contains just a data files that don't have any Haiku dependency) plus one for each library, command, or other external entity the package uses. BUILD_REQUIRES and BUILD_PREREQUIRES are similar to REQUIRES, but specify the dependencies needed for building the port. The difference between the two can be seen from a cross-compilation POV: The BUILD_REQUIRES are for the target architecture/platform, the BUILD_PREREQUIRES need to work on the build platform. So the former usually refers to development libraries, while the latter refers to commands.
8. Add a SOURCE_DIR variable, if necessary. It specifies the name (or relative path) of the directory which contains the sources when extracted from the source archive. Usually the archives contain a directory with a name like "foo-1.0.7". If that's the case and it matches the versioned port name (name of your recipe file minus the ".recipe"), then SOURCE_DIR can be omitted as that's the default. Otherwise define it as necessary. Try to keep it as generic as possible (e.g. "FooSource-$portVersion" rather than "FooSource-1.0.7") to save some work when a recipe for the next version is created. When the specified source directory consists of multiple path components, haikuporter will move the contents of that directory to the first level and remove the rest. For check-outs from repositories the first path component names the directory the files of the check-out will end up in. In either case before invoking the BUILD or INSTALL function haikuporter will already cd into the source directory, so that doesn't need to be done explicitly anymore.
9. A PATCH function can be defined. It is invoked after the patches have been applied. If your BUILD actions contained any commands that modified the sources manually (typically some sed invocation) before running the build, that should be moved to the PATCH function instead.
10. In the BUILD function:
    • If possible (for virtually all autotools based build systems), don't specify the install prefix and other directories manually. Rather use the runConfigure helper function provided by haikuporter:

      runConfigure ./configure <other configure args> ...
      

      It invokes the specified configure script with the full set of directory declaration arguments.
    • Use make $jobArgs, if possible, to allow building with multiple jobs. If the build system doesn't support it, add a comment to that effect.
11. The INSTALL function is supposed to prepare the contents of all packages to be built for the port. For each an empty directory has been created, which needs to be populated. Due to using a chroot environment and packagefs magic, the prefix passed to the configure script (also in the $prefix variable) is automatically redirected to the directory for the main package of the port. So in most cases a regular make install should dump all install files there. Usually some post-processing is needed, so that certain files end up in the right directories or are patched, if necessary. After that the packageEntries function can be used to move files to other packages. Here are some typical actions:
    • prepareInstalledDevelLibs libz: This moves static libraries, libtool files, and certain symlinks for libz from "lib" to "develop/lib". Multiple libraries can be specified at once.
    • fixPkgconfig: This moves the "lib/pkgconfig" directory to "develop/lib" and adjusts the contained files.
    • fixDevelopLibDirReferences $binDir/apu-1-config: Replace absolute paths to the "lib" directory by absolute paths to "develop/lib" in the specified file "bin/apu-1-config".
    • Remove files and directories that are not needed.
    • To move files to another package:

      packageEntries devel \
      	$binDir \
      	$developDir
      

      This moves the complete "bin" and "develop" directories to the <port>_devel package. Individual files can be specified as well. Intermediate directories are created automatically where needed.
12. Declare for each additional package at least its PROVIDES and usually also REQUIRES:

    PROVIDES_devel="
    	apr_util_devel = portVersion compat >= 1
    	cmd:apu_1_config = $portVersion compat >= 1
    	devel:libaprutil_1 = 0.4.1 compat >= 0
    	"
    REQUIRES_devel="
    	apr_util == $portVersion base
    	"
    

    The variables simply get suffixed with the suffix of the package, e.g. in this case with "_devel" for the apr_util_devel package. SUMMARY and DESCRIPTION for the additional package can be set as well. By default they are inherited from the main declarations and for known package types (like "devel", "doc", "debuginfo") a respective note (e.g. "(development files)") is added to the package's SUMMARY.