diff --git a/Manual.md b/Manual.md new file mode 100644 index 00000000000..245c3c97bd0 --- /dev/null +++ b/Manual.md @@ -0,0 +1,578 @@ +# The XBPS source packages manual + +This article contains an exhaustive manual of how to create new source +packages for XBPS, the `Void Linux` native packaging system. + +## Introduction + +The `xbps-packages` repository contains all `source` packages that are the +recipes to download, compile and build binary packages for `Void`. +Those `source` package files are called `templates`. + +The `template files` are `GNU bash` shell scripts that must define some required/optional +`variables` and `functions` that are processed by `xbps-src` (the package builder) +to generate the resulting binary packages. + +A simple `template` example is as follows: + +``` +# Template file for 'foo' + +pkgname="foo" +version="1.0" +revision=1 +build_style=gnu-configure +short_desc="A short description max 72 chars" +maintainer="name " +license="GPL-3" +homepage="http://www.foo.org" +distfiles="http://www.foo.org/foo-${version}.tar.gz" +checksum="fea0a94d4b605894f3e2d5572e3f96e4413bcad3a085aae7367c2cf07908b2ff" +``` + +The template file contains definitions to download, build and install the +package files to a `fake destdir`, and after this a binary package can be +generated with the definitions specified on it. + +Don't worry if anything is not clear as it should be. The reserved `variables` +and `functions` will be explained later. This `template` file should be created +in a directory matching `$pkgname`, i.e: `xbps-packages/srcpkgs/foo/template`. +If everything went fine after running `xbps-src build-pkg` a binary package +called `foo-1.0_1..xbps` will be generated in the local repository: +`/host/binpkgs`. + +### Subpackages + +In the example shown above just a binary package is generated, but with some +simple tweaks multiple binary packages can be generated from a single +template/build, this is called `subpackages`. + +To create additional `subpackages` the `template` must define a new function +with this naming: `_package()`, i.e: + +``` +# Template file for 'foo' + +pkgname="foo" +version="1.0" +revision=1 +build_style=gnu-configure +short_desc="A short description max 72 chars" +maintainer="name " +license="GPL-3" +homepage="http://www.foo.org" +distfiles="http://www.foo.org/foo-${version}.tar.gz" +checksum="fea0a94d4b605894f3e2d5572e3f96e4413bcad3a085aae7367c2cf07908b2ff" + +# foo-devel is a subpkg +foo-devel_package() { + short_desc+=" - development files" + depends="${sourcepkg}>=${version}_${revision}" + pkg_install() { + vmove usr/include + vmove usr/lib/*.a + vmove usr/lib/*.so + vmove usr/lib/pkgconfig + } +} +``` + +All subpackages need an additional symlink to the `main` pkg, i.e: + +``` + /srcpkgs + |- foo <- directory (main pkg) + | |- template + |- foo-devel <- symlink to `foo` +``` + +Otherwise dependencies requiring those packages won't find its `template` +file. + +### Development packages + +A development package, commonly generated as a subpackage, shall only contain +files required for development, that is, headers, static libraries, shared +library symlinks, pkg-config files, API documentation or any other script +that is only useful when developping for the target software. + +A development package should depend on packages that are required to link +against the provided shared libraries, i.e if `libfoo` provides the +`libfoo.so.2` shared library and the linking needs `-lbar`, the package +providing the `libbar` shared library should be added as a dependency; +and most likely it shall depend on its development package. + +If a development package provides a `pkg-config` file, you should verify +what dependencies the package needs for dynamic or static linking, and add +the appropiate `development` packages as dependencies. + +## 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. + +- *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`. + +- *configure*: 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. + +- *install*: This phase installs the `package files` into a `fake destdir`, +via `make install` or any other compatible method. + +- *package*: This phase builds the `binary packages` with files stored in the +`package destdir` and registers them into the local repository. + +`xbps-src` supports running just the specified phase, and if it ran +successfully, the phase will be skipped later (unless its work directory +`${wrksrc}` is removed with `xbps-src clean`). + +### Global functions + +The following functions are defined by `xbps-src` and can be used on any template: + +- *vinstall()* `vinstall []` + + Installs `file` with the specified `mode` into `targetdir` into the pkg `$DESTDIR` +The optional 4th argument can be used to change the `file name`. + +- *vcopy()* `vcopy ` + + Copies resursively all files in `pattern` to `targetdir` into the pkg `$DESTDIR` + +- *vmove()* `vmove ` + + Moves `pattern` to the specified directory in the pkg `$DESTDIR` + +- *vmkdir()* `vmkdir []` + + Creates a directory in the pkg `$DESTDIR`. The 2nd optional argument sets the mode of the directory. + +> NOTE: shell wildcards must be properly quoted, i.e `vmove "usr/lib/*.a"`. + +### 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`. + +- *sourcepkg*: 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. + +- *CROSS_BUILD*: True if `xbps-src` is cross compiling a package. + +- *DESTDIR*: Full path to the fake destdir used by the source pkg, set to +`${XBPS_MASTERDIR}/destdir/${sourcepkg}-${version}`. + +- *FILESDIR*: Full path to the `files` package directory, i.e `srcpkgs/foo/files`. +The `files` directory can be used to store additional files to be installed +as part of the source package. + +- *PKGDESTDIR*: Full path to the fake destdir used by the `pkg_install()` function in +`subpackages`, set to `${XBPS_MASTERDIR}/destdir/${pkgname}-${version}`. + +- *XBPS_BUILDDIR*: Directory to store the `source code` of the source package being processed, +set to `${XBPS_MASTERDIR}/destdir`. The package `wrksrc` is always stored +in this directory. + +- *XBPS_MACHINE*: The machine architecture as returned by `uname -m`. + +- *XBPS_SRCDISTDIR*: Full path to where the `source distfiles` are stored, i.e `$XBPS_HOSTDIR/sources`. + +- *XBPS_SRCPKGDIR*: Full path to the `srcpkgs` directory. + +- *XBPS_TARGET_MACHINE*: The target machine architecture when cross compiling a package. + +- *XBPS_FETCH_CMD*: The utility to fetch files from `ftp`, `http` of `https` servers. + +### Available variables + +#### Mandatory variables + +The list of mandatory variables for a template: + +- *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`. + +- *maintainer*: A string in the form of `name `. + +- *pkgname*: A string with the package name, matching `srcpkgs/`. + +- *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. + +- *short_desc*: 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. + + +#### 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"`. + +- *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"`. + +- *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. + +- *distfiles*: The full URL to the `upstream` source distribution files. Multiple files +can be separated by whitespaces. The files must end in `.tar.lzma`, `.tar.xz`, +`.txz`, `.tar.bz2`, `.tbz`, `.tar.gz`, `.tgz`, `.gz`, `.bz2`, `.tar` or +`.zip`. To define a target filename, append `>filename` to the URL. +Example: + distfiles="http://foo.org/foo-1.0.tar.gz http://foo.org/bar-1.0.tar.gz>bar.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"` + +- *wrksrc*: 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. + +- *create_wrksrc*: 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"` + +- *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. + +- *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`. + +- *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`. + +- *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`. + +- *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. + +- *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. 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). + +- *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 `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//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. + +- *keep_libtool_archives*: 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"`. + +- *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`. + +- *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. + +### build style scripts + +The `build_style` variable specifies the build method to build and install a +package. It expects the name of any available script in the +`/usr/share/xbps-src/build_style` directory. Please note that required packages +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`. + +- *configure*: 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`. + +- *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 +via `make_install_target`. + +- *meta*: 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 +[Module::Build](http://search.cpan.org/~leont/Module-Build-0.4202/lib/Module/Build.pm) method. + +- *perl*: For packages that use the Perl +[ExtUtils::MakeMaker](http://perldoc.perl.org/ExtUtils/MakeMaker.html) build method. + +- *python-module*: For packages that use the Python module build method (setup.py). + +- *waf3*: For packages that use the Python3 `waf` build method with python3. + +- *waf*: 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 + +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. + +- *do_extract()*: if defined and `distfiles` is not set, use it to extract the required sources. + +- *post_extract()*: Actions to execute after `do_extract()`. + +- *pre_configure()*: 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. + +- *post_configure()*: Actions to execute after `do_configure()`. + +- *pre_build()*: Actions to execute after `post_configure()`. + +- *do_build()*: Actions to execute to build the package. + +- *post_build()*: Actions to execute after `do_build()`. + +- *pre_install()*: ctions to execute after `post_build()`. + +- *do_install()*: Actions to execute to install the package files into the `fake destdir`. + +- *post_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. + +### 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. + +The following variables may be set to allow package build options: + +- *build_options*: Sets the build options supported by the source package. + +- *build_options_default*: Sets the default build options to be used by the source package. + +- `desc_option_