[PR PATCH] Manual.md: revamp explain_depends section.

[PR PATCH] Manual.md: revamp explain_depends section.

[ericonr]

[-- Attachment #1: Type: text/plain, Size: 387 bytes --]

There is a new pull request by ericonr against master on the void-packages repository

https://github.com/ericonr/void-packages dbusr
https://github.com/void-linux/void-packages/pull/23746

Manual.md: revamp explain_depends section.
Add useful examples of checkdepends that might not be obvious.

A patch file from https://github.com/void-linux/void-packages/pull/23746.patch is attached

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-dbusr-23746.patch --]
[-- Type: text/x-diff, Size: 4882 bytes --]

From dec679df08184bd5e486f95d40f4030eef9416aa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
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..61eeccb1f75 100644
--- a/Manual.md
+++ b/Manual.md
@@ -708,36 +708,49 @@ Examples:
 	```
 
 <a id="explain_depends"></a>
-#### 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`: enables running `dbus-run-session <test-command>` to provide a D-Bus
+  session for applications that need it
+- `git`: some test suites run the `git` command
+
+Finally, 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.
 
 <a id="repositories"></a>
 #### Repositories

Re: [PR PATCH] [Updated] Manual.md: revamp explain_depends section.

[ericonr]

[-- Attachment #1: Type: text/plain, Size: 392 bytes --]

There is an updated pull request by ericonr against master on the void-packages repository

https://github.com/ericonr/void-packages dbusr
https://github.com/void-linux/void-packages/pull/23746

Manual.md: revamp explain_depends section.
Add useful examples of checkdepends that might not be obvious.

A patch file from https://github.com/void-linux/void-packages/pull/23746.patch is attached

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-dbusr-23746.patch --]
[-- Type: text/x-diff, Size: 4891 bytes --]

From d784aa8d8771891c04d83d2edb8a2886b37f0b16 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
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..326fd53a583 100644
--- a/Manual.md
+++ b/Manual.md
@@ -708,36 +708,49 @@ Examples:
 	```
 
 <a id="explain_depends"></a>
-#### 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 <test-command>` to provide
+  a D-Bus session for applications that need it
+- `git`: some test suites run the `git` command
+
+Finally, 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.
 
 <a id="repositories"></a>
 #### Repositories

Re: [PR PATCH] [Updated] Manual.md: revamp explain_depends section.

[ericonr]

[-- Attachment #1: Type: text/plain, Size: 392 bytes --]

There is an updated pull request by ericonr against master on the void-packages repository

https://github.com/ericonr/void-packages dbusr
https://github.com/void-linux/void-packages/pull/23746

Manual.md: revamp explain_depends section.
Add useful examples of checkdepends that might not be obvious.

A patch file from https://github.com/void-linux/void-packages/pull/23746.patch is attached

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-dbusr-23746.patch --]
[-- Type: text/x-diff, Size: 4890 bytes --]

From 76a7602304ae98ee34d2975afb547ccc6e3b6e2c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
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:
 	```
 
 <a id="explain_depends"></a>
-#### 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 <test-command>` 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.
 
 <a id="repositories"></a>
 #### Repositories

Re: [PR REVIEW] Manual.md: revamp explain_depends section.

[Piraty]

[-- Attachment #1: Type: text/plain, Size: 158 bytes --]

New review comment by Piraty on void-packages repository

https://github.com/void-linux/void-packages/pull/23746#discussion_r471106768

Comment:
remove comma

Re: [PR REVIEW] Manual.md: revamp explain_depends section.

[Piraty]

[-- Attachment #1: Type: text/plain, Size: 241 bytes --]

New review comment by Piraty on void-packages repository

https://github.com/void-linux/void-packages/pull/23746#discussion_r471108142

Comment:
`<...> Perl and python modules <...> that use dlopen instead of dynamic linking.` keep it short

Re: [PR REVIEW] Manual.md: revamp explain_depends section.

[Piraty]

[-- Attachment #1: Type: text/plain, Size: 228 bytes --]

New review comment by Piraty on void-packages repository

https://github.com/void-linux/void-packages/pull/23746#discussion_r471107321

Comment:
proposal: mention that some binaries required for host may hide in -devel packages

Re: [PR REVIEW] Manual.md: revamp explain_depends section.

[Piraty]

[-- Attachment #1: Type: text/plain, Size: 337 bytes --]

New review comment by Piraty on void-packages repository

https://github.com/void-linux/void-packages/pull/23746#discussion_r471107741

Comment:
1. too much nesting in second sentence. (around `and`)
1. checkdepends are treated like hostdepends
1. you could mention the `XBPS_CHECK_PKGS` switch / `-Q` flag up front of the paragraph

Re: [PR REVIEW] Manual.md: revamp explain_depends section.

[Piraty]

[-- Attachment #1: Type: text/plain, Size: 276 bytes --]

New review comment by Piraty on void-packages repository

https://github.com/void-linux/void-packages/pull/23746#discussion_r471107404

Comment:
proposal: `Typically, it will contain mostly `-devel` packages.` don't explain stuff for hostmakedepends in makedepends' paragraph

Re: [PR REVIEW] Manual.md: revamp explain_depends section.

[Piraty]

[-- Attachment #1: Type: text/plain, Size: 428 bytes --]

New review comment by Piraty on void-packages repository

https://github.com/void-linux/void-packages/pull/23746#discussion_r471107922

Comment:
I don't favor listing low frequency checkdepends here (like dbus, git) and usually the do_check stage tells what it requires. If you insist on giving examples (in-text, not list) i'd go for stuff like gtest, cmocka and pytest, but I don't really see the need to give examples at all

Re: [PR REVIEW] Manual.md: revamp explain_depends section.

[Piraty]

[-- Attachment #1: Type: text/plain, Size: 237 bytes --]

New review comment by Piraty on void-packages repository

https://github.com/void-linux/void-packages/pull/23746#discussion_r471108318

Comment:
The point here is probably: "don't bloat the dependency lists". 
the old phrase was ok too

Re: [PR REVIEW] Manual.md: revamp explain_depends section.

[Piraty]

[-- Attachment #1: Type: text/plain, Size: 356 bytes --]

New review comment by Piraty on void-packages repository

https://github.com/void-linux/void-packages/pull/23746#discussion_r471107113

Comment:
proposal: 
```
These packages should be listed in `makedepends`.
The packages to be installed into the masterdir will match the target architecture (regardless of the architecture of the build machine)`
```

Re: [PR REVIEW] Manual.md: revamp explain_depends section.

[ericonr]

[-- Attachment #1: Type: text/plain, Size: 189 bytes --]

New review comment by ericonr on void-packages repository

https://github.com/void-linux/void-packages/pull/23746#discussion_r471124814

Comment:
Tried something else, but similar. Thanks.

Re: [PR REVIEW] Manual.md: revamp explain_depends section.

[ericonr]

[-- Attachment #1: Type: text/plain, Size: 166 bytes --]

New review comment by ericonr on void-packages repository

https://github.com/void-linux/void-packages/pull/23746#discussion_r471125383

Comment:
I think I fixed it.

Re: [PR REVIEW] Manual.md: revamp explain_depends section.

[ericonr]

[-- Attachment #1: Type: text/plain, Size: 459 bytes --]

New review comment by ericonr on void-packages repository

https://github.com/void-linux/void-packages/pull/23746#discussion_r471125754

Comment:
`dbus` is necessary for running tests which require D-Bus, and it isn't obvious that `dbus-run-session` can be called from inside the `do_check` stage, because the tests only complain about a lack of D-Bus. Mostly want to avoid people having to cargo cult and instead be able to read the Manual to figure it out.

Re: [PR PATCH] [Updated] Manual.md: revamp explain_depends section.

[ericonr]

[-- Attachment #1: Type: text/plain, Size: 392 bytes --]

There is an updated pull request by ericonr against master on the void-packages repository

https://github.com/ericonr/void-packages dbusr
https://github.com/void-linux/void-packages/pull/23746

Manual.md: revamp explain_depends section.
Add useful examples of checkdepends that might not be obvious.

A patch file from https://github.com/void-linux/void-packages/pull/23746.patch is attached

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-dbusr-23746.patch --]
[-- Type: text/x-diff, Size: 4734 bytes --]

From 9120f73cdde473f09003e2e0b92e95d8d56499c5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
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 | 69 +++++++++++++++++++++++++++++++------------------------
 1 file changed, 39 insertions(+), 30 deletions(-)

diff --git a/Manual.md b/Manual.md
index 5b49dc5ddd4..f2433ae937c 100644
--- a/Manual.md
+++ b/Manual.md
@@ -708,36 +708,45 @@ Examples:
 	```
 
 <a id="explain_depends"></a>
-#### 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. It is possible that some of the programs
+necessary to build a project are located in `-devel` packages.
+
+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
+will match the target architecture, regardless of the architecture of the build
+machine. Typically, `makedepends` will contain mainly `-devel` packages.
+
+Furthermore, if `XBPS_CHECK_PKGS` is set or the `-Q` option is passed to
+`xbps-src`, the target package might require specific dependencies or libraries
+that are linked into its test binaries to run its test suite. These dependencies
+should be listed in `checkdepends` and will be installed as if they were part of
+`hostmakedepends`. 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 <test-command>` 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 Perl and Python
+modules and other programs that use `dlopen(3)` instead of dynamically linking.
+
+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.
 
 <a id="repositories"></a>
 #### Repositories

Re: [PR PATCH] [Merged]: Manual.md: revamp explain_depends section.

[the-maldridge]

[-- Attachment #1: Type: text/plain, Size: 238 bytes --]

There's a merged pull request on the void-packages repository

Manual.md: revamp explain_depends section.
https://github.com/void-linux/void-packages/pull/23746

Description:
Add useful examples of checkdepends that might not be obvious.