From 1594c3e48ef10512fa4dfc399343fa67c4f32f40 Mon Sep 17 00:00:00 2001
From: Juan RP <xtraeme@gmail.com>
Date: Tue, 31 Dec 2013 07:42:58 +0100
Subject: [PATCH] doc/manual.txt: multiple improvements and tweaks.
---
doc/manual.txt | 418 +++++++++++++++++++++++++++----------------------
1 file changed, 229 insertions(+), 189 deletions(-)
diff --git a/doc/manual.txt b/doc/manual.txt
index a8af37c0fd7..347a4661f93 100644
--- a/doc/manual.txt
+++ b/doc/manual.txt
@@ -1,3 +1,5 @@
+// vim: set syntax=asciidoc:
+
The XBPS source packages manual
===============================
Juan RP <xtraeme@gmail.com>
@@ -8,7 +10,7 @@ Juan RP <xtraeme@gmail.com>
:website: http://www.voidlinux.eu
This article contains an exhaustive manual of how to create new source
-packages for XBPS, the package manager of the *Void Linux distribution*.
+packages for XBPS, the `Void Linux` native packaging system.
Introduction
------------
@@ -80,25 +82,25 @@ Package build phases
Building a package consist of the following phases:
*fetch*::
- This phase downloads required sources for a `source package`, as defined by
- the `distfiles` variable or `do_fetch()` function.
+ This phase downloads required sources for a `source package`, as defined by
+the `distfiles` variable or `do_fetch()` function.
*extract*::
- This phase extracts the `distfiles` files into `$wrksrc` or executes the `do_extract()`
- function, which is the directory to be used to compile the `source package`.
+ This phase extracts the `distfiles` files into `$wrksrc` or executes the `do_extract()`
+function, which is the directory to be used to compile the `source package`.
*configure*::
- This phase executes the `configuration` of a `source package`, i.e `GNU configure scripts`.
+ This phase executes the `configuration` of a `source package`, i.e `GNU configure scripts`.
*build*::
- This phase compiles/prepares the `source files` via `make` or any other compatible method.
+ This phase compiles/prepares the `source files` via `make` or any other compatible method.
*install-destdir*::
- This phase installs the `package files` into a `fake destdir`, via `make install` or
- any other compatible method.
+ This phase installs the `package files` into a `fake destdir`, via `make install` or
+any other compatible method.
*build-pkg*::
- This phase builds the `binary packages` with files stored in the `package destdir`.
+ This phase builds the `binary packages` with files stored in the `package destdir`.
`xbps-src` supports running just the specified phase, and if it ran
successfully, the phase will be skipped later (unless its work directory
@@ -111,28 +113,28 @@ The following functions are defined by `xbps-src` and can be used on any templat
*vinstall()*::
`vinstall <file> <mode> <targetdir> [<name>]`
- Installs `file` with the specified `mode` into `targetdir` in `$DESTDIR`
- (if called from a `source section`) or `$PKGDESTDIR` (if called from a `package section`).
- The optional 4th argument can be used to change the `file name`.
+Installs `file` with the specified `mode` into `targetdir` in `$DESTDIR`
+(if called from a `source section`) or `$PKGDESTDIR` (if called from a `package section`).
+The optional 4th argument can be used to change the `file name`.
*vcopy()*::
`vcopy <pattern> <targetdir>`
- Copies resursively all files in `pattern` to `targetdir` on `$DESTDIR`
- (if called from a `source section`) or `$PKGDESTDIR` (if called from a `package section`).
+Copies resursively all files in `pattern` to `targetdir` on `$DESTDIR`
+(if called from a `source section`) or `$PKGDESTDIR` (if called from a `package section`).
*vmove()*::
`vmove <pattern>`
- Moves `pattern` to the specified directory in `$DESTDIR`
- (if called from a `source section`) or `$PKGDESTDIR` (if called from a `package section`).
+Moves `pattern` to the specified directory in `$DESTDIR`
+(if called from a `source section`) or `$PKGDESTDIR` (if called from a `package section`).
*vmkdir()*::
`vmkdir <directory> [<mode>]`
- Creates a directory in `$DESTDIR` (if called from a `source section`) or
- $PKGDESTDIR` (if called from a `package section`). The 2nd optional argument
- sets the mode of the directory.
+Creates a directory in `$DESTDIR` (if called from a `source section`) or
+`$PKGDESTDIR` (if called from a `package section`). The 2nd optional argument
+sets the mode of the directory.
NOTE: shell wildcards must be properly quoted.
@@ -141,37 +143,37 @@ Global variables
The following variables are defined by `xbps-src` and can be used on any template:
*makejobs*::
- Set to `-jX` if `XBPS_MAKEJOBS` is defined, to allow parallel jobs with `GNU make`.
+ Set to `-jX` if `XBPS_MAKEJOBS` is defined, to allow parallel jobs with `GNU make`.
*sourcepkg*::
- Set to the to main package name, can be used to match the main package
- rather than additional binary package names.
+ Set to the to main package name, can be used to match the main package
+rather than additional binary package names.
*CHROOT_READY*::
- True if the target chroot (masterdir) is ready for chroot builds.
+ True if the target chroot (masterdir) is ready for chroot builds.
*CROSS_BUILD*::
- True if `xbps-src` is cross compiling a package.
+ True if `xbps-src` is cross compiling a package.
*DESTDIR*::
- Full path to the fake destdir used by the `source section`, set to
- `${XBPS_MASTERDIR}/destdir/${sourcepkg}-${version}`.
+ Full path to the fake destdir used by the `source section`, set to
+`${XBPS_MASTERDIR}/destdir/${sourcepkg}-${version}`.
*PKGDESTDIR*::
- Full path to the fake destdir used by the `pkg_install()` function in the
- `package section`, set to `${XBPS_MASTERDIR}/destdir/pkg-${pkgname}-${version}`.
+ Full path to the fake destdir used by the `pkg_install()` function in the
+`package section`, set to `${XBPS_MASTERDIR}/destdir/pkg-${pkgname}-${version}`.
*XBPS_MACHINE*::
- The machine architecture as returned by `uname -m`.
+ The machine architecture as returned by `uname -m`.
*XBPS_SRCDISTDIR*::
- Full path to where the `source distfiles` are stored, i.e `$XBPS_HOSTDIR/sources`.
+ Full path to where the `source distfiles` are stored, i.e `$XBPS_HOSTDIR/sources`.
*XBPS_SRCPKGDIR*::
- Full path to the `srcpkgs` directory.
+ Full path to the `srcpkgs` directory.
*XBPS_TARGET_MACHINE*::
- The target machine architecture when cross compiling a package.
+ The target machine architecture when cross compiling a package.
Source section
@@ -181,150 +183,151 @@ Mandatory variables
The list of mandatory variables in the `source section`:
*homepage*::
- A string pointing to the `upstream` homepage.
+ A string pointing to the `upstream` homepage.
*license*::
- A string matching any license file available in `/usr/share/licenses`.
- Multiple licenses should be separated by commas, i.e `GPL-3, LGPL-2.1`.
+ A string matching any license file available in `/usr/share/licenses`.
+Multiple licenses should be separated by commas, i.e `GPL-3, LGPL-2.1`.
*maintainer*::
- A string in the form of `name <user@domain>`.
+ A string in the form of `name <user@domain>`.
*pkgname*::
- A string with the package name, matching `srcpkgs/<pkgname>`.
+ A string with the package name, matching `srcpkgs/<pkgname>`.
*revision*::
- A number that must be set to 1 when the `source package` is created, or
- updated to a new `upstream version`. This should only be increased when
- the generated `binary packages` have been modified.
+ A number that must be set to 1 when the `source package` is created, or
+updated to a new `upstream version`. This should only be increased when
+the generated `binary packages` have been modified.
*short_desc*::
- A string with a brief description for this package. Max 72 chars.
+ A string with a brief description for this package. Max 72 chars.
*version*::
- A string with the package version. Must not contain dashes and at least
- one digit is required.
+ A string with the package version. Must not contain dashes and at least
+one digit is required.
Optional variables
~~~~~~~~~~~~~~~~~~
*hostmakedepends*::
- The list of `host` dependencies required to build the package. Dependencies
- can be specified with the following version comparators: `<`, `>`, `<=`, `>=`
- or `foo-1.0_1` to match an exact version. If version comparator is not
- defined (just a package name), the version comparator is automatically set to `>=0`.
- Example `hostmakedepends="foo blah<1.0"`.
+ The list of `host` dependencies required to build the package. Dependencies
+can be specified with the following version comparators: `<`, `>`, `<=`, `>=`
+or `foo-1.0_1` to match an exact version. If version comparator is not
+defined (just a package name), the version comparator is automatically set to `>=0`.
+Example `hostmakedepends="foo blah<1.0"`.
*makedepends*::
- The list of `target` dependencies required to build the package. Dependencies
- can be specified with the following version comparators: `<`, `>`, `<=`, `>=`
- or `foo-1.0_1` to match an exact version. If version comparator is not
- defined (just a package name), the version comparator is automatically set to `>=0`.
- Example `makedepends="foo blah>=1.0"`.
+ The list of `target` dependencies required to build the package. Dependencies
+can be specified with the following version comparators: `<`, `>`, `<=`, `>=`
+or `foo-1.0_1` to match an exact version. If version comparator is not
+defined (just a package name), the version comparator is automatically set to `>=0`.
+Example `makedepends="foo blah>=1.0"`.
*bootstrap*::
- If enabled the source package is considered to be part of the `bootstrap`
- process and required to be able to build packages in the chroot. Only a
- small number of packages must set this property.
+ If enabled the source package is considered to be part of the `bootstrap`
+process and required to be able to build packages in the chroot. Only a
+small number of packages must set this property.
*distfiles*::
- The full URL to the `upstream` source distribution files. Multiple files
- can be separated by blanks. The files must end in `.tar.lzma`, `.tar.xz`,
- `.txz`, `.tar.bz2`, `.tbz`, `.tar.gz`, `.tgz`, `.gz`, `.bz2`, `.tar` or
- `.zip`. Example `distfiles="http://foo.org/foo-1.0.tar.gz"`
+ The full URL to the `upstream` source distribution files. Multiple files
+can be separated by blanks. The files must end in `.tar.lzma`, `.tar.xz`,
+`.txz`, `.tar.bz2`, `.tbz`, `.tar.gz`, `.tgz`, `.gz`, `.bz2`, `.tar` or
+`.zip`. Example `distfiles="http://foo.org/foo-1.0.tar.gz"`
*checksum*::
- The `sha256` digests matching `${distfiles}`. Multiple files can be
- separated by blanks. Please note that the order must be the same than
- was used in `${distfiles}`. Example `checksum="kkas00xjkjas"`
+ The `sha256` digests matching `${distfiles}`. Multiple files can be
+separated by blanks. Please note that the order must be the same than
+was used in `${distfiles}`. Example `checksum="kkas00xjkjas"`
*long_desc*::
- A long description of the main package. Max 80 chars per line and must
- not contain the following characters: `&`, `<`, `>`.
+ A long description of the main package. Max 80 chars per line and must
+not contain the following characters: `&`, `<`, `>`.
*wrksrc*::
- The directory name where the package sources are extracted, by default
- set to `${pkgname}-${version}`.
+ The directory name where the package sources are extracted, by default
+set to `${pkgname}-${version}`.
*build_wrksrc*::
- A directory relative to `${wrksrc}` that will be used when building the package.
+ A directory relative to `${wrksrc}` that will be used when building the package.
*create_wrksrc*::
- Enable it to create the `${wrksrc}` directory. Required if a package
- contains multiple `distfiles`.
+ Enable it to create the `${wrksrc}` directory. Required if a package
+contains multiple `distfiles`.
*only_for_archs*::
- This expects a separated list of architectures where the package can be
- built matching `uname -m` output. Example `only_for_archs="x86_64 armv6l"`
+ This expects a separated list of architectures where the package can be
+built matching `uname -m` output. Example `only_for_archs="x86_64 armv6l"`
*build_style*::
- This specifies the `build method` for a package. Read below to know more
- about the available package `build methods`. If `build_style` is not set,
- the package must define at least a `do_install()` function, and optionally
- more build phases as such `do_configure()`, `do_build()`, etc.
+ This specifies the `build method` for a package. Read below to know more
+about the available package `build methods`. If `build_style` is not set,
+the package must define at least a `do_install()` function, and optionally
+ more build phases as such `do_configure()`, `do_build()`, etc.
*create_srcdir*::
- This creates a directory in `${XBPS_SRCDISTDIR}` as such `${pkgname}-${version}`
- to store the package sources at the `extract` phase. Required in packages that
- use unversioned ${distfiles}`.
+ This creates a directory in `${XBPS_SRCDISTDIR}` as such `${pkgname}-${version}`
+to store the package sources at the `extract` phase. Required in packages that
+use unversioned ${distfiles}`.
*configure_script*::
- The name of the `configure` script to execute at the `configure` phase if
- `${build_style}` is set to `configure` or `gnu-configure` build methods.
- By default set to `./configure`.
+ The name of the `configure` script to execute at the `configure` phase if
+`${build_style}` is set to `configure` or `gnu-configure` build methods.
+By default set to `./configure`.
*configure_args*::
- The arguments to be passed in to the `configure` script if `${build_style}`
- is set to `configure` or `gnu-configure` build methods. By default, prefix
- must be set to `/usr`. In `gnu-configure` packages, some options are already
- set by default: `--prefix=/usr --sysconfdir=/etc --infodir=/usr/share/info --mandir=/usr/share/man --localstatedir=/var`.
+ The arguments to be passed in to the `configure` script if `${build_style}`
+is set to `configure` or `gnu-configure` build methods. By default, prefix
+must be set to `/usr`. In `gnu-configure` packages, some options are already
+set by default: `--prefix=/usr --sysconfdir=/etc --infodir=/usr/share/info --mandir=/usr/share/man --localstatedir=/var`.
*make_cmd*::
- The executable to run at the `build` phase if `${build_style}` is set to
- `configure`, `gnu-configure` or `gnu-makefile` build methods.
- By default set to `make`.
+ The executable to run at the `build` phase if `${build_style}` is set to
+`configure`, `gnu-configure` or `gnu-makefile` build methods.
+By default set to `make`.
*make_build_args*::
- The arguments to be passed in to `${make_cmd}` at the build phase if
- `${build_style}` is set to `configure`, `gnu-configure` or `gnu_makefile`
- build methods. Unset by default.
+ The arguments to be passed in to `${make_cmd}` at the build phase if
+`${build_style}` is set to `configure`, `gnu-configure` or `gnu_makefile`
+build methods. Unset by default.
*make_install_args*::
- The arguments to be passed in to `${make_cmd}` at the `install-destdir`
- phase if `${build_style}` is set to `configure`, `gnu-configure` or
- `gnu_makefile` build methods. Unset by default.
+ The arguments to be passed in to `${make_cmd}` at the `install-destdir`
+phase if `${build_style}` is set to `configure`, `gnu-configure` or
+`gnu_makefile` build methods. By default set to
+`PREFIX=/usr DESTDIR=${DESTDIR}`.
*make_build_target*::
- The target to be passed in to `${make_cmd}` at the build phase if
- `${build_style}` is set to `configure`, `gnu-configure` or `gnu_makefile`
- build methods. Unset by default (`all` target).
+ The target to be passed in to `${make_cmd}` at the build phase if
+`${build_style}` is set to `configure`, `gnu-configure` or `gnu_makefile`
+build methods. Unset by default (`all` target).
*make_install_target*::
- The target to be passed in to `${make_cmd}` at the `install-destdir` phase
- if `${build_style}` is set to `configure`, `gnu-configure` or `gnu_makefile`
- build methods. By default set to `DESTDIR=${DESTDIR} install`.
+ The target to be passed in to `${make_cmd}` at the `install-destdir` phase
+if `${build_style}` is set to `configure`, `gnu-configure` or `gnu_makefile`
+build methods. By default set to `install`.
*patch_args*::
- The arguments to be passed in to the `patch(1)` command when applying
- patches to the package sources after `do_extract()`. Patches are stored in
- `srcpkgs/<pkgname>/patches` and must be in `-p0` format. By default set to `-Np0`.
+ The arguments to be passed in to the `patch(1)` command when applying
+patches to the package sources after `do_extract()`. Patches are stored in
+`srcpkgs/<pkgname>/patches` and must be in `-p0` format. By default set to `-Np0`.
*disable_parallel_build*::
- If set the package won't be built in parallel and `XBPS_MAKEJOBS` has no effect.
+ If set the package won't be built in parallel and `XBPS_MAKEJOBS` has no effect.
*keep_libtool_archives*::
- If enabled the `GNU Libtool` archives won't be removed. By default those
- files are always removed automatically.
+ If enabled the `GNU Libtool` archives won't be removed. By default those
+files are always removed automatically.
*skip_extraction*::
- A list of filenames that should not be extracted in the `extract` phase.
- This must match the basename of any url defined in `${distfiles}`.
- Example `skip_extraction="foo-${version}.tar.gz"`.
+ A list of filenames that should not be extracted in the `extract` phase.
+This must match the basename of any url defined in `${distfiles}`.
+Example `skip_extraction="foo-${version}.tar.gz"`.
*force_debug_pkgs*::
- If enabled binary packages with debugging symbols will be generated
- even if `XBPS_DEBUG_PKGS` is disabled in `xbps-src.conf` or in the
- `command line arguments`.
+ If enabled binary packages with debugging symbols will be generated
+even if `XBPS_DEBUG_PKGS` is disabled in `xbps-src.conf` or in the
+`command line arguments`.
build style scripts
~~~~~~~~~~~~~~~~~~~
@@ -336,42 +339,48 @@ to execute a `build_style` script must be defined via `hostmakedepends`.
The current list of available `build_style` scripts is the following:
*cmake*::
- For packages that use the CMake build system, configuration arguments
- can be passed in via `configure_args`.
+ For packages that use the CMake build system, configuration arguments
+can be passed in via `configure_args`.
*configure*::
- For packages that use non-GNU configure scripts, at least `--prefix=/usr`
- should be passed in via `configure_args`.
+ For packages that use non-GNU configure scripts, at least `--prefix=/usr`
+should be passed in via `configure_args`.
*gnu-configure*::
- For packages that use GNU configure scripts, additional configuration
- arguments can be passed in via `configure_args`.
+ For packages that use GNU configure scripts, additional configuration
+arguments can be passed in via `configure_args`.
*gnu-makefile*::
- For packages that use GNU make, build arguments can be passed in via
- `make_build_args` and install arguments via `make_install_args`. The build
- target can be overriden via `make_build_target` and the install target
+ For packages that use GNU make, build arguments can be passed in via
+`make_build_args` and install arguments via `make_install_args`. The build
+target can be overriden via `make_build_target` and the install target
+via `make_install_target`.
*meta*::
- For `meta-packages`, i.e packages that only install local files or simply
- depend on additional packages.
+ For `meta-packages`, i.e packages that only install local files or simply
+depend on additional packages. This build style does not install
+dependencies to the root directory, and only checks if a binary package is
+available in repositories.
*perl-ModuleBuild*::
- For packages that use the Perl
- http://search.cpan.org/~leont/Module-Build-0.4202/lib/Module/Build.pm[Module::Build] method.
+ For packages that use the Perl
+http://search.cpan.org/~leont/Module-Build-0.4202/lib/Module/Build.pm[Module::Build] method.
*perl*::
- For packages that use the Perl
- http://perldoc.perl.org/ExtUtils/MakeMaker.html[ExtUtils::MakeMaker] build method.
+ For packages that use the Perl
+http://perldoc.perl.org/ExtUtils/MakeMaker.html[ExtUtils::MakeMaker] build method.
*python-module*::
- For packages that use the Python module build method (setup.py).
+ For packages that use the Python module build method (setup.py).
*waf3*::
- For packages that use the Python3 `waf` build method with python3.
+ For packages that use the Python3 `waf` build method with python3.
*waf*::
- For packages that use the Python `waf` method with python2.
+ For packages that use the Python `waf` method with python2.
+
+NOTE: if `build_style` is not set, the template must (at least) define a
+`do_install()` function and optionally more phases via `do_xxx()` functions.
Functions
~~~~~~~~~
@@ -379,80 +388,47 @@ The following functions can be defined to change the behavior of how the
package is downloaded, compiled and installed.
*do_fetch()*::
- if defined and `distfiles` is not set, use it to fetch the required sources.
+ if defined and `distfiles` is not set, use it to fetch the required sources.
*do_extract()*::
- if defined and `distfiles` is not set, use it to extract the required sources.
+ if defined and `distfiles` is not set, use it to extract the required sources.
*post_extract()*::
- Actions to execute after `do_extract()`.
+ Actions to execute after `do_extract()`.
*pre_configure()*::
- Actions to execute after `post_extract()`.
+ Actions to execute after `post_extract()`.
*do_configure()*::
- Actions to execute to configure the package; `${configure_args}` should
- still be passed in if it's a GNU configure script.
+ Actions to execute to configure the package; `${configure_args}` should
+still be passed in if it's a GNU configure script.
*post_configure()*::
- Actions to execute after `do_configure()`.
+ Actions to execute after `do_configure()`.
*pre_build()*::
- Actions to execute after `post_configure()`.
+ Actions to execute after `post_configure()`.
*do_build()*::
- Actions to execute to build the package.
+ Actions to execute to build the package.
*post_build()*::
- Actions to execute after `do_build()`.
+ Actions to execute after `do_build()`.
*pre_install()*::
- Actions to execute after `post_build()`.
+ Actions to execute after `post_build()`.
*do_install()*::
- Actions to execute to install the packages files into the `fake destdir`.
+ Actions to execute to install the packages files into the `fake destdir`.
*post_install()*::
- Actions to execute after `do_install()`.
+ Actions to execute after `do_install()`.
NOTE: A function defined in a template has preference over the same function
defined by a `build_style` script.
-Run-time dependencies
-~~~~~~~~~~~~~~~~~~~~~
-
-Dependencies for ELF executables or shared libraries are detected
-automatically by `xbps-src`, hence run-time dependencies must not be specified
-in the *package sections* with the following exceptions:
-
-- ELF binaries using dlopen(3).
-- non ELF objects, i.e perl/python/ruby/etc modules.
-- Overriding the minimal version specified in the `shlibs` file.
-
-The run-time dependencies for ELF binaries are detected by checking which SONAMEs
-use and then the SONAMEs are mapped to a binary package name with a minimal
-required version. The `shlibs` file in the `xbps-packages/common` directory
-sets up the `SONAME pkgname>=version` 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 specifies the architecture (rarely used).
-
Build options
-~~~~~~~~~~~~~
-
+-------------
Some packages might be built with different build options to enable/disable
additional features; `xbps-src` allows you to do this with some simple tweaks
to the `template` file.
@@ -460,14 +436,14 @@ to the `template` file.
The following variables may be set to allow package build options:
*build_options*::
- Sets the build options supported by the source package.
+ Sets the build options supported by the source package.
*build_options_default*::
- Sets the default build options to be used by the source package.
+ Sets the default build options to be used by the source package.
*desc_option_<option>*::
- Sets the description for the build option `option`. This must match the
- keyword set in *build_options*.
+ Sets the description for the build option `option`. This must match the
+keyword set in *build_options*.
After defining those required variables, you can check for the
`build_option_<option>` variable to know if it has been set and adapt the source
@@ -533,9 +509,69 @@ The build options can also be shown for binary packages via `xbps-query(8)`:
$ xbps-query -R --property=build-options foo
--------------------------------------------
-Contributing via git
-~~~~~~~~~~~~~~~~~~~~
+Package section
+---------------
+Mandatory functions
+~~~~~~~~~~~~~~~~~~~
+A `package section` needs at least one mandatory function matching the
+`$pkgname` of the `source section`: `<pkgname>_package()`. Multiple binary
+packages with the same template can be created by adding additional
+`<pkg>_package()` functions.
+Those `<pkg>_package()` functions are run in alphabetical order, with the
+exception of the `<pkgname>_package()` function, which is always the last one.
+
+Optional variables
+~~~~~~~~~~~~~~~~~~
+*conf_files*::
+A list of configuration files the binary package owns; this expects full
+paths, and multiple entries can be separated by blanks, i.e:
+`conf_files="/etc/foo.conf /etc/foo2.conf"`.
+
+*noarch*::
+ If set, the binary package is not architecture specific and can be shared
+by all supported architectures.
+
+*nonfree*::
+ If set, the binary package will be put into the *non free* repository.
+
+*nostrip*::
+ If set, the ELF binaries with debugging symbols won't be stripped. By
+default all binaries are stripped.
+
+Run-time dependencies
+---------------------
+Dependencies for ELF executables or shared libraries are detected
+automatically by `xbps-src`, hence run-time dependencies must not be specified
+in the *package sections* with the following exceptions:
+
+- ELF binaries using dlopen(3).
+- non ELF objects, i.e perl/python/ruby/etc modules.
+- Overriding the minimal version specified in the `shlibs` file.
+
+The run-time dependencies for ELF binaries are detected by checking which SONAMEs
+use and then the SONAMEs are mapped to a binary package name with a minimal
+required version. The `shlibs` file in the `xbps-packages/common` directory
+sets up the `SONAME pkgname>=version` 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 specifies the architecture (rarely used).
+
+Contributing via git
+--------------------
You can fork the `xbps-packages` git repository on github and then set up
a remote to pull in new changes:
@@ -556,8 +592,12 @@ for more information.
For commit messages please use the following rules:
-- If you've imported a new package use `New package: <pkgver>`.
-- If you've updated a package use `<pkgname>: updated to <version>`.
-- If you've removed a package use `<pkgname>: removed ...`.
-
+- If you've imported a new package use `"New package: <pkgver>"`.
+- If you've updated a package use `"<pkgname>: updated to <version>"`.
+- If you've removed a package use `"<pkgname>: removed ..."`.
+- If you've modified a package use `"<pkgname>: ..."`.
+Help
+----
+If after reading this `manual` you still need some kind of help, please join
+us at `#xbps` via IRC at `irc.freenode.net`.