Changes between Version 1 and Version 2 of HaikuPorterForPM/HandlingRequirements

Timestamp:

06/13/13 09:58:25 (2 years ago)

Author:

zooey

Comment:

--

HaikuPorterForPM/HandlingRequirements

@@ -1 +1 @@
 = Handling Requirements =
 
-... TODO ...
+ '''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 [https://dev.haiku-os.org/wiki/PackageManagement/BuildingPackages#The.PackageInfo 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!