From 76a7602304ae98ee34d2975afb547ccc6e3b6e2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Rolim?= Date: Wed, 22 Jul 2020 16:36:59 -0300 Subject: [PATCH] Manual.md: revamp explain_depends section. Add useful examples of checkdepends that might not be obvious. --- Manual.md | 73 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 43 insertions(+), 30 deletions(-) diff --git a/Manual.md b/Manual.md index 5b49dc5ddd4..b04930cdf38 100644 --- a/Manual.md +++ b/Manual.md @@ -708,36 +708,49 @@ Examples: ``` -#### About the many types of `depends` variable. - -So far we have listed four types of `depends`, there are `hostmakedepends`, -`makedepends`, `checkdepends` and plain old `depends`.To understand the difference -between them, understand this: Void Linux cross compiles for many arches. -Sometimes in a build process, certain programs must be run, for example `yacc`, or the -compiler itself for a C program. Those programs get put in `hostmakedepends`. -When the build runs, those will be installed on the host to help the build -complete. - -Then there are those things for which a package either links against or -includes header files. These are `makedepends`, and regardless of the -architecture of the build machine, the architecture of the target machine must -be used. Typically the `makedepends` will be the only one of the three types of -`depends` to include `-devel` packages, and typically only `-devel` packages. - -Then there are those things that are required for a package to run its testsuite -`dejagnu` or libraries it must link to when building test binaries like `cmocka`. -These are `checkdepends` and they are installed like they are part of `makedepends`. -the difference is that they are only installed when `XBPS_CHECK_PKGS` is defined. - -The final variable, `depends`, is for those things the package needs at -runtime and without which is unusable, and that xbps can't auto-detect. -These are not all the packages the package needs at runtime, but only those -that are not linked against. This variable is most useful for non-compiled -programs. - -Finally, as a general rule, if something compiles the exact same way whether or -not you add a particular package to `makedepends` or `hostmakedepends`, it -shouldn't be added. +#### About the many types of `depends` variables + +So far, we have listed four types of `depends` variables: `hostmakedepends`, +`makedepends`, `checkdepends` and `depends`. These different kinds of variables +are necessary because `xbps-src` supports cross compilation and to avoid +installing unecessary packages in the build environment. + +During a build process, there are programs that must be _run_ on the host, such +as `yacc` or the C compiler. The packages that contain these programs should be +listed in `hostmakedepends`, and will be installed on the host when building the +target package. Some of these packages are dependencies of the `base-chroot` +package, and don't need to be listed. + +The target package can also depend on other packages for libraries to link +against or header files. These packages should be listed in `makedepends`, and +regardless of the architecture of the build machine, the version that will be +installed is the one from the target machine. Usually, `makedepends` is the only +one to include `-devel` packages - except for cases when the `-devel` packages +include tools necessary for building the target package - and typically only +`-devel` packages. + +Furthermore, the target package might require specific dependencies in order to +run its test suite or libraries that are linked into its test binaries. These +dependencies should be listed in `checkdepends`, and, if `XBPS_CHECK_PKGS` is +set or the `-Q` option is passed to `xbps-src`, will be installed as if they +were part of `makedepends`. Some dependencies that can be included in +`checkdepends` are: + +- `dejagnu`: used for some GNU projects +- `cmocka-devel`: linked into test binaries +- `dbus`: makes it possible to run `dbus-run-session ` to provide + a D-Bus session for applications that need it +- `git`: some test suites run the `git` command + +Lastly, a package may require certain dependencies at runtime, without which it +is unusable. These dependencies, when they aren't detected automatically by +XBPS, should be listed in `depends`. This is mostly relevant for non-compiled +programs, such as Perl and Python ones, and programs that use `dlopen(3)` +instead of dynamically linking against the libraries on which they depend. + +Finally, as a general rule, if a package is built the exact same way whether or +not a particular package is present in `makedepends` or `hostmakedepends`, that +package shouldn't be added as a build time dependency. #### Repositories