Handling Requirements

BEWARE!

this page doesn't reflect the current status quo of HaikuPorter - there's some more work to do such that HaikuPorter and the recipes actually follow the description given below ...

In order to avoid any built packages to unexpectedly depend on software that happens to be installed on the build host (i.e. you Haiku installation), HaikuPorter runs the build commands in a chroot()-ed environment. When HaikuPorter creates the chroot, it populates it with only the packages that are needed by the shell scriptlets that are executing the different build phases. Anything else that is required for building or running the port has to be declared explicitly in the build recipe of each port.

Requires

Runtime requirements of a port must be added to the REQUIRES variable in the build recipe (for ports generating more than a single package, different sets of declarations shoulde be given in the REQUIRES variable of the respective package.

Those declarations can refer to commands that will be executed by the packaged software (but which aren't part of the port) and/or to shared runtime libraries implementing some functionality that the packaged software needs.

Build Requires

Build-time requirements of a port are all the external entities that are used by the build process and have an effect at runtime.

Most notably, each library used by the port's build process represents a build requires, as the code in those libraries is being used at runtime. Accordingly, any port using external libraries must declare build requires for those development libraries (no matter if shared or static).

The build requires of a port must be added to the BUILD_REQUIRES variable in the build recipe (again, potentially involving one variable per package).

Each shared development library that a port references in BUILD_REQUIRES should have a corresponding reference to the respective shared runtime library in REQUIRES, as a library that a port has been linked to is extremely likely to be necessary at runtime. This conceptual separation of development and runtime libraries is imortant, since those are indeed being provided by separate packages (usually the base and the devel package). The fact that the development library is just a symlink to the runtime library is merely an implementation detail.

Note

Sometimes, commands used during the build can represent a build requires, too. This would be the case if the build process analyzes the commandline interface of a specific program (say git) and then adjusts itself to invoke git at runtime using the information gathered during the build. In the given example, git would have to be added to REQUIRES, too, of course.

Build Prerequires

Build-time requirements of a port that are just needed during the build, but which do not have any effect at runtime must be added to the BUILD_PREREQUIRES variable in the build recipe.

Those declarations usually refer to commands that are needed by the port's build system (which most of the time includes invocations of 'make' and 'make install'). Typical examples of this are actual buildtools like gcc, binutils, autoconf and make, but very often additional commands like sed and/or grep, too.

Requires Specification Syntax

Individual entries in any of the requires specifications need to adhere to the following syntax (please see  The .PackageInfo for more details:

required_entity		::= [type ":"] entity_name [ version_operator version_ref ]
type                    ::= "cmd" | "devel" | "lib" | ...
version_operator	::= "<" | "<=" | "==" | "!=" | ">=" | ">"

Note

There are other types than the ones given above, but those are of no concern here.

Requiring a command

A requires on a commands can be declared using cmd:<command> (e.g. 'cmd:sed' or 'cmd:git >= 1.7').

Any dashes contained in the name of the command need to be replaced with underscores, so in order to require command 'i586-pc-haiku-gcc', one has to add it as 'cmd:i586_pc_haiku_gcc'.

Requiring a runtime library

A requires on a runtime library can be declared using lib:<library-basename> (e.g. 'lib:libz' or 'lib:libpng >= 1.4'). The basename of the library is everything until the first dot - yes, this means that there's no difference between a shared or static library.

As with commands, any dashes contained in the name of the library need to be replaced with underscores.

Requiring a development library

A requires on a development library can be declared using devel:<library-basename> (e.g. 'devel:libz' or 'devel:libpng >= 1.4').

Again, any dashes contained in the name of the library need to be replaced with underscores.

Requiring a package

Any required entity without a type specification (e.g. 'openssl') is representing a package. Direct package requires are not a good idea, as such a requires relies on the contents of the package to stay the same at all times. However, packages are getting renamed or split, which would mean that such a requires declaration becomes broken.

Declared and Actual Requires

Before HaikuPorter collects the build results of a port into packages, the set of declared runtime requires (REQUIRES) is being replaced by the actual versions used at time of the build.

An example

For a port that declares a requires 'openssl >= 1.0' and has actually used openssl-1.0.0j during the build, HaikuPorter will inject the requires 'openssl >= 1.0.0j'. The reason for this is that any version of openssl less than 1.0.0j may not work properly, as ports are expected to be forward-compatible (newer versions can be used instead of older ones), but not necessarily the other way around.

Be Explicit!

In general, it is advisable to be as explicit as possible with the requires declarations. If, for instance, a port requires three different development libraries which all are provided by the same other port, it is still mandatory to declare all three of them individually as build requires. If that weren't done, a simple package split in the required port would break the port using those libraries.

There's a direct connection between explicitness of the requires declarations in build recipes and robustness of the whole packaging repository, so be explict!