Update Manual.md with Table of Contents.
This commit is contained in:
parent
8037f82a6c
commit
f27fa78751
69
Manual.md
69
Manual.md
|
@ -3,6 +3,42 @@
|
||||||
This article contains an exhaustive manual of how to create new source
|
This article contains an exhaustive manual of how to create new source
|
||||||
packages for XBPS, the `Void Linux` native packaging system.
|
packages for XBPS, the `Void Linux` native packaging system.
|
||||||
|
|
||||||
|
*Table of Contents*
|
||||||
|
|
||||||
|
* [Introduction](#Introduction)
|
||||||
|
* [Package build phases](#buildphase)
|
||||||
|
* [Package naming conventions](#namingconvention)
|
||||||
|
* [Libraries](#libs)
|
||||||
|
* [Language Modules](#language_modules)
|
||||||
|
* [Language Bindings](#language_bindings)
|
||||||
|
* [Programs](#programs)
|
||||||
|
* [Global functions](#global_funcs)
|
||||||
|
* [Global variables](#global_vars)
|
||||||
|
* [Available variables](#available_vars)
|
||||||
|
* [Mandatory variables](#mandatory_vars)
|
||||||
|
* [Optional variables](#optional_vars)
|
||||||
|
* [Repositories](#repositories)
|
||||||
|
* [Repositories defined by Branch](#repo_by_branch)
|
||||||
|
* [Package defined repositories](#pkg_defined_repo)
|
||||||
|
* [Checking for new upstream releases](#updates)
|
||||||
|
* [Build style scripts](#build_scripts)
|
||||||
|
* [Functions](#functions)
|
||||||
|
* [Build otions](#build_options)
|
||||||
|
* [Runtime dependencies](#deps_runtime)
|
||||||
|
* [INSTALL and REMOVE files](#install_remove_files)
|
||||||
|
* [INSTALL.msg and REMOVE.msg files](#install_remove_files_msg)
|
||||||
|
* [Creating system accounts/groups at runtime](#runtime_account_creation)
|
||||||
|
* [32bit packages](#32bit_pkgs)
|
||||||
|
* [Subpackages](#pkgs_sub)
|
||||||
|
* [Development packages](#pkgs_development)
|
||||||
|
* [Python packages](#pkgs_python)
|
||||||
|
* [Go packages](#pkgs_go)
|
||||||
|
* [Notes](#notes)
|
||||||
|
* [Contributing via git](#contributing)
|
||||||
|
* [Help](#help)
|
||||||
|
|
||||||
|
|
||||||
|
<a id="Introduction"></a>
|
||||||
## Introduction
|
## Introduction
|
||||||
|
|
||||||
The `void-packages` repository contains all `source` packages that are the
|
The `void-packages` repository contains all `source` packages that are the
|
||||||
|
@ -45,6 +81,7 @@ If everything went fine after running
|
||||||
a binary package named `foo-1.0_1.<arch>.xbps` will be generated in the local repository
|
a binary package named `foo-1.0_1.<arch>.xbps` will be generated in the local repository
|
||||||
`hostdir/binpkgs`.
|
`hostdir/binpkgs`.
|
||||||
|
|
||||||
|
<a id="buildphase"></a>
|
||||||
### Package build phases
|
### Package build phases
|
||||||
|
|
||||||
Building a package consist of the following phases:
|
Building a package consist of the following phases:
|
||||||
|
@ -73,8 +110,10 @@ via `make install` or any other compatible method.
|
||||||
successfully, the phase will be skipped later (unless its work directory
|
successfully, the phase will be skipped later (unless its work directory
|
||||||
`${wrksrc}` is removed with `xbps-src clean`).
|
`${wrksrc}` is removed with `xbps-src clean`).
|
||||||
|
|
||||||
|
<a id="namingconventions"></a>
|
||||||
### Package naming conventions
|
### Package naming conventions
|
||||||
|
|
||||||
|
<a id="libs"></a>
|
||||||
#### Libraries
|
#### Libraries
|
||||||
|
|
||||||
Libraries are packages which provide shared objects (\*.so) in /usr/lib.
|
Libraries are packages which provide shared objects (\*.so) in /usr/lib.
|
||||||
|
@ -98,6 +137,7 @@ a linked program.
|
||||||
against this package. If the library is a sub package, its corresponding
|
against this package. If the library is a sub package, its corresponding
|
||||||
development package should be named `lib<name>-devel`
|
development package should be named `lib<name>-devel`
|
||||||
|
|
||||||
|
<a id="language_modules"></a>
|
||||||
#### Language Modules
|
#### Language Modules
|
||||||
|
|
||||||
Language modules are extensions to script or compiled languages. Those packages
|
Language modules are extensions to script or compiled languages. Those packages
|
||||||
|
@ -118,6 +158,7 @@ for the language prefix.
|
||||||
|
|
||||||
Example: python-pam, perl-URI, python-pyside
|
Example: python-pam, perl-URI, python-pyside
|
||||||
|
|
||||||
|
<a id="language_bindings"></a>
|
||||||
#### Language Bindings
|
#### Language Bindings
|
||||||
|
|
||||||
Language Bindings are packages which allow programs or libraries to have
|
Language Bindings are packages which allow programs or libraries to have
|
||||||
|
@ -130,6 +171,7 @@ The naming convention to those packages is:
|
||||||
|
|
||||||
Example: gimp-python, irssi-perl
|
Example: gimp-python, irssi-perl
|
||||||
|
|
||||||
|
<a id="programs"></a>
|
||||||
#### Programs
|
#### Programs
|
||||||
|
|
||||||
Programs put executables under /usr/bin (or in very special cases in other
|
Programs put executables under /usr/bin (or in very special cases in other
|
||||||
|
@ -145,6 +187,7 @@ Programs can be split into program packages and library packages. The program
|
||||||
package should be named as describe above. The library package should be prefix
|
package should be named as describe above. The library package should be prefix
|
||||||
with "lib" (see section `Libraries`)
|
with "lib" (see section `Libraries`)
|
||||||
|
|
||||||
|
<a id="global_funcs"></a>
|
||||||
### Global functions
|
### Global functions
|
||||||
|
|
||||||
The following functions are defined by `xbps-src` and can be used on any template:
|
The following functions are defined by `xbps-src` and can be used on any template:
|
||||||
|
@ -215,6 +258,7 @@ The optional 4th argument can be used to change the `file name`.
|
||||||
|
|
||||||
> Shell wildcards must be properly quoted, i.e `vmove "usr/lib/*.a"`.
|
> Shell wildcards must be properly quoted, i.e `vmove "usr/lib/*.a"`.
|
||||||
|
|
||||||
|
<a id="global_vars"></a>
|
||||||
### 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:
|
||||||
|
@ -252,8 +296,10 @@ in this directory such as `${XBPS_BUILDDIR}/${wrksrc}`.
|
||||||
|
|
||||||
- `XBPS_FETCH_CMD` The utility to fetch files from `ftp`, `http` of `https` servers.
|
- `XBPS_FETCH_CMD` The utility to fetch files from `ftp`, `http` of `https` servers.
|
||||||
|
|
||||||
|
<a id="available_vars"></a>
|
||||||
### Available variables
|
### Available variables
|
||||||
|
|
||||||
|
<a id="mandatory_vars"></a>
|
||||||
#### Mandatory variables
|
#### Mandatory variables
|
||||||
|
|
||||||
The list of mandatory variables for a template:
|
The list of mandatory variables for a template:
|
||||||
|
@ -276,7 +322,7 @@ the generated `binary packages` have been modified.
|
||||||
- `version` A string with the package version. Must not contain dashes and at least
|
- `version` A string with the package version. Must not contain dashes and at least
|
||||||
one digit is required.
|
one digit is required.
|
||||||
|
|
||||||
|
<a id="optional_vars"></a>
|
||||||
#### Optional variables
|
#### Optional variables
|
||||||
|
|
||||||
- `hostmakedepends` The list of `host` dependencies required to build the package, and
|
- `hostmakedepends` The list of `host` dependencies required to build the package, and
|
||||||
|
@ -441,8 +487,10 @@ pkgver the resulting package should revert. This field *must* be defined before
|
||||||
defined in `reverts` must be lesser than the one defined in `version`.
|
defined in `reverts` must be lesser than the one defined in `version`.
|
||||||
example: `reverts="2.0_1 2.0_2"`
|
example: `reverts="2.0_1 2.0_2"`
|
||||||
|
|
||||||
|
<a id="repositories"></a>
|
||||||
#### Repositories
|
#### Repositories
|
||||||
|
|
||||||
|
<a id="repo_by_branch"></a>
|
||||||
##### Repositories defined by Branch
|
##### Repositories defined by Branch
|
||||||
|
|
||||||
The global repository takes the name of
|
The global repository takes the name of
|
||||||
|
@ -450,6 +498,7 @@ the current branch, except if the name of the branch is master. Then the resulti
|
||||||
repository will be at the global scope. The usage scenario is that the user can
|
repository will be at the global scope. The usage scenario is that the user can
|
||||||
update multiple packages in a second branch without polluting his local repository.
|
update multiple packages in a second branch without polluting his local repository.
|
||||||
|
|
||||||
|
<a id="pkg_defined_repo"></a>
|
||||||
##### Package defined Repositories
|
##### Package defined Repositories
|
||||||
|
|
||||||
The second way to define a repository is by setting the `repository` variable in
|
The second way to define a repository is by setting the `repository` variable in
|
||||||
|
@ -462,7 +511,8 @@ The following repository names are valid:
|
||||||
|
|
||||||
* `nonfree`: Repository for closed source packages.
|
* `nonfree`: Repository for closed source packages.
|
||||||
|
|
||||||
#### Checking for new upstream releases
|
<a id="updates"></a>
|
||||||
|
### Checking for new upstream releases
|
||||||
|
|
||||||
New upstream versions can be automatically checked using
|
New upstream versions can be automatically checked using
|
||||||
`./xbps-src update-check <pkgname>`. In some cases you need to override
|
`./xbps-src update-check <pkgname>`. In some cases you need to override
|
||||||
|
@ -488,6 +538,7 @@ versions. Example: `ignore="*b*"`
|
||||||
- `version` is the version number used to compare against
|
- `version` is the version number used to compare against
|
||||||
upstream versions. Example: `version=${version//./_}`
|
upstream versions. Example: `version=${version//./_}`
|
||||||
|
|
||||||
|
<a id="build_scripts"></a>
|
||||||
### build style scripts
|
### 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
|
||||||
|
@ -555,6 +606,7 @@ matching the `build_style` name, i.e:
|
||||||
|
|
||||||
`common/environment/build-style/gnu-configure.sh`
|
`common/environment/build-style/gnu-configure.sh`
|
||||||
|
|
||||||
|
<a id="functions"></a>
|
||||||
### 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
|
||||||
|
@ -590,6 +642,7 @@ still be passed in if it's a GNU configure script.
|
||||||
> A function defined in a template has preference over the same function
|
> A function defined in a template has preference over the same function
|
||||||
defined by a `build_style` script.
|
defined by a `build_style` script.
|
||||||
|
|
||||||
|
<a id="build_options"></a>
|
||||||
### Build options
|
### Build options
|
||||||
|
|
||||||
Some packages might be built with different build options to enable/disable
|
Some packages might be built with different build options to enable/disable
|
||||||
|
@ -689,6 +742,7 @@ i.e `XBPS_PKG_OPTIONS_xorg_server=opt`.
|
||||||
The list of supported package build options and its description is defined in the
|
The list of supported package build options and its description is defined in the
|
||||||
`common/options.description` file.
|
`common/options.description` file.
|
||||||
|
|
||||||
|
<a id="deps_runtime"></a>
|
||||||
#### Runtime dependencies
|
#### Runtime dependencies
|
||||||
|
|
||||||
Dependencies for ELF objects are detected automatically by `xbps-src`, hence runtime
|
Dependencies for ELF objects are detected automatically by `xbps-src`, hence runtime
|
||||||
|
@ -728,6 +782,7 @@ and is by using the `virtual?` keyword, i.e `depends="virtual?vpkg-0.1_1"`. This
|
||||||
a `runtime` virtual dependency to `vpkg-0.1_1`; this `virtual` dependency will be simply ignored
|
a `runtime` virtual dependency to `vpkg-0.1_1`; this `virtual` dependency will be simply ignored
|
||||||
when the package is being built with `xbps-src`.
|
when the package is being built with `xbps-src`.
|
||||||
|
|
||||||
|
<a id="install_remove_files"></a>
|
||||||
### INSTALL and REMOVE files
|
### INSTALL and REMOVE files
|
||||||
|
|
||||||
The INSTALL and REMOVE shell snippets can be used to execute certain actions at a specified
|
The INSTALL and REMOVE shell snippets can be used to execute certain actions at a specified
|
||||||
|
@ -771,6 +826,7 @@ be executed via `chroot(2)` won't work correctly.
|
||||||
> NOTE: do not use INSTALL/REMOVE scripts to print messages, see the next section for
|
> NOTE: do not use INSTALL/REMOVE scripts to print messages, see the next section for
|
||||||
more information.
|
more information.
|
||||||
|
|
||||||
|
<a id="install_remove_files_msg"></a>
|
||||||
### INSTALL.msg and REMOVE.msg files
|
### INSTALL.msg and REMOVE.msg files
|
||||||
|
|
||||||
The `INSTALL.msg` and `REMOVE.msg` files can be used to print a message at post-install
|
The `INSTALL.msg` and `REMOVE.msg` files can be used to print a message at post-install
|
||||||
|
@ -781,6 +837,7 @@ Ideally those files should not exceed 80 chars per line.
|
||||||
subpackages can also have their own `INSTALL.msg` and `REMOVE.msg` files, simply create them
|
subpackages can also have their own `INSTALL.msg` and `REMOVE.msg` files, simply create them
|
||||||
as `srcpkgs/<pkgname>/<subpkg>.INSTALL.msg` or `srcpkgs/<pkgname>/<subpkg>.REMOVE.msg` respectively.
|
as `srcpkgs/<pkgname>/<subpkg>.INSTALL.msg` or `srcpkgs/<pkgname>/<subpkg>.REMOVE.msg` respectively.
|
||||||
|
|
||||||
|
<a id="runtime_account_creation"></a>
|
||||||
### Creating system accounts/groups at runtime
|
### Creating system accounts/groups at runtime
|
||||||
|
|
||||||
There's a trigger along with some variables that are specifically to create
|
There's a trigger along with some variables that are specifically to create
|
||||||
|
@ -806,6 +863,7 @@ The **system user** is created by using a dynamically allocated **uid/gid** in y
|
||||||
and it's created as a `system account`, unless the **uid** is set. A new group will be created for the
|
and it's created as a `system account`, unless the **uid** is set. A new group will be created for the
|
||||||
specified `system account` and used exclusived for this purpose.
|
specified `system account` and used exclusived for this purpose.
|
||||||
|
|
||||||
|
<a id="32bit_pkgs"></a>
|
||||||
### 32bit packages
|
### 32bit packages
|
||||||
|
|
||||||
32bit packages are built automatically when the builder is x86 (32bit), but
|
32bit packages are built automatically when the builder is x86 (32bit), but
|
||||||
|
@ -824,6 +882,7 @@ paths separated by blanks, i.e `lib32files="/usr/bin/blah /usr/include/blah."`.
|
||||||
- `lib32mode` If unset, only shared libraries and pkg-config files will be copied to the
|
- `lib32mode` If unset, only shared libraries and pkg-config files will be copied to the
|
||||||
**32bit** package. If set to `full` all files will be copied as is.
|
**32bit** package. If set to `full` all files will be copied as is.
|
||||||
|
|
||||||
|
<a id="pkgs_sub"></a>
|
||||||
### Subpackages
|
### Subpackages
|
||||||
|
|
||||||
In the example shown above just a binary package is generated, but with some
|
In the example shown above just a binary package is generated, but with some
|
||||||
|
@ -884,6 +943,7 @@ destdir (`$DESTDIR`) to the `subpackage` destdir (`$PKGDESTDIR`).
|
||||||
Subpackages are processed always in alphabetical order; To force a custom order,
|
Subpackages are processed always in alphabetical order; To force a custom order,
|
||||||
the `subpackages` variable can be declared with the wanted order.
|
the `subpackages` variable can be declared with the wanted order.
|
||||||
|
|
||||||
|
<a id="pkgs_development"></a>
|
||||||
### Development packages
|
### Development packages
|
||||||
|
|
||||||
A development package, commonly generated as a subpackage, shall only contain
|
A development package, commonly generated as a subpackage, shall only contain
|
||||||
|
@ -901,6 +961,7 @@ If a development package provides a `pkg-config` file, you should verify
|
||||||
what dependencies the package needs for dynamic or static linking, and add
|
what dependencies the package needs for dynamic or static linking, and add
|
||||||
the appropiate `development` packages as dependencies.
|
the appropiate `development` packages as dependencies.
|
||||||
|
|
||||||
|
<a id="pkgs_python"></a>
|
||||||
### Python packages
|
### Python packages
|
||||||
|
|
||||||
Python packages should be built with the `python-module` build style, if possible. This sets
|
Python packages should be built with the `python-module` build style, if possible. This sets
|
||||||
|
@ -935,6 +996,7 @@ path may be specified, i.e `pycompile_dirs="usr/share/foo"`.
|
||||||
> NOTE: it's expected that additional subpkgs must be generated to allow packaging for multiple
|
> NOTE: it's expected that additional subpkgs must be generated to allow packaging for multiple
|
||||||
python versions.
|
python versions.
|
||||||
|
|
||||||
|
<a id="pkgs_go"></a>
|
||||||
### Go packages
|
### Go packages
|
||||||
|
|
||||||
Go packages should be built with the `go` build style, if possible.
|
Go packages should be built with the `go` build style, if possible.
|
||||||
|
@ -951,6 +1013,7 @@ The following variables influence how Go packages are built:
|
||||||
provided. This option should only be used with `-git` (or similar)
|
provided. This option should only be used with `-git` (or similar)
|
||||||
packages; using a versioned distfile is prefered.
|
packages; using a versioned distfile is prefered.
|
||||||
|
|
||||||
|
<a id="notes"></a>
|
||||||
### Notes
|
### Notes
|
||||||
|
|
||||||
- Make sure that all software is configured to use the `/usr` prefix.
|
- Make sure that all software is configured to use the `/usr` prefix.
|
||||||
|
@ -969,6 +1032,7 @@ the installed files (`./xbps-src show-files pkg`) before pushing new updates.
|
||||||
- Make sure that binaries are not stripped by the software, let xbps-src do this;
|
- Make sure that binaries are not stripped by the software, let xbps-src do this;
|
||||||
otherwise the `debug` packages won't have debugging symbols.
|
otherwise the `debug` packages won't have debugging symbols.
|
||||||
|
|
||||||
|
<a id="contributing"></a>
|
||||||
### Contributing via git
|
### Contributing via git
|
||||||
|
|
||||||
Fork the voidlinux `void-packages` git repository on github and clone it:
|
Fork the voidlinux `void-packages` git repository on github and clone it:
|
||||||
|
@ -997,6 +1061,7 @@ For commit messages please use the following rules:
|
||||||
- If you've removed a package use `"<pkgname>: removed ..."`.
|
- If you've removed a package use `"<pkgname>: removed ..."`.
|
||||||
- If you've modified a package use `"<pkgname>: ..."`.
|
- If you've modified a package use `"<pkgname>: ..."`.
|
||||||
|
|
||||||
|
<a id="help"></a>
|
||||||
## Help
|
## Help
|
||||||
|
|
||||||
If after reading this `manual` you still need some kind of help, please join
|
If after reading this `manual` you still need some kind of help, please join
|
||||||
|
|
Loading…
Reference in New Issue