wallenstein/void-packages
1
0
Fork 0
mirror of https://github.com/void-linux/void-packages.git synced 2025-06-07 15:43:49 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

manual.adoc: misc tweaks.

Browse source
This commit is contained in:
Juan RP 2013-11-22 17:51:38 +01:00
parent 99aa4e63e5
commit ded940cebf
1 changed files with 103 additions and 104 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

203
manual.adoc
View file

@ -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`. recipes to download, compile and build binary packages for `Void`.
Those `source` package files are called `templates`. 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) `variables` and `functions` that are processed by `xbps-src` (the package builder)
to generate the resulting binary packages. to generate the resulting binary packages.
A simple `template` example is as follows: A simple `template` example is as follows:
# Template file for 'foo' --------------------------------------------------------------------------
# source section # Template file for 'foo'
pkgname="foo"
version="1.0" ## source section
revision="1" pkgname="foo"
build_style="gnu-configure" version="1.0"
short_desc="A short description max 72 chars" revision="1"
maintainer="name <email>" build_style="gnu-configure"
license="GPL-3" short_desc="A short description max 72 chars"
homepage="http://www.foo.org" maintainer="name <email>"
distfiles="http://www.foo.org/foo-${version}.tar.gz" license="GPL-3"
checksum="fea0a94d4b605894f3e2d5572e3f96e4413bcad3a085aae7367c2cf07908b2ff" homepage="http://www.foo.org"
# end of source section distfiles="http://www.foo.org/foo-${version}.tar.gz"
# package section checksum="fea0a94d4b605894f3e2d5572e3f96e4413bcad3a085aae7367c2cf07908b2ff"
foo_package() { # end of source section
## package section
foo_package() {
pkg_install() { pkg_install() {
vmove all vmove all
} }
} }
# end of package section ---------------------------------------------------------------------------
There are two main `sections` in a template: the `source section` and the There are two main `sections` in a template: the `source section` and the
@ -60,28 +63,27 @@ called `foo-1.0_1.<arch>.xbps` will be generated in the local repository.
Package build phases Package build phases
-------------------- --------------------
Building a package consist of the following phases: Building a package consist of the following phases:
`fetch`:: *fetch*::
This phase downloads required sources for a `source package`, as defined by This phase downloads required sources for a `source package`, as defined by
the `distfiles` variable or `do_fetch()` function. the `distfiles` variable or `do_fetch()` function.
`extract`:: *extract*::
This phase extracts the `distfiles` files into `$wrksrc` or executes the `do_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`. 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`. 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. 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 This phase installs the `package files` into a `fake destdir`, via `make install` or
any other compatible method. any other compatible method.
`build-pkg`:: *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 `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 Global variables
---------------- ----------------
The following variables are defined by `xbps-src` and can be used on any template: 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`. 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 Set to the to main package name, can be used to match the main package
rather than additional binary package names. rather than additional binary package names.
`CHROOT_READY`:: *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`:: *CROSS_BUILD*::
True if `xbps-src` is cross compiling a package. True if `xbps-src` is cross compiling a package.
`DESTDIR`:: *DESTDIR*::
Full path to the fake destdir used by the `source section`, set to Full path to the fake destdir used by the `source section`, set to
`${XBPS_MASTERDIR}/destdir/${sourcepkg}-${version}`. `${XBPS_MASTERDIR}/destdir/${sourcepkg}-${version}`.
`PKGDESTDIR`:: *PKGDESTDIR*::
Full path to the fake destdir used by the `pkg_install()` function in the Full path to the fake destdir used by the `pkg_install()` function in the
`package section`, set to `${XBPS_MASTERDIR}/destdir/pkg-${pkgname}-${version}`. `package section`, set to `${XBPS_MASTERDIR}/destdir/pkg-${pkgname}-${version}`.
`XBPS_MACHINE`:: *XBPS_MACHINE*::
The machine architecture as returned by `uname -m`. 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`. Full path to where the `source distfiles` are stored, i.e `$XBPS_HOSTDIR/sources`.
`XBPS_SRCPKGDIR`:: *XBPS_SRCPKGDIR*::
Full path to the `srcpkgs` directory. Full path to the `srcpkgs` directory.
`XBPS_TARGET_MACHINE`:: *XBPS_TARGET_MACHINE*::
The target machine architecture when cross compiling a package. 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`: The list of mandatory variables in the `source section`:
`homepage`:: *homepage*::
A string pointing to the `upstream` homepage. A string pointing to the `upstream` homepage.
`license`:: *license*::
A string matching any license file available in `/usr/share/licenses`. 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`. Multiple licenses should be separated by commas, i.e `GPL-3, LGPL-2.1`.
`maintainer`:: *maintainer*::
A string in the form of `name <user@domain>`. A string in the form of `name <user@domain>`.
`pkgname`:: *pkgname*::
A string with the package name, matching `srcpkgs/<pkgname>`. A string with the package name, matching `srcpkgs/<pkgname>`.
`revision`:: *revision*::
A number that must be set to 1 when the `source package` is created, or 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 updated to a new `upstream version`. This should only be increased when
the generated `binary packages` have been modified. the generated `binary packages` have been modified.
`short_desc`:: *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`:: *version*::
A string with the package version. Must not contain dashes and at least A string with the package version. Must not contain dashes and at least
one digit is required. one digit is required.
source section - optional variables Optional variables
----------------------------------- ~~~~~~~~~~~~~~~~~~
*hostmakedepends*::
`hostmakedepends`::
The list of `host` dependencies required to build the package. Dependencies The list of `host` dependencies required to build the package. Dependencies
can be specified with the following version comparators: `<`, `>`, `<=`, `>=` can be specified with the following version comparators: `<`, `>`, `<=`, `>=`
or `foo-1.0_1` to match an exact version. If version comparator is not 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`. defined (just a package name), the version comparator is automatically set to `>=0`.
Example `hostmakedepends="foo blah<1.0"`. Example `hostmakedepends="foo blah<1.0"`.
`makedepends`:: *makedepends*::
The list of `target` dependencies required to build the package. Dependencies The list of `target` dependencies required to build the package. Dependencies
can be specified with the following version comparators: `<`, `>`, `<=`, `>=` can be specified with the following version comparators: `<`, `>`, `<=`, `>=`
or `foo-1.0_1` to match an exact version. If version comparator is not 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`. defined (just a package name), the version comparator is automatically set to `>=0`.
Example `makedepends="foo blah>=1.0"`. Example `makedepends="foo blah>=1.0"`.
`bootstrap`:: *bootstrap*::
If enabled the source package is considered to be part of the `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 process and required to be able to build packages in the chroot. Only a
small number of packages must set this property. small number of packages must set this property.
`distfiles`:: *distfiles*::
The full URL to the `upstream` source distribution files. Multiple files 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`, 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 `.txz`, `.tar.bz2`, `.tbz`, `.tar.gz`, `.tgz`, `.gz`, `.bz2`, `.tar` or
`.zip`. Example `distfiles="http://foo.org/foo-1.0.tar.gz"` `.zip`. Example `distfiles="http://foo.org/foo-1.0.tar.gz"`
`checksum`:: *checksum*::
The `sha256` digests matching `${distfiles}`. Multiple files can be The `sha256` digests matching `${distfiles}`. Multiple files can be
separated by blanks. Please note that the order must be the same than separated by blanks. Please note that the order must be the same than
was used in `${distfiles}`. Example `checksum="kkas00xjkjas"` 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 A long description of the main package. Max 80 chars per line and must
not contain the following characters: `&`, `<`, `>`. not contain the following characters: `&`, `<`, `>`.
`wrksrc`:: *wrksrc*::
The directory name where the package sources are extracted, by default The directory name where the package sources are extracted, by default
set to `${pkgname}-${version}`. set to `${pkgname}-${version}`.
`build_wrksrc`:: *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`:: *create_wrksrc*::
Enable it to create the `${wrksrc}` directory. Required if a package Enable it to create the `${wrksrc}` directory. Required if a package
contains multiple `distfiles`. contains multiple `distfiles`.
`only_for_archs`:: *only_for_archs*::
This expects a separated list of architectures where the package can be This expects a separated list of architectures where the package can be
built matching `uname -m` output. Example `only_for_archs="x86_64 armv6l"` 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 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, about the available package `build methods`. If `build_style` is not set,
the package must define at least a `do_install()` function, and optionally the package must define at least a `do_install()` function, and optionally
more build phases as such `do_configure()`, `do_build()`, etc. 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}` This creates a directory in `${XBPS_SRCDISTDIR}` as such `${pkgname}-${version}`
to store the package sources at the `extract` phase. Required in packages that to store the package sources at the `extract` phase. Required in packages that
use unversioned ${distfiles}`. use unversioned ${distfiles}`.
`configure_script`:: *configure_script*::
The name of the `configure` script to execute at the `configure` phase if The name of the `configure` script to execute at the `configure` phase if
`${build_style}` is set to `configure` or `gnu-configure` build methods. `${build_style}` is set to `configure` or `gnu-configure` build methods.
By default set to `./configure`. By default set to `./configure`.
`configure_args`:: *configure_args*::
The arguments to be passed in to the `configure` script if `${build_style}` 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 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 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`. 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 The executable to run at the `build` phase if `${build_style}` is set to
`configure`, `gnu-configure` or `gnu-makefile` build methods. `configure`, `gnu-configure` or `gnu-makefile` build methods.
By default set to `make`. 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 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_style}` is set to `configure`, `gnu-configure` or `gnu_makefile`
build methods. Unset by default. build methods. Unset by default.
`make_install_args`:: *make_install_args*::
The arguments to be passed in to `${make_cmd}` at the `install-destdir` The arguments to be passed in to `${make_cmd}` at the `install-destdir`
phase if `${build_style}` is set to `configure`, `gnu-configure` or phase if `${build_style}` is set to `configure`, `gnu-configure` or
`gnu_makefile` build methods. Unset by default. `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 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_style}` is set to `configure`, `gnu-configure` or `gnu_makefile`
build methods. Unset by default (`all` target). 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 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` if `${build_style}` is set to `configure`, `gnu-configure` or `gnu_makefile`
build methods. By default set to `DESTDIR=${DESTDIR} install`. 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 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 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`. `srcpkgs/<pkgname>/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. 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 If enabled the `GNU Libtool` archives won't be removed. By default those
files are always removed automatically. files are always removed automatically.
`skip_extraction`:: *skip_extraction*::
A list of filenames that should not be extracted in the `extract` phase. A list of filenames that should not be extracted in the `extract` phase.
This must match the basename of any url defined in `${distfiles}`. This must match the basename of any url defined in `${distfiles}`.
Example `skip_extraction="foo-${version}.tar.gz"`. Example `skip_extraction="foo-${version}.tar.gz"`.
`force_debug_pkgs`:: *force_debug_pkgs*::
If enabled binary packages with debugging symbols will be generated If enabled binary packages with debugging symbols will be generated
even if `XBPS_DEBUG_PKGS` is disabled in `xbps-src.conf` or in the even if `XBPS_DEBUG_PKGS` is disabled in `xbps-src.conf` or in the
`command line arguments`. `command line arguments`.
source section - build style build style scripts
---------------------------- ~~~~~~~~~~~~~~~~~~~
The `build_style` variable specifies the build method to build and install a The `build_style` variable specifies the build method to build and install a
package. It expects the name of any available script in the package. It expects the name of any available script in the
`/usr/share/xbps-src/build_style` directory. Please note that required packages `/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: The current list of available `build_style` scripts is the following:
`cmake`:: *cmake*::
For packages that use the CMake build system, configuration arguments For packages that use the CMake build system, configuration arguments
can be passed in via `configure_args`. can be passed in via `configure_args`.
`configure`:: *configure*::
For packages that use non-GNU configure scripts, at least `--prefix=/usr` For packages that use non-GNU configure scripts, at least `--prefix=/usr`
should be passed in via `configure_args`. should be passed in via `configure_args`.
`gnu-configure`:: *gnu-configure*::
For packages that use GNU configure scripts, additional configuration For packages that use GNU configure scripts, additional configuration
arguments can be passed in via `configure_args`. 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 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 `make_build_args` and install arguments via `make_install_args`. The build
target can be overriden via `make_build_target` and the install target 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 For `meta-packages`, i.e packages that only install local files or simply
depend on additional packages. depend on additional packages.
`perl-ModuleBuild`:: *perl-ModuleBuild*::
For packages that use the Perl For packages that use the Perl
http://search.cpan.org/~leont/Module-Build-0.4202/lib/Module/Build.pm[Module::Build] method. http://search.cpan.org/~leont/Module-Build-0.4202/lib/Module/Build.pm[Module::Build] method.
`perl`:: *perl*::
For packages that use the Perl For packages that use the Perl
http://perldoc.perl.org/ExtUtils/MakeMaker.html[ExtUtils::MakeMaker] build method. 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). For packages that use the Python module build method (setup.py).
`waf3`:: *waf3*::
For packages that use the Python3 `waf` build method with python3. For packages that use the Python3 `waf` build method with python3.
`waf`:: *waf*::
For packages that use the Python `waf` method with python2. 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 The following functions can be defined to change the behavior of how the
package is downloaded, compiled and installed. package is downloaded, compiled and installed.
`do_fetch`:: *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`:: *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`:: *post_extract()*::
Actions to execute after `do_extract()`. Actions to execute after `do_extract()`.
`pre_configure`:: *pre_configure()*::
Actions to execute after `post_extract()`. Actions to execute after `post_extract()`.
`do_configure`:: *do_configure()*::
Actions to execute to configure the package; `${configure_args}` should Actions to execute to configure the package; `${configure_args}` should
still be passed in if it's a GNU configure script. still be passed in if it's a GNU configure script.
`post_configure`:: *post_configure()*::
Actions to execute after `do_configure()`. Actions to execute after `do_configure()`.
`pre_build`:: *pre_build()*::
Actions to execute after `post_configure()`. Actions to execute after `post_configure()`.
`do_build`:: *do_build()*::
Actions to execute to build the package. Actions to execute to build the package.
`post_build`:: *post_build()*::
Actions to execute after `do_build()`. Actions to execute after `do_build()`.
`pre_install`:: *pre_install()*::
Actions to execute after `post_build()`. Actions to execute after `post_build()`.
`do_install`:: *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`:: *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 NOTE: A function defined in a template has preference over the same function
defined by a `build_style` script. defined by a `build_style` script.