diff --git a/manual.txt b/manual.txt new file mode 100644 index 0000000000..ecc5e04e59 --- /dev/null +++ b/manual.txt @@ -0,0 +1,373 @@ +The XBPS source packages manual +=============================== +Juan RP +:Author Initials: JRP +:toc: +:icons: +:numbered: +: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*. + +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` 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' + + # source section + 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" + # end of source section + + # package section + foo_package() { + pkg_install() { + vmove all + } + } + # end of package section + + +There are two main `sections` in a template: the `source section` and the +`package section`. The `source section` contains definitions to download, build +and install the package files to a `fake destdir`. The `package section` +contains the definitions to how the resulting binary packages are generated. + +A template always requires at least a `source section` and a `package section`; +multiple `package sections` can be defined to generate `multiple binary packages`. + +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. + +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-destdir`:: + 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`. + +`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 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 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}`. + +`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. + + +source section - mandatory variables +------------------------------------ + +The list of mandatory variables in the `source section`: + +`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. + + +source section - 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 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"` + +`long_desc`:: + 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}`. + +`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. + +`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}`. + +`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. Unset by default. + +`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 `DESTDIR=${DESTDIR} 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`. + +source section - build style +---------------------------- + +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 + +`meta`:: + For `meta-packages`, i.e packages that only install local files or simply + depend on additional packages. + +`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 standard 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. + +source section - 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`:: + Actions to execute after `post_build()`. + +`do_install`:: + Actions to execute to install the packages 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.