From ded940cebfb1d6d30556b59dbf2fccbadee963bf Mon Sep 17 00:00:00 2001 From: Juan RP Date: Fri, 22 Nov 2013 17:51:38 +0100 Subject: [PATCH] manual.adoc: misc tweaks. --- manual.adoc | 207 ++++++++++++++++++++++++++-------------------------- 1 file changed, 103 insertions(+), 104 deletions(-) diff --git a/manual.adoc b/manual.adoc index 3158f106431..7ad266a8853 100644 --- a/manual.adoc +++ b/manual.adoc @@ -16,32 +16,35 @@ 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 +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' - # 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 - } +-------------------------------------------------------------------------- +# 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 @@ -60,28 +63,27 @@ 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`:: +*fetch*:: This phase downloads required sources for a `source package`, as defined by the `distfiles` variable or `do_fetch()` function. -`extract`:: +*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`:: +*configure*:: This phase executes the `configuration` of a `source package`, i.e `GNU configure scripts`. -`build`:: +*build*:: This phase compiles/prepares the `source files` via `make` or any other compatible method. -`install-destdir`:: +*install-destdir*:: This phase installs the `package files` into a `fake destdir`, via `make install` or any other compatible method. -`build-pkg`:: +*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 @@ -90,198 +92,196 @@ successfully, the phase will be skipped later (unless its work directory Global variables ---------------- - The following variables are defined by `xbps-src` and can be used on any template: -`makejobs`:: +*makejobs*:: Set to `-jX` if `XBPS_MAKEJOBS` is defined, to allow parallel jobs with `GNU make`. -`sourcepkg`:: +*sourcepkg*:: Set to the to main package name, can be used to match the main package rather than additional binary package names. -`CHROOT_READY`:: +*CHROOT_READY*:: True if the target chroot (masterdir) is ready for chroot builds. -`CROSS_BUILD`:: +*CROSS_BUILD*:: True if `xbps-src` is cross compiling a package. -`DESTDIR`:: +*DESTDIR*:: Full path to the fake destdir used by the `source section`, set to `${XBPS_MASTERDIR}/destdir/${sourcepkg}-${version}`. -`PKGDESTDIR`:: +*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`:: +*XBPS_MACHINE*:: The machine architecture as returned by `uname -m`. -`XBPS_SRCDISTDIR`:: +*XBPS_SRCDISTDIR*:: Full path to where the `source distfiles` are stored, i.e `$XBPS_HOSTDIR/sources`. -`XBPS_SRCPKGDIR`:: +*XBPS_SRCPKGDIR*:: Full path to the `srcpkgs` directory. -`XBPS_TARGET_MACHINE`:: +*XBPS_TARGET_MACHINE*:: The target machine architecture when cross compiling a package. -source section - mandatory variables ------------------------------------- - +Source section +-------------- +Mandatory variables +~~~~~~~~~~~~~~~~~~~ The list of mandatory variables in the `source section`: -`homepage`:: +*homepage*:: A string pointing to the `upstream` homepage. -`license`:: +*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`:: +*maintainer*:: A string in the form of `name `. -`pkgname`:: +*pkgname*:: A string with the package name, matching `srcpkgs/`. -`revision`:: +*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`:: +*short_desc*:: A string with a brief description for this package. Max 72 chars. -`version`:: +*version*:: A string with the package version. Must not contain dashes and at least one digit is required. -source section - optional variables ------------------------------------ - -`hostmakedepends`:: +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`:: +*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`:: +*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`:: +*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`:: +*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`:: +*long_desc*:: A long description of the main package. Max 80 chars per line and must not contain the following characters: `&`, `<`, `>`. -`wrksrc`:: +*wrksrc*:: The directory name where the package sources are extracted, by default set to `${pkgname}-${version}`. -`build_wrksrc`:: +*build_wrksrc*:: A directory relative to `${wrksrc}` that will be used when building the package. -`create_wrksrc`:: +*create_wrksrc*:: Enable it to create the `${wrksrc}` directory. Required if a package contains multiple `distfiles`. -`only_for_archs`:: +*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`:: +*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`:: +*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`:: +*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`:: +*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`:: +*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`:: +*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`:: +*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`:: +*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`:: +*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`:: +*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`:: +*disable_parallel_build*:: If set the package won't be built in parallel and `XBPS_MAKEJOBS` has no effect. -`keep_libtool_archives`:: +*keep_libtool_archives*:: If enabled the `GNU Libtool` archives won't be removed. By default those files are always removed automatically. -`skip_extraction`:: +*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`:: +*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 ----------------------------- - +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 @@ -289,86 +289,85 @@ to execute a `build_style` script must be defined via `hostmakedepends`. The current list of available `build_style` scripts is the following: -`cmake`:: +*cmake*:: For packages that use the CMake build system, configuration arguments can be passed in via `configure_args`. -`configure`:: +*configure*:: For packages that use non-GNU configure scripts, at least `--prefix=/usr` should be passed in via `configure_args`. -`gnu-configure`:: +*gnu-configure*:: For packages that use GNU configure scripts, additional configuration arguments can be passed in via `configure_args`. -`gnu-makefile`:: +*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`:: +*meta*:: For `meta-packages`, i.e packages that only install local files or simply depend on additional packages. -`perl-ModuleBuild`:: +*perl-ModuleBuild*:: For packages that use the Perl http://search.cpan.org/~leont/Module-Build-0.4202/lib/Module/Build.pm[Module::Build] method. -`perl`:: +*perl*:: For packages that use the Perl http://perldoc.perl.org/ExtUtils/MakeMaker.html[ExtUtils::MakeMaker] build method. -`python-module`:: +*python-module*:: For packages that use the Python module build method (setup.py). -`waf3`:: +*waf3*:: For packages that use the Python3 `waf` build method with python3. -`waf`:: +*waf*:: For packages that use the Python `waf` method with python2. -source section - functions --------------------------- - +Functions +~~~~~~~~~ The following functions can be defined to change the behavior of how the package is downloaded, compiled and installed. -`do_fetch`:: +*do_fetch()*:: if defined and `distfiles` is not set, use it to fetch the required sources. -`do_extract`:: +*do_extract()*:: if defined and `distfiles` is not set, use it to extract the required sources. -`post_extract`:: +*post_extract()*:: Actions to execute after `do_extract()`. -`pre_configure`:: +*pre_configure()*:: Actions to execute after `post_extract()`. -`do_configure`:: +*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`:: +*post_configure()*:: Actions to execute after `do_configure()`. -`pre_build`:: +*pre_build()*:: Actions to execute after `post_configure()`. -`do_build`:: +*do_build()*:: Actions to execute to build the package. -`post_build`:: +*post_build()*:: Actions to execute after `do_build()`. -`pre_install`:: +*pre_install()*:: Actions to execute after `post_build()`. -`do_install`:: +*do_install()*:: Actions to execute to install the packages files into the `fake destdir`. -`post_install`:: +*post_install()*:: Actions to execute after `do_install()`. -NOTE: a function defined in a template has preference over the same function +NOTE: A function defined in a template has preference over the same function defined by a `build_style` script.