manual.adoc: misc tweaks.
This commit is contained in:
Juan RP
parent
99aa4e63e5
commit
ded940cebf
1 changed files with 103 additions and 104 deletions
207
manual.adoc
207
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 <email>"
|
||||
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 <email>"
|
||||
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.<arch>.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 <user@domain>`.
|
||||
|
||||
`pkgname`::
|
||||
*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
|
||||
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/<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.
|
||||
|
||||
`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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue