From a46b6131ee01f03c0a3bdcd5277efe1df6f529ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotr=20W=C3=B3jcik?= Date: Mon, 26 Jun 2023 20:01:53 +0200 Subject: [PATCH 1/6] Manual.md: move section on automatically detected depends --- Manual.md | 91 +++++++++++++++++++++++++++---------------------------- 1 file changed, 44 insertions(+), 47 deletions(-) diff --git a/Manual.md b/Manual.md index 1670863cbe54..da2572e911a0 100644 --- a/Manual.md +++ b/Manual.md @@ -27,7 +27,6 @@ packages for XBPS, the `Void Linux` native packaging system. * [Build helper scripts](#build_helper) * [Functions](#functions) * [Build options](#build_options) - * [Runtime dependencies](#deps_runtime) * [INSTALL and REMOVE files](#install_remove_files) * [INSTALL.msg and REMOVE.msg files](#install_remove_files_msg) * [Creating system accounts/groups at runtime](#runtime_account_creation) @@ -787,11 +786,55 @@ should be listed in `checkdepends` and will be installed as if they were part of 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. +Dependencies for ELF objects are detected automatically by `xbps-src`, hence runtime +dependencies must not be specified in templates via `$depends` with the following exceptions: + +- ELF objects using dlopen(3). +- non ELF objects, i.e perl/python/ruby/etc modules. +- Overriding the minimal version specified in the `shlibs` file. + +The runtime dependencies for ELF objects are detected by checking which SONAMEs +they require and then the SONAMEs are mapped to a binary package name with a minimal +required version. The `shlibs` file in the `void-packages/common` directory +sets up the ` >=` mappings. + +For example the `foo-1.0_1` package provides the `libfoo.so.1` SONAME and +software requiring this library will link to `libfoo`; the resulting binary +package will have a run-time dependency to `foo>=1.0_1` package as specified in +`common/shlibs`: + +``` +# common/shlibs +... +libfoo.so.1 foo-1.0_1 +... +``` + +- The first field specifies the SONAME. +- The second field specified the package name and minimal version required. +- A third optional field (usually set to `ignore`) can be used to skip checks in soname bumps. + +Dependencies declared via `${depends}` are not installed to the master directory, rather are +only checked if they exist as binary packages, and are built automatically by `xbps-src` if +the specified version is not in the local repository. + +As a special case, `virtual` dependencies may be specified as runtime dependencies in the +`${depends}` template variable. Several different packages can provide common functionality by +declaring a virtual name and version in the `${provides}` template variable (e.g., +`provides="vpkg-0.1_1"`). Packages that rely on the common functionality without concern for the +specific provider can declare a dependency on the virtual package name with the prefix `virtual?` +(e.g., `depends="virtual?vpkg-0.1_1"`). When a package is built by `xbps-src`, providers for any +virtual packages will be confirmed to exist and will be built if necessary. A map from virtual +packages to their default providers is defined in `etc/defaults.virtual`. Individual mappings can be +overridden by local preferences in `etc/virtual`. Comments in `etc/defaults.virtual` provide more +information on this map. + 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. @@ -1214,52 +1257,6 @@ Example: `XBPS_PKG_OPTIONS_xorg_server=opt`. The list of supported package build options and its description is defined in the `common/options.description` file. - -#### Runtime dependencies - -Dependencies for ELF objects are detected automatically by `xbps-src`, hence runtime -dependencies must not be specified in templates via `$depends` with the following exceptions: - -- ELF objects using dlopen(3). -- non ELF objects, i.e perl/python/ruby/etc modules. -- Overriding the minimal version specified in the `shlibs` file. - -The runtime dependencies for ELF objects are detected by checking which SONAMEs -they require and then the SONAMEs are mapped to a binary package name with a minimal -required version. The `shlibs` file in the `void-packages/common` directory -sets up the ` >=` mappings. - -For example the `foo-1.0_1` package provides the `libfoo.so.1` SONAME and -software requiring this library will link to `libfoo`; the resulting binary -package will have a run-time dependency to `foo>=1.0_1` package as specified in -`common/shlibs`: - -``` -# common/shlibs -... -libfoo.so.1 foo-1.0_1 -... -``` - -- The first field specifies the SONAME. -- The second field specified the package name and minimal version required. -- A third optional field (usually set to `ignore`) can be used to skip checks in soname bumps. - -Dependencies declared via `${depends}` are not installed to the master directory, rather are -only checked if they exist as binary packages, and are built automatically by `xbps-src` if -the specified version is not in the local repository. - -As a special case, `virtual` dependencies may be specified as runtime dependencies in the -`${depends}` template variable. Several different packages can provide common functionality by -declaring a virtual name and version in the `${provides}` template variable (e.g., -`provides="vpkg-0.1_1"`). Packages that rely on the common functionality without concern for the -specific provider can declare a dependency on the virtual package name with the prefix `virtual?` -(e.g., `depends="virtual?vpkg-0.1_1"`). When a package is built by `xbps-src`, providers for any -virtual packages will be confirmed to exist and will be built if necessary. A map from virtual -packages to their default providers is defined in `etc/defaults.virtual`. Individual mappings can be -overridden by local preferences in `etc/virtual`. Comments in `etc/defaults.virtual` provide more -information on this map. - ### INSTALL and REMOVE files From 6342afe7c2d66169c524137cb83a9f1b3c800498 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotr=20W=C3=B3jcik?= Date: Mon, 26 Jun 2023 20:13:46 +0200 Subject: [PATCH 2/6] Manual.md: reword section on automatically detected depends --- Manual.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Manual.md b/Manual.md index da2572e911a0..cfb9e46aad1c 100644 --- a/Manual.md +++ b/Manual.md @@ -789,15 +789,16 @@ should be listed in `checkdepends` and will be installed as if they were part of 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. +XBPS, should be listed in `depends`. -Dependencies for ELF objects are detected automatically by `xbps-src`, hence runtime -dependencies must not be specified in templates via `$depends` with the following exceptions: +Libraries linked by ELF objects are detected automatically by `xbps-src`, hence they +must not be specified in templates via `$depends`. Variable should list: +- executables called as separate processes. - ELF objects using dlopen(3). - non ELF objects, i.e perl/python/ruby/etc modules. -- Overriding the minimal version specified in the `shlibs` file. +- data files. +- overriding the minimal version specified in the `shlibs` file. The runtime dependencies for ELF objects are detected by checking which SONAMEs they require and then the SONAMEs are mapped to a binary package name with a minimal From 005171b74937f2f18b954dddd963a8889498796f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotr=20W=C3=B3jcik?= Date: Mon, 26 Jun 2023 20:25:19 +0200 Subject: [PATCH 3/6] Manual.md: adjust sections hierarchy --- Manual.md | 49 +++++++++++++++++++++++++++---------------------- 1 file changed, 27 insertions(+), 22 deletions(-) diff --git a/Manual.md b/Manual.md index cfb9e46aad1c..3676003bc6f9 100644 --- a/Manual.md +++ b/Manual.md @@ -5,7 +5,8 @@ packages for XBPS, the `Void Linux` native packaging system. *Table of Contents* -* [Introduction](#Introduction) +* The XBPS source packages manual + * [Introduction](#Introduction) * [Package build phases](#buildphase) * [Package naming conventions](#namingconventions) * [Libraries](#libs) @@ -33,13 +34,14 @@ packages for XBPS, the `Void Linux` native packaging system. * [Writing runit services](#writing_runit_services) * [32bit packages](#32bit_pkgs) * [Subpackages](#pkgs_sub) - * [Development packages](#pkgs_development) - * [Data packages](#pkgs_data) - * [Documentation packages](#pkgs_documentation) - * [Python packages](#pkgs_python) - * [Go packages](#pkgs_go) - * [Haskell packages](#pkgs_haskell) - * [Font packages](#pkgs_font) + * [Some package classes](#pkgs_classes) + * [Development packages](#pkgs_development) + * [Data packages](#pkgs_data) + * [Documentation packages](#pkgs_documentation) + * [Python packages](#pkgs_python) + * [Go packages](#pkgs_go) + * [Haskell packages](#pkgs_haskell) + * [Font packages](#pkgs_font) * [Renaming a package](#pkg_rename) * [Removing a package](#pkg_remove) * [XBPS Triggers](#xbps_triggers) @@ -72,10 +74,10 @@ packages for XBPS, the `Void Linux` native packaging system. * [Void specific documentation](#documentation) * [Notes](#notes) * [Contributing via git](#contributing) -* [Help](#help) + * [Help](#help) -## Introduction +### Introduction The `void-packages` repository contains all the recipes to download, compile and build binary packages for Void Linux. @@ -841,10 +843,10 @@ not a particular package is present in `makedepends` or `hostmakedepends`, that package shouldn't be added as a build time dependency. -#### Repositories +### Repositories -##### Repositories defined by Branch +#### Repositories defined by Branch The global repository takes the name of the current branch, except if the name of the branch is master. Then the resulting @@ -852,7 +854,7 @@ repository will be at the global scope. The usage scenario is that the user can update multiple packages in a second branch without polluting his local repository. -##### Package defined Repositories +#### Package defined Repositories The second way to define a repository is by setting the `repository` variable in a template. This way the maintainer can define repositories for a specific @@ -1474,8 +1476,11 @@ destdir (`$DESTDIR`) to the `subpackage` destdir (`$PKGDESTDIR`). Subpackages are processed always in alphabetical order; To force a custom order, the `subpackages` variable can be declared with the wanted order. + +### Some package classes + -### Development packages +#### Development packages A development package, commonly generated as a subpackage, shall only contain files required for development, that is, headers, static libraries, shared @@ -1505,7 +1510,7 @@ following subset of files from the main package: * Vala bindings `usr/share/vala` -### Data packages +#### Data packages Another common subpackage type is the `-data` subpackage. This subpackage type used to split architecture independent, big(ger) or huge amounts @@ -1517,7 +1522,7 @@ The main package must then have `depends="${pkgname}-data-${version}_${revision} possibly in addition to other, non-automatic depends. -### Documentation packages +#### Documentation packages Packages intended for user interaction do not always unconditionally require their documentation part. A user who does not want to e.g. develop @@ -1532,7 +1537,7 @@ amounts of documentation for no reason. Thus the size of the documentation part be your guidance to decide whether or not to split off a `-doc` subpackage. -### Python packages +#### Python packages Python packages should be built with the `python{,2,3}-module` build style, if possible. This sets some environment variables required to allow cross compilation. Support to allow @@ -1593,7 +1598,7 @@ Also, a set of useful variables are defined to use in the templates: python versions. -### Go packages +#### Go packages Go packages should be built with the `go` build style, if possible. The `go` build style takes care of downloading Go dependencies and @@ -1627,7 +1632,7 @@ The path to the package's source inside `$GOPATH` is available as `$GOSRCPATH`. -### Haskell packages +#### Haskell packages We build Haskell package using `stack` from [Stackage](http://www.stackage.org/), generally the LTS versions. @@ -1645,7 +1650,7 @@ The following variables influence how Haskell packages are built: you can add your `--flag ...` parameters there. -### Font packages +#### Font packages Font packages are very straightforward to write, they are always set with the following variables: @@ -1902,7 +1907,7 @@ If it is running under another architecture it tries to use the host's `install- utility. -### initramfs-regenerate +#### initramfs-regenerate The initramfs-regenerate trigger will trigger the regeneration of all kernel initramfs images after package installation or removal. The trigger must be @@ -2151,7 +2156,7 @@ to pull in new changes: $ git pull --rebase upstream master -## Help +### Help If after reading this `manual` you still need some kind of help, please join us at `#xbps` via IRC at `irc.libera.chat`. From 1a4c6baf065cefc82fccf265eb8006a0371efd1b Mon Sep 17 00:00:00 2001 From: Chocimier Date: Mon, 26 Jun 2023 22:08:52 +0200 Subject: [PATCH 4/6] Update Manual.md Co-authored-by: Mohammed Anas --- Manual.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Manual.md b/Manual.md index 3676003bc6f9..a1e31677a2a1 100644 --- a/Manual.md +++ b/Manual.md @@ -804,8 +804,8 @@ must not be specified in templates via `$depends`. Variable should list: The runtime dependencies for ELF objects are detected by checking which SONAMEs they require and then the SONAMEs are mapped to a binary package name with a minimal -required version. The `shlibs` file in the `void-packages/common` directory -sets up the ` >=` mappings. +required version. The `common/shlibs` file sets up the +` >=` mappings. For example the `foo-1.0_1` package provides the `libfoo.so.1` SONAME and software requiring this library will link to `libfoo`; the resulting binary From 73daf7a55f2dc0c4a8f27ca68a5fc179b38c594e Mon Sep 17 00:00:00 2001 From: Chocimier Date: Mon, 26 Jun 2023 22:09:12 +0200 Subject: [PATCH 5/6] Update Manual.md Co-authored-by: Mohammed Anas --- Manual.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Manual.md b/Manual.md index a1e31677a2a1..706ab93a09fc 100644 --- a/Manual.md +++ b/Manual.md @@ -794,7 +794,7 @@ is unusable. These dependencies, when they aren't detected automatically by XBPS, should be listed in `depends`. Libraries linked by ELF objects are detected automatically by `xbps-src`, hence they -must not be specified in templates via `$depends`. Variable should list: +must not be specified in templates via `depends`. Variable should list: - executables called as separate processes. - ELF objects using dlopen(3). From df7250922c286613b4ce1968f63f1f5baa974bd0 Mon Sep 17 00:00:00 2001 From: Chocimier Date: Mon, 26 Jun 2023 22:09:20 +0200 Subject: [PATCH 6/6] Update Manual.md Co-authored-by: Mohammed Anas --- Manual.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Manual.md b/Manual.md index 706ab93a09fc..823df890fd0b 100644 --- a/Manual.md +++ b/Manual.md @@ -798,7 +798,7 @@ must not be specified in templates via `depends`. Variable should list: - executables called as separate processes. - ELF objects using dlopen(3). -- non ELF objects, i.e perl/python/ruby/etc modules. +- non-ELF objects, i.e perl/python/ruby/etc modules. - data files. - overriding the minimal version specified in the `shlibs` file.