* [PR PATCH] Run vmdfmt in the markdown files and update some information there
@ 2020-05-04 14:20 ericonr
2020-05-04 14:27 ` Duncaen
` (7 more replies)
0 siblings, 8 replies; 9+ messages in thread
From: ericonr @ 2020-05-04 14:20 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 895 bytes --]
There is a new pull request by ericonr against master on the void-packages repository
https://github.com/ericonr/void-packages contributing
https://github.com/void-linux/void-packages/pull/21609
Run vmdfmt in the markdown files and update some information there
- Had to remove html tags from those files and use markdown anchors instead
- Changed how files in this repo are linked to each other, GH supports using `[contributing](./CONTRIBUTING.md)`.
- Added some information regarding PRs, which I took from #21481 and one of my own PRs as well. This commit can be split from the rest, but it was easier to include it, since I was already messing with the formatting.
I've tested the hyperlinks in the GH interface, and they should be good to go. The main commit for comments should be f272b49.
A patch file from https://github.com/void-linux/void-packages/pull/21609.patch is attached
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-contributing-21609.patch --]
[-- Type: text/x-diff, Size: 89778 bytes --]
From 6de2d6ce8f0852cdc619ae8e4be932c52751d421 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Thu, 30 Apr 2020 22:37:58 -0300
Subject: [PATCH 1/6] CONTRIBUTING.md: format with vmdfmt
---
CONTRIBUTING.md | 150 ++++++++++++++++++++++++++++++++----------------
1 file changed, 102 insertions(+), 48 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0490b5f11c2..a55dda679ec 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,65 +1,99 @@
# Contributing to void-packages
-void-packages is the backbone of the Void Linux distribution. It contains all the definitions to build packages from source.
+void-packages is the backbone of the Void Linux distribution. It contains all
+the definitions to build packages from source.
-This document describes how you, as a contributor, can help with adding packages, correcting bugs and adding features to void-packages.
+This document describes how you, as a contributor, can help with adding
+packages, correcting bugs and adding features to void-packages.
## Getting your packages into Void by yourself
-If you really want to get a package into Void Linux, we recommend you package it yourself.
+If you really want to get a package into Void Linux, we recommend you package it
+yourself.
-We provide a [comprehensive Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md)
-on how to create new packages. There's also a
-[manual for xbps-src](https://github.com/void-linux/void-packages/blob/master/README.md), which is used
-to build package files from templates.
+We provide a [comprehensive
+Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md) on
+how to create new packages. There's also a [manual for
+xbps-src](https://github.com/void-linux/void-packages/blob/master/README.md),
+which is used to build package files from templates.
-For this guide, we assume you have basic knowledge about [git](http://git-scm.org), as well as a [GitHub Account](http://github.com).
+For this guide, we assume you have basic knowledge about
+[git](http://git-scm.org), as well as a [GitHub Account](http://github.com).
-Please note that we do not accept any packages containing non-release versions, such as specific git- or svn-revisions anymore.
+Please note that we do not accept any packages containing non-release versions,
+such as specific git- or svn-revisions anymore.
### Creating a new template
-You can use the helper tool `xnew`, from the [xtools](https://github.com/chneukirchen/xtools) package, to create new templates:
+You can use the helper tool `xnew`, from the
+[xtools](https://github.com/chneukirchen/xtools) package, to create new
+templates:
- $ xnew pkgname subpkg1 subpkg2 ...
+```
+$ xnew pkgname subpkg1 subpkg2 ...
+```
-Templates must have the name `void-packages/srcpkgs/<pkgname>/template`, where `pkgname` is the same as the `pkgname` variable in the template.
+Templates must have the name `void-packages/srcpkgs/<pkgname>/template`, where
+`pkgname` is the same as the `pkgname` variable in the template.
-For deeper insights on the contents of template files, please read the [manual](https://github.com/void-linux/void-packages/blob/master/Manual.md), and be sure to browse the existing template files in the `srcpkgs` directory of this repository for concrete examples.
+For deeper insights on the contents of template files, please read the
+[manual](https://github.com/void-linux/void-packages/blob/master/Manual.md), and
+be sure to browse the existing template files in the `srcpkgs` directory of this
+repository for concrete examples.
-When you've finished working on the template file, please check it with `xlint` helper from the [xtools](https://github.com/chneukirchen/xtools) package:
+When you've finished working on the template file, please check it with `xlint`
+helper from the [xtools](https://github.com/chneukirchen/xtools) package:
- $ xlint template
+```
+$ xlint template
+```
If `xlint` reports any issues, resolve them before committing.
### Committing your changes
-Once you have built your template file or files, the commit message should have one of the following forms:
+Once you have built your template file or files, the commit message should have
+one of the following forms:
-* for new packages, use ```New package: <pkgname>-<version>``` ([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)).
+- for new packages, use `New package: <pkgname>-<version>`
+ ([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)).
+- for package updates, use `<pkgname>: update to <version>.`
+ ([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)).
+- for template modifications without a version change, use `<pkgname>: <reason>`
+ ([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)).
-* for package updates, use ```<pkgname>: update to <version>.``` ([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)).
+If you want to describe your changes in more detail, add an empty line followed
+by those details
+([example](https://github.com/void-linux/void-packages/commit/f1c45a502086ba1952f23ace9084a870ce437bc6)).
-* for template modifications without a version change, use ```<pkgname>: <reason>``` ([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)).
+For further information, please consult the
+[manual](https://github.com/void-linux/void-packages/blob/master/Manual.md).
-If you want to describe your changes in more detail, add an empty line followed by those details ([example](https://github.com/void-linux/void-packages/commit/f1c45a502086ba1952f23ace9084a870ce437bc6)).
+`xbump`, available in the [xtools](https://github.com/chneukirchen/xtools)
+package, can be used to commit a new or updated package:
-For further information, please consult the [manual](https://github.com/void-linux/void-packages/blob/master/Manual.md).
+```
+$ xbump <pkgname> <git commit options>
+```
-`xbump`, available in the [xtools](https://github.com/chneukirchen/xtools) package, can be used to commit a new or updated package:
+`xbump` will use `git commit` to commit the changes with the appropriate commit
+message. For more fine-grained control over the commit, specific options can be
+passed to `git commit` by adding them after the package name.
- $ xbump <pkgname> <git commit options>
+After committing your changes, please check that the package builds
+successfully. From the top level directory of your local copy of the
+`void-packages` repository, run:
-`xbump` will use `git commit` to commit the changes with the appropriate commit message. For more fine-grained control over the commit, specific options can be passed to `git commit` by adding them after the package name.
+```
+$ ./xbps-src pkg <pkgname>
+```
-After committing your changes, please check that the package builds successfully. From the top level directory of your local copy of the `void-packages` repository, run:
+Your package must build successfully for at least x86, but we recommend trying
+to build for armv* as well, e.g.:
- $ ./xbps-src pkg <pkgname>
-
-Your package must build successfully for at least x86, but we recommend trying to build for armv* as well, e.g.:
-
- $ ./xbps-src -a armv7l pkg <pkgname>
+```
+$ ./xbps-src -a armv7l pkg <pkgname>
+```
For further details, see the output of `./xbps-src -h`.
@@ -67,40 +101,60 @@ For further details, see the output of `./xbps-src -h`.
Once you have successfully built the package, you can start a pull request.
-Most pull requests should only contain a single package and dependencies which are not part of void-packages yet.
+Most pull requests should only contain a single package and dependencies which
+are not part of void-packages yet.
-If you make updates to packages containing a soname bump you also need to revbump all packages that are dependant. Those
-packages should also be part of the same pull request.
+If you make updates to packages containing a soname bump you also need to
+revbump all packages that are dependant. Those packages should also be part of
+the same pull request.
-When you make changes to your pull request, please *do not close and reopen your pull request*. Instead, just forcibly git push, overwriting any old commits. Closing and opening your pull requests repeatedly spams the Void maintainers.
+When you make changes to your pull request, please *do not close and reopen your
+pull request*. Instead, just forcibly git push, overwriting any old commits.
+Closing and opening your pull requests repeatedly spams the Void maintainers.
#### Travis
-Once you have started a pull request, you will get instant feedback from Travis. It will check if the templates you have changed
-comply with the our guidelines. At the moment not all packages comply with the rules, so if you update a package, it may happen that Travis reports errors about places you haven't touched. Please feel free to fix those errors too.
+Once you have started a pull request, you will get instant feedback from Travis.
+It will check if the templates you have changed comply with the our guidelines.
+At the moment not all packages comply with the rules, so if you update a
+package, it may happen that Travis reports errors about places you haven't
+touched. Please feel free to fix those errors too.
#### Review
-Most of the time your pull request will contain mistakes. It's nothing bad, it just happens.
+Most of the time your pull request will contain mistakes. It's nothing bad, it
+just happens.
-Reviewers will comment on your pull request and point out which changes are needed before the template can be included.
+Reviewers will comment on your pull request and point out which changes are
+needed before the template can be included.
-We recommend having only a single commit for pull request, so if you need to make changes in commits but already have a pull request, use the following commands:
+We recommend having only a single commit for pull request, so if you need to
+make changes in commits but already have a pull request, use the following
+commands:
- $ git add <file>
- $ git commit --amend
- $ git push -f
+```
+$ git add <file>
+$ git commit --amend
+$ git push -f
+```
#### Closing the pull request
-Once you have applied all requested changes, the reviewers will merge your request.
+Once you have applied all requested changes, the reviewers will merge your
+request.
-If the pull request becomes inactive for some days, the reviewers may or may not warn you when they are about to close it.
-If it stays inactive further, it will be closed.
+If the pull request becomes inactive for some days, the reviewers may or may not
+warn you when they are about to close it. If it stays inactive further, it will
+be closed.
-Please abstain from temporarily closing a pull request while revising the templates. Instead, leave a comment on the PR describing what still needs work, or add "[WIP]" to the PR title. Only close your pull request if you're sure you don't want your changes to be included.
+Please abstain from temporarily closing a pull request while revising the
+templates. Instead, leave a comment on the PR describing what still needs work,
+or add "[WIP]" to the PR title. Only close your pull request if you're sure you
+don't want your changes to be included.
#### Publishing the package
-Once the reviewers have merged the pull request, our [build server](http://build.voidlinux.org) is automatically triggered and builds
-all packages in the pull request for all supported platforms. Upon completion, the packages are available to all Void Linux users.
+Once the reviewers have merged the pull request, our [build
+server](http://build.voidlinux.org) is automatically triggered and builds all
+packages in the pull request for all supported platforms. Upon completion, the
+packages are available to all Void Linux users.
From f272b4974f6a76f3b404f3c598170aee6cea99cc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Thu, 30 Apr 2020 22:42:29 -0300
Subject: [PATCH 2/6] CONTRIBUTING.md: update commit examples and PR process
- Add a commit example for shlibs modifications
- Explain the PR process a bit better, specially what needs to be
done when the packages involve a soname bump
---
CONTRIBUTING.md | 12 ++++++++----
1 file changed, 8 insertions(+), 4 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a55dda679ec..1a90e742ee0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -59,8 +59,11 @@ one of the following forms:
([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)).
- for package updates, use `<pkgname>: update to <version>.`
([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)).
-- for template modifications without a version change, use `<pkgname>: <reason>`
+- for template modifications without a version change, including removals, use
+ `<pkgname>: <reason>`
([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)).
+- for `common/shlibs` modifications, use `common/shlibs: <pkgname>`
+ ([example](https://github.com/void-linux/void-packages/commit/613651c91811cb4fd2e1a6be701c87072d759a9f)).
If you want to describe your changes in more detail, add an empty line followed
by those details
@@ -104,9 +107,10 @@ Once you have successfully built the package, you can start a pull request.
Most pull requests should only contain a single package and dependencies which
are not part of void-packages yet.
-If you make updates to packages containing a soname bump you also need to
-revbump all packages that are dependant. Those packages should also be part of
-the same pull request.
+If you make updates to packages containing a soname bump, you also need to
+update `common/shlibs` and revbump all packages that are dependant. There should
+be a commit for each package revbump, and those commits should be part of the
+same pull request.
When you make changes to your pull request, please *do not close and reopen your
pull request*. Instead, just forcibly git push, overwriting any old commits.
From 1bdc7e112862cc152c015c33b25aa4fcee15ddde Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Thu, 30 Apr 2020 23:02:20 -0300
Subject: [PATCH 3/6] Manual.md: use markdown anchors instead of HTML tags
Match some titles in the index to the titles in the document itself.
---
Manual.md | 197 ++++++++++++++++++------------------------------------
1 file changed, 65 insertions(+), 132 deletions(-)
diff --git a/Manual.md b/Manual.md
index 576b3d2032e..b1cf9f9dc20 100644
--- a/Manual.md
+++ b/Manual.md
@@ -5,73 +5,72 @@ packages for XBPS, the `Void Linux` native packaging system.
*Table of Contents*
-* [Introduction](#Introduction)
- * [Quality Requirements](#quality_requirements)
- * [Package build phases](#buildphase)
- * [Package naming conventions](#namingconvention)
- * [Libraries](#libs)
- * [Language Modules](#language_modules)
- * [Language Bindings](#language_bindings)
+* [Introduction](#introduction)
+ * [Quality Requirements](#quality-requirements)
+ * [Package build phases](#package-build-phases)
+ * [Package naming conventions](#package-naming-conventions)
+ * [Libraries](#libraries)
+ * [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)
- * [About the depends variables](#explain_depends)
+ * [Global functions](#global-functions)
+ * [Global variables](#global-variables)
+ * [Available variables](#available-variables)
+ * [Mandatory variables](#mandatory-variables)
+ * [Optional variables](#optional-variables)
+ * [About the many types of `depends` variables](#about-the-many-types-of-depends-variables)
* [Repositories](#repositories)
- * [Repositories defined by Branch](#repo_by_branch)
- * [Package defined repositories](#pkg_defined_repo)
- * [Checking for new upstream releases](#updates)
- * [Handling patches](#patches)
- * [Build style scripts](#build_scripts)
- * [Build helper scripts](#build_helper)
+ * [Repositories defined by Branch](#repositories-defined-by-branch)
+ * [Package defined Repositories](#package-defined-repositories)
+ * [Checking for new upstream releases](#checking-for-new-upstream-releases)
+ * [Handling patches](#handling-patches)
+ * [build\_style scripts](#build_style-scripts)
+ * [build\_helper scripts](#build_helper-scripts)
* [Functions](#functions)
- * [Build options](#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)
- * [Writing runit services](#writing_runit_services)
- * [32bit packages](#32bit_pkgs)
- * [Subpackages](#pkgs_sub)
- * [Development packages](#pkgs_development)
- * [Data packages](#pkgs_data)
- * [Documentation packages](#pkgs_documentation)
- * [Python packages](#pkgs_python)
- * [Go packages](#pkgs_go)
- * [Haskell packages](#pkgs_haskell)
- * [Font packages](#pkgs_font)
- * [Removing a package](#pkg_remove)
- * [XBPS Triggers](#xbps_triggers)
- * [appstream-cache](#triggers_appstream_cache)
- * [binfmts](#triggers_binfmts)
- * [dkms](#triggers_dkms)
- * [gconf-schemas](#triggers_gconf_schemas)
- * [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders)
- * [gio-modules](#triggers_gio_modules)
- * [gettings-schemas](#triggers_gsettings_schemas)
- * [gtk-icon-cache](#triggers_gtk_icon_cache)
- * [gtk-immodules](#triggers_gtk_immodules)
- * [gtk-pixbuf-loaders](#triggers_gtk_pixbuf_loaders)
- * [gtk3-immodules](#triggers_gtk3_immodules)
- * [hwdb.d-dir](#triggers_hwdb.d_dir)
- * [info-files](#triggers_info_files)
- * [kernel-hooks](#triggers_kernel_hooks)
- * [mimedb](#triggers_mimedb)
- * [mkdirs](#triggers_mkdirs)
- * [pango-modules](#triggers_pango_module)
- * [pycompile](#triggers_pycompile)
- * [register-shell](#triggers_register_shell)
- * [system-accounts](#triggers_system_accounts)
- * [update-desktopdb](#triggers_update_desktopdb)
- * [x11-fonts](#triggers_x11_fonts)
- * [xml-catalog](#triggers_xml_catalog)
+ * [Build options](#build-options)
+ * [Runtime dependencies](#runtime-dependencies)
+ * [INSTALL and REMOVE files](#install-and-remove-files)
+ * [INSTALL.msg and REMOVE.msg files](#installmsg-and-removemsg-files)
+ * [Creating system accounts/groups at runtime](#creating-system-accountsgroups-at-runtime)
+ * [Writing runit services](#writing-runit-services)
+ * [32bit packages](#32bit-packages)
+ * [Subpackages](#subpackages)
+ * [Development packages](#development-packages)
+ * [Data packages](#data-packages)
+ * [Documentation packages](#documentation-packages)
+ * [Python packages](#python-packages)
+ * [Go packages](#go-packages)
+ * [Haskell packages](#haskell-packages)
+ * [Font packages](#font-packages)
+ * [Removing a package](#removing-a-package)
+ * [XBPS Triggers](#xbps-triggers)
+ * [appstream-cache](#appstream-cache)
+ * [binfmts](#binfmts)
+ * [dkms](#dkms)
+ * [gconf-schemas](#gconf-schemas)
+ * [gdk-pixbuf-loaders](#gdk-pixbuf-loaders)
+ * [gio-modules](#gio-modules)
+ * [gettings-schemas](#gsettings-schemas)
+ * [gtk-icon-cache](#gtk-icon-cache)
+ * [gtk-immodules](#gtk-immodules)
+ * [gtk-pixbuf-loaders](#gtk-pixbuf-loaders)
+ * [gtk3-immodules](#gtk3-immodules)
+ * [hwdb.d-dir](#hwdbd-dir)
+ * [info-files](#info-files)
+ * [kernel-hooks](#kernel-hooks)
+ * [mimedb](#mimedb)
+ * [mkdirs](#mkdirs)
+ * [pango-modules](#pango-modules)
+ * [pycompile](#pycompile)
+ * [register-shell](#register-shell)
+ * [system-accounts](#system-accounts)
+ * [update-desktopdb](#update-desktopdb)
+ * [x11-fonts](#x11-fonts)
+ * [xml-catalog](#xml-catalog)
* [Notes](#notes)
- * [Contributing via git](#contributing)
+ * [Contributing via git](#contributing-via-git)
* [Help](#help)
-<a id="Introduction"></a>
## Introduction
The `void-packages` repository contains all `source` packages that are the
@@ -117,7 +116,6 @@ If everything went fine after running
a binary package named `foo-1.0_1.<arch>.xbps` will be generated in the local repository
`hostdir/binpkgs`.
-<a id="quality_requirements"></a>
### Quality Requirements
Follow this list to determine if a piece of software or other technology may be
@@ -135,7 +133,6 @@ the Void packages system.
1. Required: Another package either within the repository or pending inclusion
requires the package.
-<a id="buildphase"></a>
### Package build phases
Building a package consist of the following phases:
@@ -169,10 +166,8 @@ via `make install` or any other compatible method.
successfully, the phase will be skipped later (unless its work directory
`${wrksrc}` is removed with `xbps-src clean`).
-<a id="namingconventions"></a>
### Package naming conventions
-<a id="libs"></a>
#### Libraries
Libraries are packages which provide shared objects (\*.so) in /usr/lib.
@@ -196,7 +191,6 @@ a linked program.
against this package. If the library is a sub package, its corresponding
development package should be named `lib<name>-devel`
-<a id="language_modules"></a>
#### Language Modules
Language modules are extensions to script or compiled languages. Those packages
@@ -217,7 +211,6 @@ for the language prefix.
Example: python-pam, perl-URI, python3-pyside2
-<a id="language_bindings"></a>
#### Language Bindings
Language Bindings are packages which allow programs or libraries to have
@@ -230,7 +223,6 @@ The naming convention to those packages is:
Example: gimp-python, irssi-perl
-<a id="programs"></a>
#### Programs
Programs put executables under /usr/bin (or in very special cases in other
@@ -246,7 +238,6 @@ Programs can be split into program packages and library packages. The program
package should be named as described above. The library package should be
prefixed with "lib" (see section `Libraries`)
-<a id="global_funcs"></a>
### Global functions
The following functions are defined by `xbps-src` and can be used on any template:
@@ -305,12 +296,11 @@ The following functions are defined by `xbps-src` and can be used on any templat
`$DESTDIR`. The optional 2nd argument can be used to change the
`file name`.
-- <a id="vlicense"></a>
*vlicense()* `vlicense <file> [<name>]`
Installs `file` into `usr/share/licenses/<pkgname>` in the pkg
`$DESTDIR`. The optional 2nd argument can be used to change the
- `file name`. See [license](#var_license) for when to use it.
+ `file name`. See [license](#mandatory-license) for when to use it.
- *vsv()* `vsv <service>`
@@ -333,7 +323,6 @@ The following functions are defined by `xbps-src` and can be used on any templat
> Shell wildcards must be properly quoted, Example: `vmove "usr/lib/*.a"`.
-<a id="global_vars"></a>
### Global variables
The following variables are defined by `xbps-src` and can be used on any template:
@@ -393,10 +382,8 @@ in this directory such as `${XBPS_BUILDDIR}/${wrksrc}`.
- `XBPS_RUST_TARGET` The target architecture triplet used by `rustc` and `cargo`.
-<a id="available_vars"></a>
### Available variables
-<a id="mandatory_vars"></a>
#### Mandatory variables
The list of mandatory variables for a template:
@@ -404,8 +391,7 @@ The list of mandatory variables for a template:
- `homepage` A string pointing to the `upstream` homepage.
-- <a id="var_license"></a>
-`license` A string matching the license's [SPDX Short identifier](https://spdx.org/licenses),
+- `license` A string matching the license's [SPDX Short identifier](https://spdx.org/licenses),
`Public Domain`, or string prefixed with `custom:` for other licenses.
Multiple licenses should be separated by commas, Example: `GPL-3.0-or-later, custom:Hugware`.
@@ -432,7 +418,6 @@ the generated `binary packages` have been modified.
- `version` A string with the package version. Must not contain dashes or underscore
and at least one digit is required. Shell's variable substition usage is not allowed.
-<a id="optional_vars"></a>
#### Optional variables
- `hostmakedepends` The list of `host` dependencies required to build the package, and
@@ -702,8 +687,7 @@ Examples:
archs=noarch
```
-<a id="explain_depends"></a>
-#### About the many types of `depends` variable.
+#### About the many types of `depends` variables
So far we have listed four types of `depends`, there are `hostmakedepends`,
`makedepends`, `checkdepends` and plain old `depends`.To understand the difference
@@ -734,10 +718,8 @@ Finally, as a general rule, if something compiles the exact same way whether or
not you add a particular package to `makedepends` or `hostmakedepends`, it
shouldn't be added.
-<a id="repositories"></a>
#### Repositories
-<a id="repo_by_branch"></a>
##### Repositories defined by Branch
The global repository takes the name of
@@ -745,7 +727,6 @@ 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
update multiple packages in a second branch without polluting his local repository.
-<a id="pkg_defined_repo"></a>
##### Package defined Repositories
The second way to define a repository is by setting the `repository` variable in
@@ -758,7 +739,6 @@ The following repository names are valid:
* `nonfree`: Repository for closed source packages.
-<a id="updates"></a>
### Checking for new upstream releases
New upstream versions can be automatically checked using
@@ -797,7 +777,6 @@ in url. Defaults to `(|v|$pkgname)[-_.]*`.
part that follows numeric part of version directory
in url. Defaults to `(|\.x)`.
-<a id="patches"></a>
### Handling patches
Sometimes software needs to be patched, most commonly to fix bugs that have
@@ -820,8 +799,7 @@ be used to set the args passed to `patch(1)`. As an example, if `foo.patch` requ
special arguments to be passed to `patch(1)` that can't be used when applying other
patches, `foo.patch.args` can be created containing those args.
-<a id="build_scripts"></a>
-### build style scripts
+### 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
@@ -933,8 +911,7 @@ matching the `build_style` name, Example:
`common/environment/build-style/gnu-configure.sh`
-<a id="build_helper"></a>
-### build helper scripts
+### build\_helper scripts
The `build_helper` variable specifies shell snippets to be sourced that will create a
suitable environment for working with certain sets of packages.
@@ -963,7 +940,6 @@ This aims to fix cross-builds for when the build-style is mixed: e.g. when in a
`gnu-configure` style the configure script calls `qmake` or a `Makefile` in
`gnu-makefile` style, respectively.
-<a id="functions"></a>
### Functions
The following functions can be defined to change the behavior of how the
@@ -1022,7 +998,6 @@ Current working directory for functions is set as follows:
- For pre_configure through post_install: `build_wrksrc`
if it is defined, otherwise `wrksrc`.
-<a id="build_options"></a>
### Build options
Some packages might be built with different build options to enable/disable
@@ -1127,7 +1102,6 @@ Example: `XBPS_PKG_OPTIONS_xorg_server=opt`.
The list of supported package build options and its description is defined in the
`common/options.description` file.
-<a id="deps_runtime"></a>
#### Runtime dependencies
Dependencies for ELF objects are detected automatically by `xbps-src`, hence runtime
@@ -1167,7 +1141,6 @@ 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
when the package is being built with `xbps-src`.
-<a id="install_remove_files"></a>
### INSTALL and REMOVE files
The INSTALL and REMOVE shell snippets can be used to execute certain actions at a specified
@@ -1211,7 +1184,6 @@ be executed via `chroot(2)` won't work correctly.
> NOTE: do not use INSTALL/REMOVE scripts to print messages, see the next section for
more information.
-<a id="install_remove_files_msg"></a>
### INSTALL.msg and REMOVE.msg files
The `INSTALL.msg` and `REMOVE.msg` files can be used to print a message at post-install
@@ -1222,7 +1194,6 @@ 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
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
There's a trigger along with some variables that are specifically to create
@@ -1254,7 +1225,6 @@ accounts.
> NOTE: The underscore policy does not apply to old packages, due to the inevitable breakage of
> changing the username only new packages should follow it.
-<a id="writing_runit_services"></a>
### Writing runit services
Void Linux uses [runit](http://smarden.org/runit/) for booting and supervision of services.
@@ -1293,7 +1263,6 @@ If the service requires directories in parts of the system that are not generall
temporary filesystems. Then use the `make_dirs` variable in the template to create
those directories when the package is installed.
-<a id="32bit_pkgs"></a>
### 32bit packages
32bit packages are built automatically when the builder is x86 (32bit), but
@@ -1315,7 +1284,6 @@ This expects the basename of the target file, Example: `lib32symlinks="foo"`.
- `lib32mode` If unset, only shared/static libraries and pkg-config files will be copied to the
**32bit** package. If set to `full` all files will be copied to the 32bit package, unmodified.
-<a id="pkgs_sub"></a>
### Subpackages
In the example shown above just a binary package is generated, but with some
@@ -1375,7 +1343,6 @@ destdir (`$DESTDIR`) to the `subpackage` destdir (`$PKGDESTDIR`).
Subpackages are processed always in alphabetical order; To force a custom order,
the `subpackages` variable can be declared with the wanted order.
-<a id="pkgs_development"></a>
### Development packages
A development package, commonly generated as a subpackage, shall only contain
@@ -1405,7 +1372,6 @@ following subset of files from the main package:
* Gobject introspection XML files `usr/share/gir-1.0`
* Vala bindings `usr/share/vala`
-<a id="pkgs_data"></a>
### Data packages
Another common subpackage type is the `-data` subpackage. This subpackage
@@ -1417,7 +1383,6 @@ or card material (maps). Data subpackages are almost always `archs=noarch`.
The main package must then have `depends="${pkgname}-data-${version}_${revision}"`,
possibly in addition to other, non-automatic depends.
-<a id="pkgs_documentation"></a>
### Documentation packages
Packages intended for user interaction do not always unconditionally require
@@ -1432,7 +1397,6 @@ building packages depending on a specific package there is no need to install la
amounts of documentation for no reason. Thus the size of the documentation part should
be your guidance to decide whether or not to split off a `-doc` subpackage.
-<a id="pkgs_python"></a>
### Python packages
Python packages should be built with the `python{,2,3}-module` build style, if possible.
@@ -1481,7 +1445,6 @@ Also, a set of useful variables are defined to use in the templates:
> NOTE: it's expected that additional subpkgs must be generated to allow packaging for multiple
python versions.
-<a id="pkgs_go"></a>
### Go packages
Go packages should be built with the `go` build style, if possible.
@@ -1518,7 +1481,6 @@ otherwise preping some assets. If possible do this in pre_build().
The path to the package's source inside `$GOPATH` is available as
`$GOSRCPATH`.
-<a id="pkgs_haskell"></a>
### Haskell packages
We build Haskell package using `stack` from
@@ -1536,7 +1498,6 @@ The following variables influence how Haskell packages are built:
- `make_build_args`: This is passed as-is to `stack build ...`, so
you can add your `--flag ...` parameters there.
-<a id="pkgs_font"></a>
### Font packages
Font packages are very straightforward to write, they are always set with the
@@ -1548,7 +1509,6 @@ cache during the install/removal of the package
- `font_dirs`: which should be set to the directory where the package
installs its fonts
-<a id="pkg_remove"></a>
### Removing a package
Follows a list of things that should be done to help guarantee that a
@@ -1576,7 +1536,6 @@ the source of those patches/files.
- Remove the package from the repository index
or contact a team member that can do so.
-<a id="xbps_triggers"></a>
### XBPS Triggers
XBPS triggers are a collection of snippets of code, provided by the `xbps-triggers`
@@ -1591,7 +1550,6 @@ package.
This is not a complete overview of the package. It is recommended to read the variables
referenced and the triggers themselves.
-<a id="triggers_appstream_cache"></a>
#### appstream-cache
The appstream-cache trigger is responsible for rebuilding the appstream metadata cache.
@@ -1613,7 +1571,6 @@ directory.
It is automatically added to packages that have XML files under one of the directories
searched by appstreamcli.
-<a id="triggers_binfmts"></a>
#### binfmts
The binfmts trigger is responsible for registration and removal of arbitrary
@@ -1625,7 +1582,6 @@ to register/remove entries from the arbitrary executable binary formats database
To include the trigger use the `binfmts` variable, as the trigger won't do anything unless
it is defined.
-<a id="triggers_dkms"></a>
#### dkms
The dkms trigger is responsible for compiling and removing dynamic kernel modules of a
@@ -1638,7 +1594,6 @@ the corresponding module will be removed
To include the trigger use the `dkms_modules` variable, as the trigger won't do anything
unless it is defined.
-<a id="triggers_gconf_schemas"></a>
#### gconf-schemas
The gconf-schemas trigger is responsible for registering and removing .schemas and
@@ -1655,7 +1610,6 @@ It is automatically added to packages that have `/usr/share/gconf/schemas` prese
as a directory. All files with the schemas file extension under that directory
are passed to the trigger.
-<a id="triggers_gdk_pixbuf_loaders"></a>
#### gdk-pixbuf-loaders
The gdk-pixbuf-loaders trigger is responsible for maintaining the GDK Pixbuf loaders cache.
@@ -1669,7 +1623,6 @@ It can be added by defining `gdk-pixbuf-loaders` in the `triggers` variable. It
added automatically to any package that has the path `usr/lib/gdk-pixbuf-2.0/2.10.0/loaders`
available as a directory.
-<a id="triggers_gio_modules"></a>
#### gio-modules
The gio-modules trigger is responsible for updating the Glib GIO module cache with
@@ -1681,7 +1634,6 @@ present under `usr/lib/gio/modules`.
It is automatically added to packages that have `/usr/lib/gio/modules` present
as a directory.
-<a id="triggers_gsettings_schemas"></a>
#### gsettings-schemas
The gsettings-schemas trigger is responsible for compiling Glib's GSettings XML
@@ -1696,7 +1648,6 @@ During removal of the glib package it deletes all files inside
It is automatically added to packages that have `/usr/share/glib-2.0/schemas` present
as a directory.
-<a id="triggers_gtk_icon_cache"></a>
#### gtk-icon-cache
The gtk-icon-cache trigger is responsible for updating the gtk+ icon cache.
@@ -1710,7 +1661,6 @@ It is automatically added on packages that have `/usr/share/icons` available
as a directory, all directories under that directory have their absolute path
passed to the trigger.
-<a id="triggers_gtk_immodules"></a>
#### gtk-immodules
The gtk-immodules trigger is responsible for updating the IM (Input Method) modules
@@ -1726,7 +1676,6 @@ During removal of the `gtk+` package it removes the cache file which is located
It is automatically added to packages that have `/usr/lib/gtk-2.0/2.10.0/immodules`
present as a directory.
-<a id="triggers_gtk_pixbuf_loaders"></a>
#### gtk-pixbuf-loaders
gtk-pixbuf-loaders is the old name for the current `gdk-pixbuf-loaders` trigger and is
@@ -1735,7 +1684,6 @@ compatibility measure.
For information about how it works refer to [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders).
-<a id="triggers_gtk3_immodules"></a>
#### gtk3-immodules
The gtk3-immodules trigger is responsible for updating the IM (Input Method) modules
@@ -1751,7 +1699,6 @@ During removal of the `gtk+3` package it removes the cache file which is located
It is automatically added to packages that have `/usr/lib/gtk-3.0/3.0.0/immodules`
present as a directory.
-<a id="triggers_hwdb.d_dir"></a>
#### hwdb.d-dir
The hwdb.d-dir trigger is responsible for updating the hardware database.
@@ -1761,7 +1708,6 @@ During installation and removal it runs `usr/bin/udevadm hwdb --root=. --update`
It is automatically added to packages that have `/usr/lib/udev/hwdb.d` present
as a directory.
-<a id="triggers_info_files"></a>
#### info-files
The info-files trigger is responsible for registering and unregistering the GNU info
@@ -1779,7 +1725,6 @@ registry located at `usr/share/info`.
If it is running under another architecture it tries to use the host's `install-info`
utility.
-<a id="triggers_kernel_hooks"></a>
#### kernel-hooks
The kernel-hooks trigger is responsible for running scripts during installation/removal
@@ -1797,7 +1742,6 @@ target.
It is automatically added if the helper variable `kernel_hooks_version` is defined.
However it is not obligatory to have it defined.
-<a id="triggers_mimedb"></a>
#### mimedb
The mimedb trigger is responsible for updating the shared-mime-info database.
@@ -1807,7 +1751,6 @@ In all runs it will just execute `update-mime-database -n usr/share/mime`.
It is automatically added to packages that have `/usr/share/mime` available as
a directory.
-<a id="triggers_mkdirs"></a>
#### mkdirs
The mkdirs trigger is responsible for creating and removing directories dictated
@@ -1832,7 +1775,6 @@ During removal it will delete the directory using `rmdir`.
To include this trigger use the `make_dirs` variable, as the trigger won't do anything
unless it is defined.
-<a id="triggers_pango_module"></a>
#### pango-modules
The pango-modules trigger is currently being removed since upstream has removed the
@@ -1846,7 +1788,6 @@ Currently it removes `etc/pango/pango.modules` file during removal of the pango
It can be added by defining `pango-modules` in the `triggers` variable and has no way to get
added automatically to a package.
-<a id="triggers_pycompile"></a>
#### pycompile
The pycompile trigger is responsible for compiling python code into native
@@ -1863,7 +1804,6 @@ trigger won't do anything unless at least one of those variables is defined.
A `python_version` variable can be set to direct behaviour of the trigger.
-<a id="triggers_register_shell"></a>
#### register-shell
The register-shell trigger is responsible for registering and removing shell entries
@@ -1877,7 +1817,6 @@ During removal it will use `sed` to delete the shell from the file.
To include this trigger use the `register_shell` variable, as the trigger won't do
anything unless it is defined.
-<a id="triggers_system_accounts"></a>
#### system-accounts
The system-accounts trigger is responsible for creating and disabling system accounts
@@ -1890,7 +1829,6 @@ Example: `transmission unprivileged user - for uninstalled package transmission`
This trigger can only be used by using the `system_accounts` variable.
-<a id="triggers_update_desktopdb"></a>
#### update-desktopdb
The update-desktopdb trigger is responsible for updating the system's MIME database.
@@ -1904,7 +1842,6 @@ was created during installation.
It is automatically added to packages that have `/usr/share/applications` available as
a directory.
-<a id="triggers_x11_fonts"></a>
#### x11-fonts
The x11-fonts trigger is responsible for rebuilding the fonts.dir and fonts.scale files
@@ -1916,7 +1853,6 @@ all font directories it was given via the `font_dirs` variable.
To include this trigger use the `font_dirs` variable, as the trigger won't do anything
unless it is defined.
-<a id="triggers_xml_catalog"></a>
#### xml-catalog
The xml-catalog trigger is responsible for registering and removing SGML/XML catalog entries.
@@ -1932,7 +1868,6 @@ During removal it uses `xmlcatmgr` to remove all catalogs passed to it by the
To include this trigger use the `sgml_entries` variable or/and the `xml_entries` variable,
as the trigger won't do anything unless either of them are defined.
-<a id="notes"></a>
### Notes
- Make sure that all software is configured to use the `/usr` prefix.
@@ -1951,7 +1886,6 @@ 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;
otherwise the `debug` packages won't have debugging symbols.
-<a id="contributing"></a>
### Contributing via git
Fork the voidlinux `void-packages` git repository on github and clone it:
@@ -1971,7 +1905,6 @@ to pull in new changes:
$ git remote add upstream git://github.com/void-linux/void-packages.git
$ git pull upstream master
-<a id="help"></a>
## Help
If after reading this `manual` you still need some kind of help, please join
From 24835096548cd3e228c15388615742fb3162aaa2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Mon, 4 May 2020 10:55:53 -0300
Subject: [PATCH 4/6] README.md: use markdown anchors instead of HTML flags
---
README.md | 41 ++++++++++++-----------------------------
1 file changed, 12 insertions(+), 29 deletions(-)
diff --git a/README.md b/README.md
index 752fb3d4fdc..47ad8f25252 100644
--- a/README.md
+++ b/README.md
@@ -17,22 +17,22 @@ for details of how to create source packages.
- [Requirements](#requirements)
- [Quick start](#quick-start)
- [chroot methods](#chroot-methods)
-- [Install the bootstrap packages](#install-bootstrap)
+- [Install the bootstrap packages](#install-the-bootstrap-packages)
- [Configuration](#configuration)
- [Directory hierarchy](#directory-hierarchy)
- [Building packages](#building-packages)
-- [Package build options](#build-options)
-- [Sharing and signing your local repositories](#sharing-and-signing)
-- [Rebuilding and overwriting existing local packages](#rebuilding)
-- [Enabling distcc for distributed compilation](#distcc)
+- [Package build options](#package-build-options)
+- [Sharing and signing your local repositories](#sharing-and-signing-your-local-repositories)
+- [Rebuilding and overwriting existing local packages](#rebuilding-and-overwriting-existing-local-packages)
+- [Enabling distcc for distributed compilation](#enabling-distcc-for-distributed-compilation)
- [Distfiles mirrors](#distfiles-mirrors)
-- [Cross compiling packages for a target architecture](#cross-compiling)
-- [Using xbps-src in a foreign Linux distribution](#foreign)
-- [Remaking the masterdir](#remaking-masterdir)
-- [Keeping your masterdir uptodate](#updating-masterdir)
-- [Building 32bit packages on x86_64](#building-32bit)
-- [Building packages natively for the musl C library](#building-for-musl)
-- [Building void base-system from scratch](#building-base-system)
+- [Cross compiling packages for a target architecture](#cross-compiling-packages-for-a-target-architecture)
+- [Using xbps-src in a foreign Linux distribution](#using-xbps-src-in-a-foreign-linux-distribution)
+- [Remaking the masterdir](#remaking-the-masterdir)
+- [Keeping your masterdir uptodate](#keeping-your-masterdir-uptodate)
+- [Building 32bit packages on x86\_64](#building-32bit-packages-on-x86_64)
+- [Building packages natively for the musl C library](#building-packages-natively-for-the-musl-c-library)
+- [Building void base-system from scratch](#building-void-base-system-from-scratch)
### Requirements
@@ -58,7 +58,6 @@ multiple utilities to accomplish this task:
> NOTE: `xbps-src` does not allow building as root anymore. Use one of the chroot
methods shown above.
-<a name="quick-start"></a>
### Quick start
Clone the `void-packages` git repository and install the bootstrap packages:
@@ -95,7 +94,6 @@ Alternatively, packages can be installed with the `xi` utility, from the `xtools
# xi <package_name>
```
-<a name="chroot-methods"></a>
### chroot methods
#### xbps-uunshare(1) (default)
@@ -149,7 +147,6 @@ To enable it:
$ cd void-packages
$ echo XBPS_CHROOT_CMD=proot >> etc/conf
-<a name="install-bootstrap"></a>
### Install the bootstrap packages
The `bootstrap` packages are a set of packages required to build any available source package in a container. There are two methods to install the `bootstrap`:
@@ -185,7 +182,6 @@ used as dependencies in the source packages tree.
If you want to customize those replacements, copy `etc/defaults.virtual` to `etc/virtual`
and edit it accordingly to your needs.
-<a name="directory-hierarchy"></a>
### Directory hierarchy
The following directory hierarchy is used with a default configuration file:
@@ -222,7 +218,6 @@ The description of these directories is as follows:
- `hostdir/sources`: to store package sources.
- `hostdir/binpkgs`: local repository to store generated binary packages.
-<a name="building-packages"></a>
### Building packages
The simplest form of building package is accomplished by running the `pkg` target in `xbps-src`:
@@ -249,7 +244,6 @@ It is possible to avoid using remote repositories completely by using the `-N` f
> The default local repository may contain multiple *sub-repositories*: `debug`, `multilib`, etc.
-<a name="build-options"></a>
### Package build options
The supported build options for a source package can be shown with `xbps-src show-options`:
@@ -289,7 +283,6 @@ i.e `XBPS_PKG_OPTIONS_xorg_server=opt`.
The list of supported package build options and its description is defined in the
`common/options.description` file or in the `template` file.
-<a name="sharing-and-signing"></a>
### Sharing and signing your local repositories
To share a local repository remotely it's mandatory to sign it and the binary packages
@@ -327,7 +320,6 @@ Each time a binary package is created, a package signature must be created with
> It is not possible to sign a repository with multiple RSA keys.
-<a name="rebuilding"></a>
### Rebuilding and overwriting existing local packages
If for whatever reason a package has been built and it is available in your local repository
@@ -343,7 +335,6 @@ Reinstalling this package in your target `rootdir` can be easily done too:
> Please note that the `package expression` must be properly defined to explicitly pick up
the package from the desired repository.
-<a name="distcc"></a>
### Enabling distcc for distributed compilation
Setup the slaves (machines that will compile the code):
@@ -374,7 +365,6 @@ The slave 192.168.2.101 has a CPU with 8 cores and the /9 for the number of jobs
The slave 192.168.2.102 is set to run at most 2 compile jobs to keep its load low, even if its CPU has 4 cores.
The XBPS_MAKEJOBS setting is increased to 16 to account for the possible parallelism (2 + 9 + 2 + some slack).
-<a name="distfiles-mirrors"></a>
### Distfiles mirror(s)
In etc/conf you may optionally define a mirror or a list of mirrors to search for distfiles.
@@ -399,7 +389,6 @@ using the `file://` prefix or simply an absolute path on your build host (e.g. /
Mirror locations specified this way are bind mounted inside the chroot environment
under $XBPS_MASTERDIR and searched for distfiles just the same as remote locations.
-<a name="cross-compiling"></a>
### Cross compiling packages for a target architecture
Currently `xbps-src` can cross build packages for some target architectures with a cross compiler.
@@ -411,7 +400,6 @@ If a source package has been adapted to be **cross buildable** `xbps-src` will a
If the build for whatever reason fails, might be a new build issue or simply because it hasn't been adapted to be **cross compiled**.
-<a name="foreign"></a>
### Using xbps-src in a foreign Linux distribution
xbps-src can be used in any recent Linux distribution matching the CPU architecture.
@@ -439,7 +427,6 @@ and `xbps-src` should be fully functional; just start the `bootstrap` process, i
The default masterdir is created in the current working directory, i.e `void-packages/masterdir`.
-<a name="remaking-masterdir"></a>
### Remaking the masterdir
If for some reason you must update xbps-src and the `bootstrap-update` target is not enough, it's possible to recreate a masterdir with two simple commands (please note that `zap` keeps your `ccache/distcc/host` directories intact):
@@ -447,14 +434,12 @@ If for some reason you must update xbps-src and the `bootstrap-update` target is
$ ./xbps-src zap
$ ./xbps-src binary-bootstrap
-<a name="updating-masterdir"></a>
### Keeping your masterdir uptodate
Sometimes the bootstrap packages must be updated to the latest available version in repositories, this is accomplished with the `bootstrap-update` target:
$ ./xbps-src bootstrap-update
-<a name="building-32bit"></a>
### Building 32bit packages on x86_64
Two ways are available to build 32bit packages on x86\_64:
@@ -471,7 +456,6 @@ The second mode (native) needs a new x86 `masterdir`:
$ ./xbps-src -m masterdir-x86 binary-bootstrap i686
$ ./xbps-src -m masterdir-x86 ...
-<a name="building-for-musl"></a>
### Building packages natively for the musl C library
A native build environment is required to be able to cross compile the bootstrap packages for the musl C library; this is accomplished by installing them via `binary-bootstrap`:
@@ -493,7 +477,6 @@ Your new masterdir is now ready to build packages natively for the musl C librar
To see if the musl C dynamic linker is working as expected.
-<a name="building-base-system"></a>
### Building void base-system from scratch
To rebuild all packages in `base-system` for your native architecture:
From 2d789bb60d453d76389633f117a35641b32a4fea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Mon, 4 May 2020 11:03:29 -0300
Subject: [PATCH 5/6] README.md: format with vmdfmt
---
README.md | 581 +++++++++++++++++++++++++++++++++---------------------
1 file changed, 358 insertions(+), 223 deletions(-)
diff --git a/README.md b/README.md
index 47ad8f25252..afe50b766be 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,18 @@
## The XBPS source packages collection
-This repository contains the XBPS source packages collection to build binary packages
-for the Void Linux distribution.
+This repository contains the XBPS source packages collection to build binary
+packages for the Void Linux distribution.
-The included `xbps-src` script will fetch and compile the sources, and install its
-files into a `fake destdir` to generate XBPS binary packages that can be installed
-or queried through the `xbps-install(1)` and `xbps-query(1)` utilities, respectively.
+The included `xbps-src` script will fetch and compile the sources, and install
+its files into a `fake destdir` to generate XBPS binary packages that can be
+installed or queried through the `xbps-install(1)` and `xbps-query(1)`
+utilities, respectively.
-See [Contributing](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
+See
+[Contributing](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
for a general overview of how to contribute and the
-[Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md)
-for details of how to create source packages.
+[Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md) for
+details of how to create source packages.
### Table of Contents
@@ -22,17 +24,24 @@ for details of how to create source packages.
- [Directory hierarchy](#directory-hierarchy)
- [Building packages](#building-packages)
- [Package build options](#package-build-options)
-- [Sharing and signing your local repositories](#sharing-and-signing-your-local-repositories)
-- [Rebuilding and overwriting existing local packages](#rebuilding-and-overwriting-existing-local-packages)
-- [Enabling distcc for distributed compilation](#enabling-distcc-for-distributed-compilation)
+- [Sharing and signing your local
+ repositories](#sharing-and-signing-your-local-repositories)
+- [Rebuilding and overwriting existing local
+ packages](#rebuilding-and-overwriting-existing-local-packages)
+- [Enabling distcc for distributed
+ compilation](#enabling-distcc-for-distributed-compilation)
- [Distfiles mirrors](#distfiles-mirrors)
-- [Cross compiling packages for a target architecture](#cross-compiling-packages-for-a-target-architecture)
-- [Using xbps-src in a foreign Linux distribution](#using-xbps-src-in-a-foreign-linux-distribution)
+- [Cross compiling packages for a target
+ architecture](#cross-compiling-packages-for-a-target-architecture)
+- [Using xbps-src in a foreign Linux
+ distribution](#using-xbps-src-in-a-foreign-linux-distribution)
- [Remaking the masterdir](#remaking-the-masterdir)
- [Keeping your masterdir uptodate](#keeping-your-masterdir-uptodate)
-- [Building 32bit packages on x86\_64](#building-32bit-packages-on-x86_64)
-- [Building packages natively for the musl C library](#building-packages-natively-for-the-musl-c-library)
-- [Building void base-system from scratch](#building-void-base-system-from-scratch)
+- [Building 32bit packages on x86_64](#building-32bit-packages-on-x86_64)
+- [Building packages natively for the musl C
+ library](#building-packages-natively-for-the-musl-c-library)
+- [Building void base-system from
+ scratch](#building-void-base-system-from-scratch)
### Requirements
@@ -45,18 +54,22 @@ for details of how to create source packages.
- objcopy(1), objdump(1), strip(1): binutils
- other common POSIX utilities included by default in almost all UNIX systems.
-`xbps-src` requires a utility to chroot and bind mount existing directories
-into a `masterdir` that is used as its main `chroot` directory. `xbps-src` supports
+`xbps-src` requires a utility to chroot and bind mount existing directories into
+a `masterdir` that is used as its main `chroot` directory. `xbps-src` supports
multiple utilities to accomplish this task:
- - `bwrap` - bubblewrap, see https://github.com/projectatomic/bubblewrap.
- - `ethereal` - only useful for one-shot containers, i.e docker (used with travis).
- - `xbps-uunshare(1)` - XBPS utility that uses `user_namespaces(7)` (part of xbps, default).
- - `xbps-uchroot(1)` - XBPS utility that uses `namespaces` and must be `setgid` (part of xbps).
- - `proot(1)` - utility that implements chroot/bind mounts in user space, see https://proot-me.github.io/.
+- `bwrap` - bubblewrap, see https://github.com/projectatomic/bubblewrap.
+- `ethereal` - only useful for one-shot containers, i.e docker (used with
+ travis).
+- `xbps-uunshare(1)` - XBPS utility that uses `user_namespaces(7)` (part of
+ xbps, default).
+- `xbps-uchroot(1)` - XBPS utility that uses `namespaces` and must be `setgid`
+ (part of xbps).
+- `proot(1)` - utility that implements chroot/bind mounts in user space, see
+ https://proot-me.github.io/.
-> NOTE: `xbps-src` does not allow building as root anymore. Use one of the chroot
-methods shown above.
+> NOTE: `xbps-src` does not allow building as root anymore. Use one of the
+> chroot methods shown above.
### Quick start
@@ -82,13 +95,16 @@ To build packages marked as 'restricted', modify `etc/conf`:
$ echo XBPS_ALLOW_RESTRICTED=yes >> etc/conf
```
-Once built, the package will be available in `hostdir/binpkgs` or an appropriate subdirectory (e.g. `hostdir/binpkgs/nonfree`). To install the package:
+Once built, the package will be available in `hostdir/binpkgs` or an appropriate
+subdirectory (e.g. `hostdir/binpkgs/nonfree`). To install the package:
```
# xbps-install --repository hostdir/binpkgs <package_name>
```
-Alternatively, packages can be installed with the `xi` utility, from the `xtools` package. `xi` takes the repository of the current working directory into account.
+Alternatively, packages can be installed with the `xi` utility, from the
+`xtools` package. `xi` takes the repository of the current working directory
+into account.
```
# xi <package_name>
@@ -100,380 +116,492 @@ Alternatively, packages can be installed with the `xi` utility, from the `xtools
This utility requires these Linux kernel options:
-- CONFIG\_NAMESPACES
-- CONFIG\_IPC\_NS
-- CONFIG\_UTS\_NS
-- CONFIG\_USER\_NS
+- CONFIG_NAMESPACES
+- CONFIG_IPC_NS
+- CONFIG_UTS_NS
+- CONFIG_USER_NS
-This is the default method, and if your system does not support any of the required kernel
-options it will fail with `EINVAL (Invalid argument)`.
+This is the default method, and if your system does not support any of the
+required kernel options it will fail with `EINVAL (Invalid argument)`.
#### xbps-uchroot(1)
This utility requires these Linux kernel options:
-- CONFIG\_NAMESPACES
-- CONFIG\_IPC\_NS
-- CONFIG\_PID\_NS
-- CONFIG\_UTS\_NS
+- CONFIG_NAMESPACES
+- CONFIG_IPC_NS
+- CONFIG_PID_NS
+- CONFIG_UTS_NS
-Your user must be added to a special group to be able to use `xbps-uchroot(1)` and the
-executable must be `setgid`:
+Your user must be added to a special group to be able to use `xbps-uchroot(1)`
+and the executable must be `setgid`:
- # chown root:<group> xbps-uchroot
- # chmod 4750 xbps-uchroot
- # usermod -a -G <group> <user>
+```
+# chown root:<group> xbps-uchroot
+# chmod 4750 xbps-uchroot
+# usermod -a -G <group> <user>
+```
-> NOTE: by default in void you shouldn't do this manually, your user must be a member of
-the `xbuilder` group.
+> NOTE: by default in void you shouldn't do this manually, your user must be a
+> member of the `xbuilder` group.
To enable it:
- $ cd void-packages
- $ echo XBPS_CHROOT_CMD=uchroot >> etc/conf
+```
+$ cd void-packages
+$ echo XBPS_CHROOT_CMD=uchroot >> etc/conf
+```
-If for some reason it's erroring out as `ERROR clone (Operation not permitted)`, check that
-your user is a member of the required `group` and that `xbps-uchroot(1)` utility has the
-proper permissions and owner/group as explained above.
+If for some reason it's erroring out as `ERROR clone (Operation not permitted)`,
+check that your user is a member of the required `group` and that
+`xbps-uchroot(1)` utility has the proper permissions and owner/group as
+explained above.
#### proot(1)
-The `proot(1)` utility implements chroot and bind mounts support completely in user space,
-and can be used if your Linux kernel does not have support for namespaces. See https://proot-me.github.io/.
-for more information.
+The `proot(1)` utility implements chroot and bind mounts support completely in
+user space, and can be used if your Linux kernel does not have support for
+namespaces. See https://proot-me.github.io/. for more information.
To enable it:
- $ cd void-packages
- $ echo XBPS_CHROOT_CMD=proot >> etc/conf
+```
+$ cd void-packages
+$ echo XBPS_CHROOT_CMD=proot >> etc/conf
+```
### Install the bootstrap packages
-The `bootstrap` packages are a set of packages required to build any available source package in a container. There are two methods to install the `bootstrap`:
-
- - `bootstrap`: all bootstrap packages will be built from scratch; additional utilities are required in the
-host system to allow building the `base-chroot` package: binutils, gcc, perl, texinfo, etc.
+The `bootstrap` packages are a set of packages required to build any available
+source package in a container. There are two methods to install the `bootstrap`:
- - `binary-bootstrap`: the bootstrap binary packages are downloaded via XBPS repositories.
+- `bootstrap`: all bootstrap packages will be built from scratch; additional
+ utilities are required in the host system to allow building the `base-chroot`
+ package: binutils, gcc, perl, texinfo, etc.
+- `binary-bootstrap`: the bootstrap binary packages are downloaded via XBPS
+ repositories.
-If you don't want to waste your time building everything from scratch probably it's better to use `binary-bootstrap`.
+If you don't want to waste your time building everything from scratch probably
+it's better to use `binary-bootstrap`.
### Configuration
-The `etc/defaults.conf` file contains the possible settings that can be overridden
-through the `etc/conf` configuration file for the `xbps-src` utility; if that file
-does not exist, will try to read configuration settings from `~/.xbps-src.conf`.
+The `etc/defaults.conf` file contains the possible settings that can be
+overridden through the `etc/conf` configuration file for the `xbps-src` utility;
+if that file does not exist, will try to read configuration settings from
+`~/.xbps-src.conf`.
-If you want to customize default `CFLAGS`, `CXXFLAGS` and `LDFLAGS`, don't override
-those defined in `etc/defaults.conf`, set them on `etc/conf` instead i.e:
+If you want to customize default `CFLAGS`, `CXXFLAGS` and `LDFLAGS`, don't
+override those defined in `etc/defaults.conf`, set them on `etc/conf` instead
+i.e:
- $ echo 'XBPS_CFLAGS="your flags here"' >> etc/conf
- $ echo 'XBPS_LDFLAGS="your flags here"' >> etc/conf
+```
+$ echo 'XBPS_CFLAGS="your flags here"' >> etc/conf
+$ echo 'XBPS_LDFLAGS="your flags here"' >> etc/conf
+```
-Native and cross compiler/linker flags are set per architecture in `common/build-profiles`
-and `common/cross-profiles` respectively. Ideally those settings are good enough by default,
-and there's no need to set your own unless you know what you are doing.
+Native and cross compiler/linker flags are set per architecture in
+`common/build-profiles` and `common/cross-profiles` respectively. Ideally those
+settings are good enough by default, and there's no need to set your own unless
+you know what you are doing.
#### Virtual packages
-The `etc/defaults.virtual` file contains the default replacements for virtual packages,
-used as dependencies in the source packages tree.
+The `etc/defaults.virtual` file contains the default replacements for virtual
+packages, used as dependencies in the source packages tree.
-If you want to customize those replacements, copy `etc/defaults.virtual` to `etc/virtual`
-and edit it accordingly to your needs.
+If you want to customize those replacements, copy `etc/defaults.virtual` to
+`etc/virtual` and edit it accordingly to your needs.
### Directory hierarchy
The following directory hierarchy is used with a default configuration file:
- /void-packages
- |- common
- |- etc
- |- srcpkgs
- | |- xbps
- | |- template
- |
- |- hostdir
- | |- binpkgs ...
- | |- ccache ...
- | |- distcc-<arch> ...
- | |- repocache ...
- | |- sources ...
- |
- |- masterdir
- | |- builddir -> ...
- | |- destdir -> ...
- | |- host -> bind mounted from <hostdir>
- | |- void-packages -> bind mounted from <void-packages>
-
+```
+ /void-packages
+ |- common
+ |- etc
+ |- srcpkgs
+ | |- xbps
+ | |- template
+ |
+ |- hostdir
+ | |- binpkgs ...
+ | |- ccache ...
+ | |- distcc-<arch> ...
+ | |- repocache ...
+ | |- sources ...
+ |
+ |- masterdir
+ | |- builddir -> ...
+ | |- destdir -> ...
+ | |- host -> bind mounted from <hostdir>
+ | |- void-packages -> bind mounted from <void-packages>
+```
The description of these directories is as follows:
- - `masterdir`: master directory to be used as rootfs to build/install packages.
- - `builddir`: to unpack package source tarballs and where packages are built.
- - `destdir`: to install packages, aka **fake destdir**.
- - `hostdir/ccache`: to store ccache data if the `XBPS_CCACHE` option is enabled.
- - `hostdir/distcc-<arch>`: to store distcc data if the `XBPS_DISTCC` option is enabled.
- - `hostdir/repocache`: to store binary packages from remote repositories.
- - `hostdir/sources`: to store package sources.
- - `hostdir/binpkgs`: local repository to store generated binary packages.
+- `masterdir`: master directory to be used as rootfs to build/install packages.
+- `builddir`: to unpack package source tarballs and where packages are built.
+- `destdir`: to install packages, aka **fake destdir**.
+- `hostdir/ccache`: to store ccache data if the `XBPS_CCACHE` option is enabled.
+- `hostdir/distcc-<arch>`: to store distcc data if the `XBPS_DISTCC` option is
+ enabled.
+- `hostdir/repocache`: to store binary packages from remote repositories.
+- `hostdir/sources`: to store package sources.
+- `hostdir/binpkgs`: local repository to store generated binary packages.
### Building packages
-The simplest form of building package is accomplished by running the `pkg` target in `xbps-src`:
+The simplest form of building package is accomplished by running the `pkg`
+target in `xbps-src`:
```
$ cd void-packages
$ ./xbps-src pkg <pkgname>
```
-When the package and its required dependencies are built, the binary packages will be created
-and registered in the default local repository at `hostdir/binpkgs`; the path to this local repository can be added to
-any xbps configuration file (see xbps.d(5)) or by explicitly appending them via cmdline, i.e:
+When the package and its required dependencies are built, the binary packages
+will be created and registered in the default local repository at
+`hostdir/binpkgs`; the path to this local repository can be added to any xbps
+configuration file (see xbps.d(5)) or by explicitly appending them via cmdline,
+i.e:
- $ xbps-install --repository=hostdir/binpkgs ...
- $ xbps-query --repository=hostdir/binpkgs ...
+```
+$ xbps-install --repository=hostdir/binpkgs ...
+$ xbps-query --repository=hostdir/binpkgs ...
+```
By default **xbps-src** will try to resolve package dependencies in this order:
- - If a dependency exists in the local repository, use it (`hostdir/binpkgs`).
- - If a dependency exists in a remote repository, use it.
- - If a dependency exists in a source package, use it.
+- If a dependency exists in the local repository, use it (`hostdir/binpkgs`).
+- If a dependency exists in a remote repository, use it.
+- If a dependency exists in a source package, use it.
-It is possible to avoid using remote repositories completely by using the `-N` flag.
+It is possible to avoid using remote repositories completely by using the `-N`
+flag.
-> The default local repository may contain multiple *sub-repositories*: `debug`, `multilib`, etc.
+> The default local repository may contain multiple *sub-repositories*: `debug`,
+> `multilib`, etc.
### Package build options
-The supported build options for a source package can be shown with `xbps-src show-options`:
+The supported build options for a source package can be shown with `xbps-src
+show-options`:
- $ ./xbps-src show-options foo
+```
+$ ./xbps-src show-options foo
+```
Build options can be enabled with the `-o` flag of `xbps-src`:
- $ ./xbps-src -o option,option1 pkg foo
+```
+$ ./xbps-src -o option,option1 pkg foo
+```
Build options can be disabled by prefixing them with `~`:
- $ ./xbps-src -o ~option,~option1 pkg foo
+```
+$ ./xbps-src -o ~option,~option1 pkg foo
+```
-Both ways can be used together to enable and/or disable multiple options
-at the same time with `xbps-src`:
+Both ways can be used together to enable and/or disable multiple options at the
+same time with `xbps-src`:
- $ ./xbps-src -o option,~option1,~option2 pkg foo
+```
+$ ./xbps-src -o option,~option1,~option2 pkg foo
+```
The build options can also be shown for binary packages via `xbps-query(1)`:
- $ xbps-query -R --property=build-options foo
+```
+$ xbps-query -R --property=build-options foo
+```
-> NOTE: if you build a package with a custom option, and that package is available
-in an official void repository, an update will ignore those options. Put that package
-on `hold` mode via `xbps-pkgdb(1)`, i.e `xbps-pkgdb -m hold foo` to ignore updates
-with `xbps-install -u`. Once the package is on `hold`, the only way to update it
-is by declaring it explicitly: `xbps-install -u foo`.
+> NOTE: if you build a package with a custom option, and that package is
+> available in an official void repository, an update will ignore those options.
+> Put that package on `hold` mode via `xbps-pkgdb(1)`, i.e `xbps-pkgdb -m hold
+> foo` to ignore updates with `xbps-install -u`. Once the package is on `hold`,
+> the only way to update it is by declaring it explicitly: `xbps-install -u
+> foo`.
-Permanent global package build options can be set via `XBPS_PKG_OPTIONS` variable in the
-`etc/conf` configuration file. Per package build options can be set via
-`XBPS_PKG_OPTIONS_<pkgname>`.
+Permanent global package build options can be set via `XBPS_PKG_OPTIONS`
+variable in the `etc/conf` configuration file. Per package build options can be
+set via `XBPS_PKG_OPTIONS_<pkgname>`.
-> NOTE: if `pkgname` contains `dashes`, those should be replaced by `underscores`
-i.e `XBPS_PKG_OPTIONS_xorg_server=opt`.
+> NOTE: if `pkgname` contains `dashes`, those should be replaced by
+> `underscores` i.e `XBPS_PKG_OPTIONS_xorg_server=opt`.
-The list of supported package build options and its description is defined in the
-`common/options.description` file or in the `template` file.
+The list of supported package build options and its description is defined in
+the `common/options.description` file or in the `template` file.
### Sharing and signing your local repositories
-To share a local repository remotely it's mandatory to sign it and the binary packages
-stored on it. This is accomplished with the `xbps-rindex(1)` utility.
+To share a local repository remotely it's mandatory to sign it and the binary
+packages stored on it. This is accomplished with the `xbps-rindex(1)` utility.
First a RSA key must be created with `openssl(1)` or `ssh-keygen(1)`:
- $ openssl genrsa -des3 -out privkey.pem 4096
+```
+$ openssl genrsa -des3 -out privkey.pem 4096
+```
or
- $ ssh-keygen -t rsa -b 4096 -m PEM -f privkey.pem
+```
+$ ssh-keygen -t rsa -b 4096 -m PEM -f privkey.pem
+```
> Only RSA keys in PEM format are currently accepted by xbps.
-Once the RSA private key is ready you can use it to initialize the repository metadata:
+Once the RSA private key is ready you can use it to initialize the repository
+metadata:
- $ xbps-rindex --sign --signedby "I'm Groot" --privkey privkey.pem $PWD/hostdir/binpkgs
+```
+$ xbps-rindex --sign --signedby "I'm Groot" --privkey privkey.pem $PWD/hostdir/binpkgs
+```
And then make a signature per package:
- $ xbps-rindex --sign-pkg --privkey privkey.pem $PWD/hostdir/binpkgs/*.xbps
+```
+$ xbps-rindex --sign-pkg --privkey privkey.pem $PWD/hostdir/binpkgs/*.xbps
+```
> If --privkey is unset, it defaults to `~/.ssh/id_rsa`.
-If the RSA key was protected with a passphrase you'll have to type it, or alternatively set
-it via the `XBPS_PASSPHRASE` environment variable.
+If the RSA key was protected with a passphrase you'll have to type it, or
+alternatively set it via the `XBPS_PASSPHRASE` environment variable.
-Once the binary packages have been signed, check the repository contains the appropriate `hex fingerprint`:
+Once the binary packages have been signed, check the repository contains the
+appropriate `hex fingerprint`:
- $ xbps-query --repository=hostdir/binpkgs -vL
- ...
+```
+$ xbps-query --repository=hostdir/binpkgs -vL
+...
+```
-Each time a binary package is created, a package signature must be created with `--sign-pkg`.
+Each time a binary package is created, a package signature must be created with
+`--sign-pkg`.
> It is not possible to sign a repository with multiple RSA keys.
### Rebuilding and overwriting existing local packages
-If for whatever reason a package has been built and it is available in your local repository
-and you have to rebuild it without bumping its `version` or `revision` fields, it is possible
-to accomplish this task easily with `xbps-src`:
+If for whatever reason a package has been built and it is available in your
+local repository and you have to rebuild it without bumping its `version` or
+`revision` fields, it is possible to accomplish this task easily with
+`xbps-src`:
- $ ./xbps-src -f pkg xbps
+```
+$ ./xbps-src -f pkg xbps
+```
Reinstalling this package in your target `rootdir` can be easily done too:
- $ xbps-install --repository=/path/to/local/repo -yff xbps-0.25_1
+```
+$ xbps-install --repository=/path/to/local/repo -yff xbps-0.25_1
+```
-> Please note that the `package expression` must be properly defined to explicitly pick up
-the package from the desired repository.
+> Please note that the `package expression` must be properly defined to
+> explicitly pick up the package from the desired repository.
### Enabling distcc for distributed compilation
Setup the slaves (machines that will compile the code):
- # xbps-install -Sy distcc
+```
+# xbps-install -Sy distcc
+```
-Modify the configuration to allow your local network machines to use distcc (e.g. `192.168.2.0/24`):
+Modify the configuration to allow your local network machines to use distcc
+(e.g. `192.168.2.0/24`):
- # echo "192.168.2.0/24" >> /etc/distcc/clients.allow
+```
+# echo "192.168.2.0/24" >> /etc/distcc/clients.allow
+```
Enable and start the `distccd` service:
- # ln -s /etc/sv/distccd /var/service
+```
+# ln -s /etc/sv/distccd /var/service
+```
-Install distcc on the host (machine that executes xbps-src) as well.
-Unless you want to use the host as slave from other machines, there is no need
-to modify the configuration.
+Install distcc on the host (machine that executes xbps-src) as well. Unless you
+want to use the host as slave from other machines, there is no need to modify
+the configuration.
On the host you can now enable distcc in the `void-packages/etc/conf` file:
- XBPS_DISTCC=yes
- XBPS_DISTCC_HOSTS="localhost/2 --localslots_cpp=24 192.168.2.101/9 192.168.2.102/2"
- XBPS_MAKEJOBS=16
+```
+XBPS_DISTCC=yes
+XBPS_DISTCC_HOSTS="localhost/2 --localslots_cpp=24 192.168.2.101/9 192.168.2.102/2"
+XBPS_MAKEJOBS=16
+```
-The example values assume a localhost CPU with 4 cores of which at most 2 are used for compiler jobs.
-The number of slots for preprocessor jobs is set to 24 in order to have enough preprocessed data for other CPUs to compile.
-The slave 192.168.2.101 has a CPU with 8 cores and the /9 for the number of jobs is a saturating choice.
-The slave 192.168.2.102 is set to run at most 2 compile jobs to keep its load low, even if its CPU has 4 cores.
-The XBPS_MAKEJOBS setting is increased to 16 to account for the possible parallelism (2 + 9 + 2 + some slack).
+The example values assume a localhost CPU with 4 cores of which at most 2 are
+used for compiler jobs. The number of slots for preprocessor jobs is set to 24
+in order to have enough preprocessed data for other CPUs to compile. The slave
+192.168.2.101 has a CPU with 8 cores and the /9 for the number of jobs is a
+saturating choice. The slave 192.168.2.102 is set to run at most 2 compile jobs
+to keep its load low, even if its CPU has 4 cores. The XBPS_MAKEJOBS setting is
+increased to 16 to account for the possible parallelism (2 + 9 + 2 + some
+slack).
### Distfiles mirror(s)
-In etc/conf you may optionally define a mirror or a list of mirrors to search for distfiles.
+In etc/conf you may optionally define a mirror or a list of mirrors to search
+for distfiles.
- $ echo 'XBPS_DISTFILES_MIRROR="ftp://192.168.100.5/gentoo/distfiles"' >> etc/conf
+```
+$ echo 'XBPS_DISTFILES_MIRROR="ftp://192.168.100.5/gentoo/distfiles"' >> etc/conf
+```
-If more than one mirror is to be searched, you can either specify multiple URLs separated
-with blanks, or add to the variable like this
+If more than one mirror is to be searched, you can either specify multiple URLs
+separated with blanks, or add to the variable like this
- $ echo 'XBPS_DISTFILES_MIRROR+=" http://repo.voidlinux.de/distfiles"' >> etc/conf
+```
+$ echo 'XBPS_DISTFILES_MIRROR+=" http://repo.voidlinux.de/distfiles"' >> etc/conf
+```
Make sure to put the blank after the first double quote in this case.
The mirrors are searched in order for the distfiles to build a package until the
checksum of the downloaded file matches the one specified in the template.
-Ultimately, if no mirror carries the distfile, or in case all downloads failed the
-checksum verification, the original download location is used.
+Ultimately, if no mirror carries the distfile, or in case all downloads failed
+the checksum verification, the original download location is used.
-If you use `proot` or `uchroot` for your XBPS_CHROOT_CMD, you may also specify a local path
-using the `file://` prefix or simply an absolute path on your build host (e.g. /mnt/distfiles).
-Mirror locations specified this way are bind mounted inside the chroot environment
-under $XBPS_MASTERDIR and searched for distfiles just the same as remote locations.
+If you use `proot` or `uchroot` for your XBPS_CHROOT_CMD, you may also specify a
+local path using the `file://` prefix or simply an absolute path on your build
+host (e.g. /mnt/distfiles). Mirror locations specified this way are bind mounted
+inside the chroot environment under $XBPS_MASTERDIR and searched for distfiles
+just the same as remote locations.
### Cross compiling packages for a target architecture
-Currently `xbps-src` can cross build packages for some target architectures with a cross compiler.
-The supported target is shown with `./xbps-src -h`.
+Currently `xbps-src` can cross build packages for some target architectures with
+a cross compiler. The supported target is shown with `./xbps-src -h`.
-If a source package has been adapted to be **cross buildable** `xbps-src` will automatically build the binary package(s) with a simple command:
+If a source package has been adapted to be **cross buildable** `xbps-src` will
+automatically build the binary package(s) with a simple command:
- $ ./xbps-src -a <target> pkg <pkgname>
+```
+$ ./xbps-src -a <target> pkg <pkgname>
+```
-If the build for whatever reason fails, might be a new build issue or simply because it hasn't been adapted to be **cross compiled**.
+If the build for whatever reason fails, might be a new build issue or simply
+because it hasn't been adapted to be **cross compiled**.
### Using xbps-src in a foreign Linux distribution
-xbps-src can be used in any recent Linux distribution matching the CPU architecture.
+xbps-src can be used in any recent Linux distribution matching the CPU
+architecture.
-To use xbps-src in your Linux distribution use the following instructions. Let's start downloading the xbps static binaries:
+To use xbps-src in your Linux distribution use the following instructions. Let's
+start downloading the xbps static binaries:
- $ wget http://alpha.de.repo.voidlinux.org/static/xbps-static-latest.<arch>-musl.tar.xz
- $ mkdir ~/XBPS
- $ tar xvf xbps-static-latest.<arch>.tar.xz -C ~/XBPS
- $ export PATH=~/XBPS/usr/bin:$PATH
+```
+$ wget http://alpha.de.repo.voidlinux.org/static/xbps-static-latest.<arch>-musl.tar.xz
+$ mkdir ~/XBPS
+$ tar xvf xbps-static-latest.<arch>.tar.xz -C ~/XBPS
+$ export PATH=~/XBPS/usr/bin:$PATH
+```
-If your system does not support `user namespaces`, a privileged group is required to be able to use
-`xbps-uchroot(1)` with xbps-src, by default it's set to the `xbuilder` group, change this to your desired group:
+If your system does not support `user namespaces`, a privileged group is
+required to be able to use `xbps-uchroot(1)` with xbps-src, by default it's set
+to the `xbuilder` group, change this to your desired group:
- # chown root:<group> ~/XBPS/usr/bin/xbps-uchroot.static
- # chmod 4750 ~/XBPS/usr/bin/xbps-uchroot.static
+```
+# chown root:<group> ~/XBPS/usr/bin/xbps-uchroot.static
+# chmod 4750 ~/XBPS/usr/bin/xbps-uchroot.static
+```
Clone the `void-packages` git repository:
- $ git clone git://github.com/void-linux/void-packages
+```
+$ git clone git://github.com/void-linux/void-packages
+```
-and `xbps-src` should be fully functional; just start the `bootstrap` process, i.e:
+and `xbps-src` should be fully functional; just start the `bootstrap` process,
+i.e:
- $ ./xbps-src binary-bootstrap
+```
+$ ./xbps-src binary-bootstrap
+```
-The default masterdir is created in the current working directory, i.e `void-packages/masterdir`.
+The default masterdir is created in the current working directory, i.e
+`void-packages/masterdir`.
### Remaking the masterdir
-If for some reason you must update xbps-src and the `bootstrap-update` target is not enough, it's possible to recreate a masterdir with two simple commands (please note that `zap` keeps your `ccache/distcc/host` directories intact):
+If for some reason you must update xbps-src and the `bootstrap-update` target is
+not enough, it's possible to recreate a masterdir with two simple commands
+(please note that `zap` keeps your `ccache/distcc/host` directories intact):
- $ ./xbps-src zap
- $ ./xbps-src binary-bootstrap
+```
+$ ./xbps-src zap
+$ ./xbps-src binary-bootstrap
+```
### Keeping your masterdir uptodate
-Sometimes the bootstrap packages must be updated to the latest available version in repositories, this is accomplished with the `bootstrap-update` target:
+Sometimes the bootstrap packages must be updated to the latest available version
+in repositories, this is accomplished with the `bootstrap-update` target:
- $ ./xbps-src bootstrap-update
+```
+$ ./xbps-src bootstrap-update
+```
### Building 32bit packages on x86_64
-Two ways are available to build 32bit packages on x86\_64:
+Two ways are available to build 32bit packages on x86_64:
- - cross compilation mode
- - native mode with a 32bit masterdir
+- cross compilation mode
+- native mode with a 32bit masterdir
The first mode (cross compilation) is as easy as:
- $ ./xbps-src -a i686 pkg ...
+```
+$ ./xbps-src -a i686 pkg ...
+```
The second mode (native) needs a new x86 `masterdir`:
- $ ./xbps-src -m masterdir-x86 binary-bootstrap i686
- $ ./xbps-src -m masterdir-x86 ...
+```
+$ ./xbps-src -m masterdir-x86 binary-bootstrap i686
+$ ./xbps-src -m masterdir-x86 ...
+```
### Building packages natively for the musl C library
-A native build environment is required to be able to cross compile the bootstrap packages for the musl C library; this is accomplished by installing them via `binary-bootstrap`:
+A native build environment is required to be able to cross compile the bootstrap
+packages for the musl C library; this is accomplished by installing them via
+`binary-bootstrap`:
- $ ./xbps-src binary-bootstrap
+```
+$ ./xbps-src binary-bootstrap
+```
Now cross compile `base-chroot-musl` for your native architecture:
- $ ./xbps-src -a x86_64-musl pkg base-chroot-musl
+```
+$ ./xbps-src -a x86_64-musl pkg base-chroot-musl
+```
-Wait until all packages are built and when ready, prepare a new masterdir with the musl packages:
+Wait until all packages are built and when ready, prepare a new masterdir with
+the musl packages:
- $ ./xbps-src -m masterdir-x86_64-musl binary-bootstrap x86_64-musl
+```
+$ ./xbps-src -m masterdir-x86_64-musl binary-bootstrap x86_64-musl
+```
-Your new masterdir is now ready to build packages natively for the musl C library. Try:
+Your new masterdir is now ready to build packages natively for the musl C
+library. Try:
- $ ./xbps-src -m masterdir-x86_64-musl chroot
- $ ldd
+```
+$ ./xbps-src -m masterdir-x86_64-musl chroot
+$ ldd
+```
To see if the musl C dynamic linker is working as expected.
@@ -481,14 +609,21 @@ To see if the musl C dynamic linker is working as expected.
To rebuild all packages in `base-system` for your native architecture:
- $ ./xbps-src -N pkg base-system
+```
+$ ./xbps-src -N pkg base-system
+```
It's also possible to cross compile everything from scratch:
- $ ./xbps-src -a <target> -N pkg base-system
+```
+$ ./xbps-src -a <target> -N pkg base-system
+```
-Once the build has finished, you can specify the path to the local repository to `void-mklive`, i.e:
+Once the build has finished, you can specify the path to the local repository to
+`void-mklive`, i.e:
- # cd void-mklive
- # make
- # ./mklive.sh ... -r /path/to/hostdir/binpkgs
+```
+# cd void-mklive
+# make
+# ./mklive.sh ... -r /path/to/hostdir/binpkgs
+```
From 735b13fd63c3df59292623ec6579c4e7e4e24c27 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Mon, 4 May 2020 11:07:11 -0300
Subject: [PATCH 6/6] README, CONTRIBUTING, Manual: use file names instead of
links for files inside the repo
---
CONTRIBUTING.md | 16 ++++++----------
Manual.md | 2 +-
README.md | 8 +++-----
3 files changed, 10 insertions(+), 16 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1a90e742ee0..c3240cd591c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -11,11 +11,9 @@ packages, correcting bugs and adding features to void-packages.
If you really want to get a package into Void Linux, we recommend you package it
yourself.
-We provide a [comprehensive
-Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md) on
-how to create new packages. There's also a [manual for
-xbps-src](https://github.com/void-linux/void-packages/blob/master/README.md),
-which is used to build package files from templates.
+We provide a [comprehensive Manual](./Manual.md) on how to create new packages.
+There's also a [manual for xbps-src](./README.md), which is used to build
+package files from templates.
For this guide, we assume you have basic knowledge about
[git](http://git-scm.org), as well as a [GitHub Account](http://github.com).
@@ -37,9 +35,8 @@ Templates must have the name `void-packages/srcpkgs/<pkgname>/template`, where
`pkgname` is the same as the `pkgname` variable in the template.
For deeper insights on the contents of template files, please read the
-[manual](https://github.com/void-linux/void-packages/blob/master/Manual.md), and
-be sure to browse the existing template files in the `srcpkgs` directory of this
-repository for concrete examples.
+[manual](./Manual.md), and be sure to browse the existing template files in the
+`srcpkgs` directory of this repository for concrete examples.
When you've finished working on the template file, please check it with `xlint`
helper from the [xtools](https://github.com/chneukirchen/xtools) package:
@@ -69,8 +66,7 @@ If you want to describe your changes in more detail, add an empty line followed
by those details
([example](https://github.com/void-linux/void-packages/commit/f1c45a502086ba1952f23ace9084a870ce437bc6)).
-For further information, please consult the
-[manual](https://github.com/void-linux/void-packages/blob/master/Manual.md).
+For further information, please consult the [manual](./Manual.md).
`xbump`, available in the [xtools](https://github.com/chneukirchen/xtools)
package, can be used to commit a new or updated package:
diff --git a/Manual.md b/Manual.md
index b1cf9f9dc20..f1c82b66bdc 100644
--- a/Manual.md
+++ b/Manual.md
@@ -1892,7 +1892,7 @@ Fork the voidlinux `void-packages` git repository on github and clone it:
$ git clone git@github.com:<user>/void-packages.git
-See [CONTRIBUTING.md](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
+See [CONTRIBUTING.md](./CONTRIBUTING.md)
for information on how to format your commits and other tips for
contributing.
diff --git a/README.md b/README.md
index afe50b766be..13c677062c2 100644
--- a/README.md
+++ b/README.md
@@ -8,11 +8,9 @@ its files into a `fake destdir` to generate XBPS binary packages that can be
installed or queried through the `xbps-install(1)` and `xbps-query(1)`
utilities, respectively.
-See
-[Contributing](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
-for a general overview of how to contribute and the
-[Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md) for
-details of how to create source packages.
+See [Contributing](./CONTRIBUTING.md) for a general overview of how to
+contribute and the [Manual](./Manual.md) for details of how to create source
+packages.
### Table of Contents
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Run vmdfmt in the markdown files and update some information there
2020-05-04 14:20 [PR PATCH] Run vmdfmt in the markdown files and update some information there ericonr
@ 2020-05-04 14:27 ` Duncaen
2020-05-04 14:31 ` [PR PATCH] [Updated] " ericonr
` (6 subsequent siblings)
7 siblings, 0 replies; 9+ messages in thread
From: Duncaen @ 2020-05-04 14:27 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 270 bytes --]
New comment by Duncaen on void-packages repository
https://github.com/void-linux/void-packages/pull/21609#issuecomment-623497670
Comment:
Not a fan of vmdfmt, this makes the markdown less readable for no real gain, and makes git blame to look at history a lot harder.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PR PATCH] [Updated] Run vmdfmt in the markdown files and update some information there
2020-05-04 14:20 [PR PATCH] Run vmdfmt in the markdown files and update some information there ericonr
2020-05-04 14:27 ` Duncaen
@ 2020-05-04 14:31 ` ericonr
2020-05-04 17:37 ` ericonr
` (5 subsequent siblings)
7 siblings, 0 replies; 9+ messages in thread
From: ericonr @ 2020-05-04 14:31 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 900 bytes --]
There is an updated pull request by ericonr against master on the void-packages repository
https://github.com/ericonr/void-packages contributing
https://github.com/void-linux/void-packages/pull/21609
Run vmdfmt in the markdown files and update some information there
- Had to remove html tags from those files and use markdown anchors instead
- Changed how files in this repo are linked to each other, GH supports using `[contributing](./CONTRIBUTING.md)`.
- Added some information regarding PRs, which I took from #21481 and one of my own PRs as well. This commit can be split from the rest, but it was easier to include it, since I was already messing with the formatting.
I've tested the hyperlinks in the GH interface, and they should be good to go. The main commit for comments should be f272b49.
A patch file from https://github.com/void-linux/void-packages/pull/21609.patch is attached
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-contributing-21609.patch --]
[-- Type: text/x-diff, Size: 89778 bytes --]
From 99c6e7edfd97c121d500d35be25d86c97884350a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Thu, 30 Apr 2020 22:37:58 -0300
Subject: [PATCH 1/6] CONTRIBUTING.md: format with vmdfmt
---
CONTRIBUTING.md | 150 ++++++++++++++++++++++++++++++++----------------
1 file changed, 102 insertions(+), 48 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0490b5f11c2..a55dda679ec 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,65 +1,99 @@
# Contributing to void-packages
-void-packages is the backbone of the Void Linux distribution. It contains all the definitions to build packages from source.
+void-packages is the backbone of the Void Linux distribution. It contains all
+the definitions to build packages from source.
-This document describes how you, as a contributor, can help with adding packages, correcting bugs and adding features to void-packages.
+This document describes how you, as a contributor, can help with adding
+packages, correcting bugs and adding features to void-packages.
## Getting your packages into Void by yourself
-If you really want to get a package into Void Linux, we recommend you package it yourself.
+If you really want to get a package into Void Linux, we recommend you package it
+yourself.
-We provide a [comprehensive Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md)
-on how to create new packages. There's also a
-[manual for xbps-src](https://github.com/void-linux/void-packages/blob/master/README.md), which is used
-to build package files from templates.
+We provide a [comprehensive
+Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md) on
+how to create new packages. There's also a [manual for
+xbps-src](https://github.com/void-linux/void-packages/blob/master/README.md),
+which is used to build package files from templates.
-For this guide, we assume you have basic knowledge about [git](http://git-scm.org), as well as a [GitHub Account](http://github.com).
+For this guide, we assume you have basic knowledge about
+[git](http://git-scm.org), as well as a [GitHub Account](http://github.com).
-Please note that we do not accept any packages containing non-release versions, such as specific git- or svn-revisions anymore.
+Please note that we do not accept any packages containing non-release versions,
+such as specific git- or svn-revisions anymore.
### Creating a new template
-You can use the helper tool `xnew`, from the [xtools](https://github.com/chneukirchen/xtools) package, to create new templates:
+You can use the helper tool `xnew`, from the
+[xtools](https://github.com/chneukirchen/xtools) package, to create new
+templates:
- $ xnew pkgname subpkg1 subpkg2 ...
+```
+$ xnew pkgname subpkg1 subpkg2 ...
+```
-Templates must have the name `void-packages/srcpkgs/<pkgname>/template`, where `pkgname` is the same as the `pkgname` variable in the template.
+Templates must have the name `void-packages/srcpkgs/<pkgname>/template`, where
+`pkgname` is the same as the `pkgname` variable in the template.
-For deeper insights on the contents of template files, please read the [manual](https://github.com/void-linux/void-packages/blob/master/Manual.md), and be sure to browse the existing template files in the `srcpkgs` directory of this repository for concrete examples.
+For deeper insights on the contents of template files, please read the
+[manual](https://github.com/void-linux/void-packages/blob/master/Manual.md), and
+be sure to browse the existing template files in the `srcpkgs` directory of this
+repository for concrete examples.
-When you've finished working on the template file, please check it with `xlint` helper from the [xtools](https://github.com/chneukirchen/xtools) package:
+When you've finished working on the template file, please check it with `xlint`
+helper from the [xtools](https://github.com/chneukirchen/xtools) package:
- $ xlint template
+```
+$ xlint template
+```
If `xlint` reports any issues, resolve them before committing.
### Committing your changes
-Once you have built your template file or files, the commit message should have one of the following forms:
+Once you have built your template file or files, the commit message should have
+one of the following forms:
-* for new packages, use ```New package: <pkgname>-<version>``` ([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)).
+- for new packages, use `New package: <pkgname>-<version>`
+ ([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)).
+- for package updates, use `<pkgname>: update to <version>.`
+ ([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)).
+- for template modifications without a version change, use `<pkgname>: <reason>`
+ ([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)).
-* for package updates, use ```<pkgname>: update to <version>.``` ([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)).
+If you want to describe your changes in more detail, add an empty line followed
+by those details
+([example](https://github.com/void-linux/void-packages/commit/f1c45a502086ba1952f23ace9084a870ce437bc6)).
-* for template modifications without a version change, use ```<pkgname>: <reason>``` ([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)).
+For further information, please consult the
+[manual](https://github.com/void-linux/void-packages/blob/master/Manual.md).
-If you want to describe your changes in more detail, add an empty line followed by those details ([example](https://github.com/void-linux/void-packages/commit/f1c45a502086ba1952f23ace9084a870ce437bc6)).
+`xbump`, available in the [xtools](https://github.com/chneukirchen/xtools)
+package, can be used to commit a new or updated package:
-For further information, please consult the [manual](https://github.com/void-linux/void-packages/blob/master/Manual.md).
+```
+$ xbump <pkgname> <git commit options>
+```
-`xbump`, available in the [xtools](https://github.com/chneukirchen/xtools) package, can be used to commit a new or updated package:
+`xbump` will use `git commit` to commit the changes with the appropriate commit
+message. For more fine-grained control over the commit, specific options can be
+passed to `git commit` by adding them after the package name.
- $ xbump <pkgname> <git commit options>
+After committing your changes, please check that the package builds
+successfully. From the top level directory of your local copy of the
+`void-packages` repository, run:
-`xbump` will use `git commit` to commit the changes with the appropriate commit message. For more fine-grained control over the commit, specific options can be passed to `git commit` by adding them after the package name.
+```
+$ ./xbps-src pkg <pkgname>
+```
-After committing your changes, please check that the package builds successfully. From the top level directory of your local copy of the `void-packages` repository, run:
+Your package must build successfully for at least x86, but we recommend trying
+to build for armv* as well, e.g.:
- $ ./xbps-src pkg <pkgname>
-
-Your package must build successfully for at least x86, but we recommend trying to build for armv* as well, e.g.:
-
- $ ./xbps-src -a armv7l pkg <pkgname>
+```
+$ ./xbps-src -a armv7l pkg <pkgname>
+```
For further details, see the output of `./xbps-src -h`.
@@ -67,40 +101,60 @@ For further details, see the output of `./xbps-src -h`.
Once you have successfully built the package, you can start a pull request.
-Most pull requests should only contain a single package and dependencies which are not part of void-packages yet.
+Most pull requests should only contain a single package and dependencies which
+are not part of void-packages yet.
-If you make updates to packages containing a soname bump you also need to revbump all packages that are dependant. Those
-packages should also be part of the same pull request.
+If you make updates to packages containing a soname bump you also need to
+revbump all packages that are dependant. Those packages should also be part of
+the same pull request.
-When you make changes to your pull request, please *do not close and reopen your pull request*. Instead, just forcibly git push, overwriting any old commits. Closing and opening your pull requests repeatedly spams the Void maintainers.
+When you make changes to your pull request, please *do not close and reopen your
+pull request*. Instead, just forcibly git push, overwriting any old commits.
+Closing and opening your pull requests repeatedly spams the Void maintainers.
#### Travis
-Once you have started a pull request, you will get instant feedback from Travis. It will check if the templates you have changed
-comply with the our guidelines. At the moment not all packages comply with the rules, so if you update a package, it may happen that Travis reports errors about places you haven't touched. Please feel free to fix those errors too.
+Once you have started a pull request, you will get instant feedback from Travis.
+It will check if the templates you have changed comply with the our guidelines.
+At the moment not all packages comply with the rules, so if you update a
+package, it may happen that Travis reports errors about places you haven't
+touched. Please feel free to fix those errors too.
#### Review
-Most of the time your pull request will contain mistakes. It's nothing bad, it just happens.
+Most of the time your pull request will contain mistakes. It's nothing bad, it
+just happens.
-Reviewers will comment on your pull request and point out which changes are needed before the template can be included.
+Reviewers will comment on your pull request and point out which changes are
+needed before the template can be included.
-We recommend having only a single commit for pull request, so if you need to make changes in commits but already have a pull request, use the following commands:
+We recommend having only a single commit for pull request, so if you need to
+make changes in commits but already have a pull request, use the following
+commands:
- $ git add <file>
- $ git commit --amend
- $ git push -f
+```
+$ git add <file>
+$ git commit --amend
+$ git push -f
+```
#### Closing the pull request
-Once you have applied all requested changes, the reviewers will merge your request.
+Once you have applied all requested changes, the reviewers will merge your
+request.
-If the pull request becomes inactive for some days, the reviewers may or may not warn you when they are about to close it.
-If it stays inactive further, it will be closed.
+If the pull request becomes inactive for some days, the reviewers may or may not
+warn you when they are about to close it. If it stays inactive further, it will
+be closed.
-Please abstain from temporarily closing a pull request while revising the templates. Instead, leave a comment on the PR describing what still needs work, or add "[WIP]" to the PR title. Only close your pull request if you're sure you don't want your changes to be included.
+Please abstain from temporarily closing a pull request while revising the
+templates. Instead, leave a comment on the PR describing what still needs work,
+or add "[WIP]" to the PR title. Only close your pull request if you're sure you
+don't want your changes to be included.
#### Publishing the package
-Once the reviewers have merged the pull request, our [build server](http://build.voidlinux.org) is automatically triggered and builds
-all packages in the pull request for all supported platforms. Upon completion, the packages are available to all Void Linux users.
+Once the reviewers have merged the pull request, our [build
+server](http://build.voidlinux.org) is automatically triggered and builds all
+packages in the pull request for all supported platforms. Upon completion, the
+packages are available to all Void Linux users.
From d775a9cd6b1778612192539f40ed623b53b5da82 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Thu, 30 Apr 2020 22:42:29 -0300
Subject: [PATCH 2/6] CONTRIBUTING.md: update commit examples and PR process
- Add a commit example for shlibs modifications
- Explain the PR process a bit better, specially what needs to be
done when the packages involve a soname bump
---
CONTRIBUTING.md | 12 ++++++++----
1 file changed, 8 insertions(+), 4 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a55dda679ec..1a90e742ee0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -59,8 +59,11 @@ one of the following forms:
([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)).
- for package updates, use `<pkgname>: update to <version>.`
([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)).
-- for template modifications without a version change, use `<pkgname>: <reason>`
+- for template modifications without a version change, including removals, use
+ `<pkgname>: <reason>`
([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)).
+- for `common/shlibs` modifications, use `common/shlibs: <pkgname>`
+ ([example](https://github.com/void-linux/void-packages/commit/613651c91811cb4fd2e1a6be701c87072d759a9f)).
If you want to describe your changes in more detail, add an empty line followed
by those details
@@ -104,9 +107,10 @@ Once you have successfully built the package, you can start a pull request.
Most pull requests should only contain a single package and dependencies which
are not part of void-packages yet.
-If you make updates to packages containing a soname bump you also need to
-revbump all packages that are dependant. Those packages should also be part of
-the same pull request.
+If you make updates to packages containing a soname bump, you also need to
+update `common/shlibs` and revbump all packages that are dependant. There should
+be a commit for each package revbump, and those commits should be part of the
+same pull request.
When you make changes to your pull request, please *do not close and reopen your
pull request*. Instead, just forcibly git push, overwriting any old commits.
From 2146bf4785d6efb4249b5cfb62b467ecbdc65b8a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Thu, 30 Apr 2020 23:02:20 -0300
Subject: [PATCH 3/6] Manual.md: use markdown anchors instead of HTML tags
Match some titles in the index to the titles in the document itself.
---
Manual.md | 197 ++++++++++++++++++------------------------------------
1 file changed, 65 insertions(+), 132 deletions(-)
diff --git a/Manual.md b/Manual.md
index 576b3d2032e..b1cf9f9dc20 100644
--- a/Manual.md
+++ b/Manual.md
@@ -5,73 +5,72 @@ packages for XBPS, the `Void Linux` native packaging system.
*Table of Contents*
-* [Introduction](#Introduction)
- * [Quality Requirements](#quality_requirements)
- * [Package build phases](#buildphase)
- * [Package naming conventions](#namingconvention)
- * [Libraries](#libs)
- * [Language Modules](#language_modules)
- * [Language Bindings](#language_bindings)
+* [Introduction](#introduction)
+ * [Quality Requirements](#quality-requirements)
+ * [Package build phases](#package-build-phases)
+ * [Package naming conventions](#package-naming-conventions)
+ * [Libraries](#libraries)
+ * [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)
- * [About the depends variables](#explain_depends)
+ * [Global functions](#global-functions)
+ * [Global variables](#global-variables)
+ * [Available variables](#available-variables)
+ * [Mandatory variables](#mandatory-variables)
+ * [Optional variables](#optional-variables)
+ * [About the many types of `depends` variables](#about-the-many-types-of-depends-variables)
* [Repositories](#repositories)
- * [Repositories defined by Branch](#repo_by_branch)
- * [Package defined repositories](#pkg_defined_repo)
- * [Checking for new upstream releases](#updates)
- * [Handling patches](#patches)
- * [Build style scripts](#build_scripts)
- * [Build helper scripts](#build_helper)
+ * [Repositories defined by Branch](#repositories-defined-by-branch)
+ * [Package defined Repositories](#package-defined-repositories)
+ * [Checking for new upstream releases](#checking-for-new-upstream-releases)
+ * [Handling patches](#handling-patches)
+ * [build\_style scripts](#build_style-scripts)
+ * [build\_helper scripts](#build_helper-scripts)
* [Functions](#functions)
- * [Build options](#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)
- * [Writing runit services](#writing_runit_services)
- * [32bit packages](#32bit_pkgs)
- * [Subpackages](#pkgs_sub)
- * [Development packages](#pkgs_development)
- * [Data packages](#pkgs_data)
- * [Documentation packages](#pkgs_documentation)
- * [Python packages](#pkgs_python)
- * [Go packages](#pkgs_go)
- * [Haskell packages](#pkgs_haskell)
- * [Font packages](#pkgs_font)
- * [Removing a package](#pkg_remove)
- * [XBPS Triggers](#xbps_triggers)
- * [appstream-cache](#triggers_appstream_cache)
- * [binfmts](#triggers_binfmts)
- * [dkms](#triggers_dkms)
- * [gconf-schemas](#triggers_gconf_schemas)
- * [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders)
- * [gio-modules](#triggers_gio_modules)
- * [gettings-schemas](#triggers_gsettings_schemas)
- * [gtk-icon-cache](#triggers_gtk_icon_cache)
- * [gtk-immodules](#triggers_gtk_immodules)
- * [gtk-pixbuf-loaders](#triggers_gtk_pixbuf_loaders)
- * [gtk3-immodules](#triggers_gtk3_immodules)
- * [hwdb.d-dir](#triggers_hwdb.d_dir)
- * [info-files](#triggers_info_files)
- * [kernel-hooks](#triggers_kernel_hooks)
- * [mimedb](#triggers_mimedb)
- * [mkdirs](#triggers_mkdirs)
- * [pango-modules](#triggers_pango_module)
- * [pycompile](#triggers_pycompile)
- * [register-shell](#triggers_register_shell)
- * [system-accounts](#triggers_system_accounts)
- * [update-desktopdb](#triggers_update_desktopdb)
- * [x11-fonts](#triggers_x11_fonts)
- * [xml-catalog](#triggers_xml_catalog)
+ * [Build options](#build-options)
+ * [Runtime dependencies](#runtime-dependencies)
+ * [INSTALL and REMOVE files](#install-and-remove-files)
+ * [INSTALL.msg and REMOVE.msg files](#installmsg-and-removemsg-files)
+ * [Creating system accounts/groups at runtime](#creating-system-accountsgroups-at-runtime)
+ * [Writing runit services](#writing-runit-services)
+ * [32bit packages](#32bit-packages)
+ * [Subpackages](#subpackages)
+ * [Development packages](#development-packages)
+ * [Data packages](#data-packages)
+ * [Documentation packages](#documentation-packages)
+ * [Python packages](#python-packages)
+ * [Go packages](#go-packages)
+ * [Haskell packages](#haskell-packages)
+ * [Font packages](#font-packages)
+ * [Removing a package](#removing-a-package)
+ * [XBPS Triggers](#xbps-triggers)
+ * [appstream-cache](#appstream-cache)
+ * [binfmts](#binfmts)
+ * [dkms](#dkms)
+ * [gconf-schemas](#gconf-schemas)
+ * [gdk-pixbuf-loaders](#gdk-pixbuf-loaders)
+ * [gio-modules](#gio-modules)
+ * [gettings-schemas](#gsettings-schemas)
+ * [gtk-icon-cache](#gtk-icon-cache)
+ * [gtk-immodules](#gtk-immodules)
+ * [gtk-pixbuf-loaders](#gtk-pixbuf-loaders)
+ * [gtk3-immodules](#gtk3-immodules)
+ * [hwdb.d-dir](#hwdbd-dir)
+ * [info-files](#info-files)
+ * [kernel-hooks](#kernel-hooks)
+ * [mimedb](#mimedb)
+ * [mkdirs](#mkdirs)
+ * [pango-modules](#pango-modules)
+ * [pycompile](#pycompile)
+ * [register-shell](#register-shell)
+ * [system-accounts](#system-accounts)
+ * [update-desktopdb](#update-desktopdb)
+ * [x11-fonts](#x11-fonts)
+ * [xml-catalog](#xml-catalog)
* [Notes](#notes)
- * [Contributing via git](#contributing)
+ * [Contributing via git](#contributing-via-git)
* [Help](#help)
-<a id="Introduction"></a>
## Introduction
The `void-packages` repository contains all `source` packages that are the
@@ -117,7 +116,6 @@ If everything went fine after running
a binary package named `foo-1.0_1.<arch>.xbps` will be generated in the local repository
`hostdir/binpkgs`.
-<a id="quality_requirements"></a>
### Quality Requirements
Follow this list to determine if a piece of software or other technology may be
@@ -135,7 +133,6 @@ the Void packages system.
1. Required: Another package either within the repository or pending inclusion
requires the package.
-<a id="buildphase"></a>
### Package build phases
Building a package consist of the following phases:
@@ -169,10 +166,8 @@ via `make install` or any other compatible method.
successfully, the phase will be skipped later (unless its work directory
`${wrksrc}` is removed with `xbps-src clean`).
-<a id="namingconventions"></a>
### Package naming conventions
-<a id="libs"></a>
#### Libraries
Libraries are packages which provide shared objects (\*.so) in /usr/lib.
@@ -196,7 +191,6 @@ a linked program.
against this package. If the library is a sub package, its corresponding
development package should be named `lib<name>-devel`
-<a id="language_modules"></a>
#### Language Modules
Language modules are extensions to script or compiled languages. Those packages
@@ -217,7 +211,6 @@ for the language prefix.
Example: python-pam, perl-URI, python3-pyside2
-<a id="language_bindings"></a>
#### Language Bindings
Language Bindings are packages which allow programs or libraries to have
@@ -230,7 +223,6 @@ The naming convention to those packages is:
Example: gimp-python, irssi-perl
-<a id="programs"></a>
#### Programs
Programs put executables under /usr/bin (or in very special cases in other
@@ -246,7 +238,6 @@ Programs can be split into program packages and library packages. The program
package should be named as described above. The library package should be
prefixed with "lib" (see section `Libraries`)
-<a id="global_funcs"></a>
### Global functions
The following functions are defined by `xbps-src` and can be used on any template:
@@ -305,12 +296,11 @@ The following functions are defined by `xbps-src` and can be used on any templat
`$DESTDIR`. The optional 2nd argument can be used to change the
`file name`.
-- <a id="vlicense"></a>
*vlicense()* `vlicense <file> [<name>]`
Installs `file` into `usr/share/licenses/<pkgname>` in the pkg
`$DESTDIR`. The optional 2nd argument can be used to change the
- `file name`. See [license](#var_license) for when to use it.
+ `file name`. See [license](#mandatory-license) for when to use it.
- *vsv()* `vsv <service>`
@@ -333,7 +323,6 @@ The following functions are defined by `xbps-src` and can be used on any templat
> Shell wildcards must be properly quoted, Example: `vmove "usr/lib/*.a"`.
-<a id="global_vars"></a>
### Global variables
The following variables are defined by `xbps-src` and can be used on any template:
@@ -393,10 +382,8 @@ in this directory such as `${XBPS_BUILDDIR}/${wrksrc}`.
- `XBPS_RUST_TARGET` The target architecture triplet used by `rustc` and `cargo`.
-<a id="available_vars"></a>
### Available variables
-<a id="mandatory_vars"></a>
#### Mandatory variables
The list of mandatory variables for a template:
@@ -404,8 +391,7 @@ The list of mandatory variables for a template:
- `homepage` A string pointing to the `upstream` homepage.
-- <a id="var_license"></a>
-`license` A string matching the license's [SPDX Short identifier](https://spdx.org/licenses),
+- `license` A string matching the license's [SPDX Short identifier](https://spdx.org/licenses),
`Public Domain`, or string prefixed with `custom:` for other licenses.
Multiple licenses should be separated by commas, Example: `GPL-3.0-or-later, custom:Hugware`.
@@ -432,7 +418,6 @@ the generated `binary packages` have been modified.
- `version` A string with the package version. Must not contain dashes or underscore
and at least one digit is required. Shell's variable substition usage is not allowed.
-<a id="optional_vars"></a>
#### Optional variables
- `hostmakedepends` The list of `host` dependencies required to build the package, and
@@ -702,8 +687,7 @@ Examples:
archs=noarch
```
-<a id="explain_depends"></a>
-#### About the many types of `depends` variable.
+#### About the many types of `depends` variables
So far we have listed four types of `depends`, there are `hostmakedepends`,
`makedepends`, `checkdepends` and plain old `depends`.To understand the difference
@@ -734,10 +718,8 @@ Finally, as a general rule, if something compiles the exact same way whether or
not you add a particular package to `makedepends` or `hostmakedepends`, it
shouldn't be added.
-<a id="repositories"></a>
#### Repositories
-<a id="repo_by_branch"></a>
##### Repositories defined by Branch
The global repository takes the name of
@@ -745,7 +727,6 @@ 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
update multiple packages in a second branch without polluting his local repository.
-<a id="pkg_defined_repo"></a>
##### Package defined Repositories
The second way to define a repository is by setting the `repository` variable in
@@ -758,7 +739,6 @@ The following repository names are valid:
* `nonfree`: Repository for closed source packages.
-<a id="updates"></a>
### Checking for new upstream releases
New upstream versions can be automatically checked using
@@ -797,7 +777,6 @@ in url. Defaults to `(|v|$pkgname)[-_.]*`.
part that follows numeric part of version directory
in url. Defaults to `(|\.x)`.
-<a id="patches"></a>
### Handling patches
Sometimes software needs to be patched, most commonly to fix bugs that have
@@ -820,8 +799,7 @@ be used to set the args passed to `patch(1)`. As an example, if `foo.patch` requ
special arguments to be passed to `patch(1)` that can't be used when applying other
patches, `foo.patch.args` can be created containing those args.
-<a id="build_scripts"></a>
-### build style scripts
+### 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
@@ -933,8 +911,7 @@ matching the `build_style` name, Example:
`common/environment/build-style/gnu-configure.sh`
-<a id="build_helper"></a>
-### build helper scripts
+### build\_helper scripts
The `build_helper` variable specifies shell snippets to be sourced that will create a
suitable environment for working with certain sets of packages.
@@ -963,7 +940,6 @@ This aims to fix cross-builds for when the build-style is mixed: e.g. when in a
`gnu-configure` style the configure script calls `qmake` or a `Makefile` in
`gnu-makefile` style, respectively.
-<a id="functions"></a>
### Functions
The following functions can be defined to change the behavior of how the
@@ -1022,7 +998,6 @@ Current working directory for functions is set as follows:
- For pre_configure through post_install: `build_wrksrc`
if it is defined, otherwise `wrksrc`.
-<a id="build_options"></a>
### Build options
Some packages might be built with different build options to enable/disable
@@ -1127,7 +1102,6 @@ Example: `XBPS_PKG_OPTIONS_xorg_server=opt`.
The list of supported package build options and its description is defined in the
`common/options.description` file.
-<a id="deps_runtime"></a>
#### Runtime dependencies
Dependencies for ELF objects are detected automatically by `xbps-src`, hence runtime
@@ -1167,7 +1141,6 @@ 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
when the package is being built with `xbps-src`.
-<a id="install_remove_files"></a>
### INSTALL and REMOVE files
The INSTALL and REMOVE shell snippets can be used to execute certain actions at a specified
@@ -1211,7 +1184,6 @@ be executed via `chroot(2)` won't work correctly.
> NOTE: do not use INSTALL/REMOVE scripts to print messages, see the next section for
more information.
-<a id="install_remove_files_msg"></a>
### INSTALL.msg and REMOVE.msg files
The `INSTALL.msg` and `REMOVE.msg` files can be used to print a message at post-install
@@ -1222,7 +1194,6 @@ 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
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
There's a trigger along with some variables that are specifically to create
@@ -1254,7 +1225,6 @@ accounts.
> NOTE: The underscore policy does not apply to old packages, due to the inevitable breakage of
> changing the username only new packages should follow it.
-<a id="writing_runit_services"></a>
### Writing runit services
Void Linux uses [runit](http://smarden.org/runit/) for booting and supervision of services.
@@ -1293,7 +1263,6 @@ If the service requires directories in parts of the system that are not generall
temporary filesystems. Then use the `make_dirs` variable in the template to create
those directories when the package is installed.
-<a id="32bit_pkgs"></a>
### 32bit packages
32bit packages are built automatically when the builder is x86 (32bit), but
@@ -1315,7 +1284,6 @@ This expects the basename of the target file, Example: `lib32symlinks="foo"`.
- `lib32mode` If unset, only shared/static libraries and pkg-config files will be copied to the
**32bit** package. If set to `full` all files will be copied to the 32bit package, unmodified.
-<a id="pkgs_sub"></a>
### Subpackages
In the example shown above just a binary package is generated, but with some
@@ -1375,7 +1343,6 @@ destdir (`$DESTDIR`) to the `subpackage` destdir (`$PKGDESTDIR`).
Subpackages are processed always in alphabetical order; To force a custom order,
the `subpackages` variable can be declared with the wanted order.
-<a id="pkgs_development"></a>
### Development packages
A development package, commonly generated as a subpackage, shall only contain
@@ -1405,7 +1372,6 @@ following subset of files from the main package:
* Gobject introspection XML files `usr/share/gir-1.0`
* Vala bindings `usr/share/vala`
-<a id="pkgs_data"></a>
### Data packages
Another common subpackage type is the `-data` subpackage. This subpackage
@@ -1417,7 +1383,6 @@ or card material (maps). Data subpackages are almost always `archs=noarch`.
The main package must then have `depends="${pkgname}-data-${version}_${revision}"`,
possibly in addition to other, non-automatic depends.
-<a id="pkgs_documentation"></a>
### Documentation packages
Packages intended for user interaction do not always unconditionally require
@@ -1432,7 +1397,6 @@ building packages depending on a specific package there is no need to install la
amounts of documentation for no reason. Thus the size of the documentation part should
be your guidance to decide whether or not to split off a `-doc` subpackage.
-<a id="pkgs_python"></a>
### Python packages
Python packages should be built with the `python{,2,3}-module` build style, if possible.
@@ -1481,7 +1445,6 @@ Also, a set of useful variables are defined to use in the templates:
> NOTE: it's expected that additional subpkgs must be generated to allow packaging for multiple
python versions.
-<a id="pkgs_go"></a>
### Go packages
Go packages should be built with the `go` build style, if possible.
@@ -1518,7 +1481,6 @@ otherwise preping some assets. If possible do this in pre_build().
The path to the package's source inside `$GOPATH` is available as
`$GOSRCPATH`.
-<a id="pkgs_haskell"></a>
### Haskell packages
We build Haskell package using `stack` from
@@ -1536,7 +1498,6 @@ The following variables influence how Haskell packages are built:
- `make_build_args`: This is passed as-is to `stack build ...`, so
you can add your `--flag ...` parameters there.
-<a id="pkgs_font"></a>
### Font packages
Font packages are very straightforward to write, they are always set with the
@@ -1548,7 +1509,6 @@ cache during the install/removal of the package
- `font_dirs`: which should be set to the directory where the package
installs its fonts
-<a id="pkg_remove"></a>
### Removing a package
Follows a list of things that should be done to help guarantee that a
@@ -1576,7 +1536,6 @@ the source of those patches/files.
- Remove the package from the repository index
or contact a team member that can do so.
-<a id="xbps_triggers"></a>
### XBPS Triggers
XBPS triggers are a collection of snippets of code, provided by the `xbps-triggers`
@@ -1591,7 +1550,6 @@ package.
This is not a complete overview of the package. It is recommended to read the variables
referenced and the triggers themselves.
-<a id="triggers_appstream_cache"></a>
#### appstream-cache
The appstream-cache trigger is responsible for rebuilding the appstream metadata cache.
@@ -1613,7 +1571,6 @@ directory.
It is automatically added to packages that have XML files under one of the directories
searched by appstreamcli.
-<a id="triggers_binfmts"></a>
#### binfmts
The binfmts trigger is responsible for registration and removal of arbitrary
@@ -1625,7 +1582,6 @@ to register/remove entries from the arbitrary executable binary formats database
To include the trigger use the `binfmts` variable, as the trigger won't do anything unless
it is defined.
-<a id="triggers_dkms"></a>
#### dkms
The dkms trigger is responsible for compiling and removing dynamic kernel modules of a
@@ -1638,7 +1594,6 @@ the corresponding module will be removed
To include the trigger use the `dkms_modules` variable, as the trigger won't do anything
unless it is defined.
-<a id="triggers_gconf_schemas"></a>
#### gconf-schemas
The gconf-schemas trigger is responsible for registering and removing .schemas and
@@ -1655,7 +1610,6 @@ It is automatically added to packages that have `/usr/share/gconf/schemas` prese
as a directory. All files with the schemas file extension under that directory
are passed to the trigger.
-<a id="triggers_gdk_pixbuf_loaders"></a>
#### gdk-pixbuf-loaders
The gdk-pixbuf-loaders trigger is responsible for maintaining the GDK Pixbuf loaders cache.
@@ -1669,7 +1623,6 @@ It can be added by defining `gdk-pixbuf-loaders` in the `triggers` variable. It
added automatically to any package that has the path `usr/lib/gdk-pixbuf-2.0/2.10.0/loaders`
available as a directory.
-<a id="triggers_gio_modules"></a>
#### gio-modules
The gio-modules trigger is responsible for updating the Glib GIO module cache with
@@ -1681,7 +1634,6 @@ present under `usr/lib/gio/modules`.
It is automatically added to packages that have `/usr/lib/gio/modules` present
as a directory.
-<a id="triggers_gsettings_schemas"></a>
#### gsettings-schemas
The gsettings-schemas trigger is responsible for compiling Glib's GSettings XML
@@ -1696,7 +1648,6 @@ During removal of the glib package it deletes all files inside
It is automatically added to packages that have `/usr/share/glib-2.0/schemas` present
as a directory.
-<a id="triggers_gtk_icon_cache"></a>
#### gtk-icon-cache
The gtk-icon-cache trigger is responsible for updating the gtk+ icon cache.
@@ -1710,7 +1661,6 @@ It is automatically added on packages that have `/usr/share/icons` available
as a directory, all directories under that directory have their absolute path
passed to the trigger.
-<a id="triggers_gtk_immodules"></a>
#### gtk-immodules
The gtk-immodules trigger is responsible for updating the IM (Input Method) modules
@@ -1726,7 +1676,6 @@ During removal of the `gtk+` package it removes the cache file which is located
It is automatically added to packages that have `/usr/lib/gtk-2.0/2.10.0/immodules`
present as a directory.
-<a id="triggers_gtk_pixbuf_loaders"></a>
#### gtk-pixbuf-loaders
gtk-pixbuf-loaders is the old name for the current `gdk-pixbuf-loaders` trigger and is
@@ -1735,7 +1684,6 @@ compatibility measure.
For information about how it works refer to [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders).
-<a id="triggers_gtk3_immodules"></a>
#### gtk3-immodules
The gtk3-immodules trigger is responsible for updating the IM (Input Method) modules
@@ -1751,7 +1699,6 @@ During removal of the `gtk+3` package it removes the cache file which is located
It is automatically added to packages that have `/usr/lib/gtk-3.0/3.0.0/immodules`
present as a directory.
-<a id="triggers_hwdb.d_dir"></a>
#### hwdb.d-dir
The hwdb.d-dir trigger is responsible for updating the hardware database.
@@ -1761,7 +1708,6 @@ During installation and removal it runs `usr/bin/udevadm hwdb --root=. --update`
It is automatically added to packages that have `/usr/lib/udev/hwdb.d` present
as a directory.
-<a id="triggers_info_files"></a>
#### info-files
The info-files trigger is responsible for registering and unregistering the GNU info
@@ -1779,7 +1725,6 @@ registry located at `usr/share/info`.
If it is running under another architecture it tries to use the host's `install-info`
utility.
-<a id="triggers_kernel_hooks"></a>
#### kernel-hooks
The kernel-hooks trigger is responsible for running scripts during installation/removal
@@ -1797,7 +1742,6 @@ target.
It is automatically added if the helper variable `kernel_hooks_version` is defined.
However it is not obligatory to have it defined.
-<a id="triggers_mimedb"></a>
#### mimedb
The mimedb trigger is responsible for updating the shared-mime-info database.
@@ -1807,7 +1751,6 @@ In all runs it will just execute `update-mime-database -n usr/share/mime`.
It is automatically added to packages that have `/usr/share/mime` available as
a directory.
-<a id="triggers_mkdirs"></a>
#### mkdirs
The mkdirs trigger is responsible for creating and removing directories dictated
@@ -1832,7 +1775,6 @@ During removal it will delete the directory using `rmdir`.
To include this trigger use the `make_dirs` variable, as the trigger won't do anything
unless it is defined.
-<a id="triggers_pango_module"></a>
#### pango-modules
The pango-modules trigger is currently being removed since upstream has removed the
@@ -1846,7 +1788,6 @@ Currently it removes `etc/pango/pango.modules` file during removal of the pango
It can be added by defining `pango-modules` in the `triggers` variable and has no way to get
added automatically to a package.
-<a id="triggers_pycompile"></a>
#### pycompile
The pycompile trigger is responsible for compiling python code into native
@@ -1863,7 +1804,6 @@ trigger won't do anything unless at least one of those variables is defined.
A `python_version` variable can be set to direct behaviour of the trigger.
-<a id="triggers_register_shell"></a>
#### register-shell
The register-shell trigger is responsible for registering and removing shell entries
@@ -1877,7 +1817,6 @@ During removal it will use `sed` to delete the shell from the file.
To include this trigger use the `register_shell` variable, as the trigger won't do
anything unless it is defined.
-<a id="triggers_system_accounts"></a>
#### system-accounts
The system-accounts trigger is responsible for creating and disabling system accounts
@@ -1890,7 +1829,6 @@ Example: `transmission unprivileged user - for uninstalled package transmission`
This trigger can only be used by using the `system_accounts` variable.
-<a id="triggers_update_desktopdb"></a>
#### update-desktopdb
The update-desktopdb trigger is responsible for updating the system's MIME database.
@@ -1904,7 +1842,6 @@ was created during installation.
It is automatically added to packages that have `/usr/share/applications` available as
a directory.
-<a id="triggers_x11_fonts"></a>
#### x11-fonts
The x11-fonts trigger is responsible for rebuilding the fonts.dir and fonts.scale files
@@ -1916,7 +1853,6 @@ all font directories it was given via the `font_dirs` variable.
To include this trigger use the `font_dirs` variable, as the trigger won't do anything
unless it is defined.
-<a id="triggers_xml_catalog"></a>
#### xml-catalog
The xml-catalog trigger is responsible for registering and removing SGML/XML catalog entries.
@@ -1932,7 +1868,6 @@ During removal it uses `xmlcatmgr` to remove all catalogs passed to it by the
To include this trigger use the `sgml_entries` variable or/and the `xml_entries` variable,
as the trigger won't do anything unless either of them are defined.
-<a id="notes"></a>
### Notes
- Make sure that all software is configured to use the `/usr` prefix.
@@ -1951,7 +1886,6 @@ 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;
otherwise the `debug` packages won't have debugging symbols.
-<a id="contributing"></a>
### Contributing via git
Fork the voidlinux `void-packages` git repository on github and clone it:
@@ -1971,7 +1905,6 @@ to pull in new changes:
$ git remote add upstream git://github.com/void-linux/void-packages.git
$ git pull upstream master
-<a id="help"></a>
## Help
If after reading this `manual` you still need some kind of help, please join
From 9669f6f44da125c013774f2672766b54eacf032f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Mon, 4 May 2020 10:55:53 -0300
Subject: [PATCH 4/6] README.md: use markdown anchors instead of HTML flags
---
README.md | 41 ++++++++++++-----------------------------
1 file changed, 12 insertions(+), 29 deletions(-)
diff --git a/README.md b/README.md
index 752fb3d4fdc..47ad8f25252 100644
--- a/README.md
+++ b/README.md
@@ -17,22 +17,22 @@ for details of how to create source packages.
- [Requirements](#requirements)
- [Quick start](#quick-start)
- [chroot methods](#chroot-methods)
-- [Install the bootstrap packages](#install-bootstrap)
+- [Install the bootstrap packages](#install-the-bootstrap-packages)
- [Configuration](#configuration)
- [Directory hierarchy](#directory-hierarchy)
- [Building packages](#building-packages)
-- [Package build options](#build-options)
-- [Sharing and signing your local repositories](#sharing-and-signing)
-- [Rebuilding and overwriting existing local packages](#rebuilding)
-- [Enabling distcc for distributed compilation](#distcc)
+- [Package build options](#package-build-options)
+- [Sharing and signing your local repositories](#sharing-and-signing-your-local-repositories)
+- [Rebuilding and overwriting existing local packages](#rebuilding-and-overwriting-existing-local-packages)
+- [Enabling distcc for distributed compilation](#enabling-distcc-for-distributed-compilation)
- [Distfiles mirrors](#distfiles-mirrors)
-- [Cross compiling packages for a target architecture](#cross-compiling)
-- [Using xbps-src in a foreign Linux distribution](#foreign)
-- [Remaking the masterdir](#remaking-masterdir)
-- [Keeping your masterdir uptodate](#updating-masterdir)
-- [Building 32bit packages on x86_64](#building-32bit)
-- [Building packages natively for the musl C library](#building-for-musl)
-- [Building void base-system from scratch](#building-base-system)
+- [Cross compiling packages for a target architecture](#cross-compiling-packages-for-a-target-architecture)
+- [Using xbps-src in a foreign Linux distribution](#using-xbps-src-in-a-foreign-linux-distribution)
+- [Remaking the masterdir](#remaking-the-masterdir)
+- [Keeping your masterdir uptodate](#keeping-your-masterdir-uptodate)
+- [Building 32bit packages on x86\_64](#building-32bit-packages-on-x86_64)
+- [Building packages natively for the musl C library](#building-packages-natively-for-the-musl-c-library)
+- [Building void base-system from scratch](#building-void-base-system-from-scratch)
### Requirements
@@ -58,7 +58,6 @@ multiple utilities to accomplish this task:
> NOTE: `xbps-src` does not allow building as root anymore. Use one of the chroot
methods shown above.
-<a name="quick-start"></a>
### Quick start
Clone the `void-packages` git repository and install the bootstrap packages:
@@ -95,7 +94,6 @@ Alternatively, packages can be installed with the `xi` utility, from the `xtools
# xi <package_name>
```
-<a name="chroot-methods"></a>
### chroot methods
#### xbps-uunshare(1) (default)
@@ -149,7 +147,6 @@ To enable it:
$ cd void-packages
$ echo XBPS_CHROOT_CMD=proot >> etc/conf
-<a name="install-bootstrap"></a>
### Install the bootstrap packages
The `bootstrap` packages are a set of packages required to build any available source package in a container. There are two methods to install the `bootstrap`:
@@ -185,7 +182,6 @@ used as dependencies in the source packages tree.
If you want to customize those replacements, copy `etc/defaults.virtual` to `etc/virtual`
and edit it accordingly to your needs.
-<a name="directory-hierarchy"></a>
### Directory hierarchy
The following directory hierarchy is used with a default configuration file:
@@ -222,7 +218,6 @@ The description of these directories is as follows:
- `hostdir/sources`: to store package sources.
- `hostdir/binpkgs`: local repository to store generated binary packages.
-<a name="building-packages"></a>
### Building packages
The simplest form of building package is accomplished by running the `pkg` target in `xbps-src`:
@@ -249,7 +244,6 @@ It is possible to avoid using remote repositories completely by using the `-N` f
> The default local repository may contain multiple *sub-repositories*: `debug`, `multilib`, etc.
-<a name="build-options"></a>
### Package build options
The supported build options for a source package can be shown with `xbps-src show-options`:
@@ -289,7 +283,6 @@ i.e `XBPS_PKG_OPTIONS_xorg_server=opt`.
The list of supported package build options and its description is defined in the
`common/options.description` file or in the `template` file.
-<a name="sharing-and-signing"></a>
### Sharing and signing your local repositories
To share a local repository remotely it's mandatory to sign it and the binary packages
@@ -327,7 +320,6 @@ Each time a binary package is created, a package signature must be created with
> It is not possible to sign a repository with multiple RSA keys.
-<a name="rebuilding"></a>
### Rebuilding and overwriting existing local packages
If for whatever reason a package has been built and it is available in your local repository
@@ -343,7 +335,6 @@ Reinstalling this package in your target `rootdir` can be easily done too:
> Please note that the `package expression` must be properly defined to explicitly pick up
the package from the desired repository.
-<a name="distcc"></a>
### Enabling distcc for distributed compilation
Setup the slaves (machines that will compile the code):
@@ -374,7 +365,6 @@ The slave 192.168.2.101 has a CPU with 8 cores and the /9 for the number of jobs
The slave 192.168.2.102 is set to run at most 2 compile jobs to keep its load low, even if its CPU has 4 cores.
The XBPS_MAKEJOBS setting is increased to 16 to account for the possible parallelism (2 + 9 + 2 + some slack).
-<a name="distfiles-mirrors"></a>
### Distfiles mirror(s)
In etc/conf you may optionally define a mirror or a list of mirrors to search for distfiles.
@@ -399,7 +389,6 @@ using the `file://` prefix or simply an absolute path on your build host (e.g. /
Mirror locations specified this way are bind mounted inside the chroot environment
under $XBPS_MASTERDIR and searched for distfiles just the same as remote locations.
-<a name="cross-compiling"></a>
### Cross compiling packages for a target architecture
Currently `xbps-src` can cross build packages for some target architectures with a cross compiler.
@@ -411,7 +400,6 @@ If a source package has been adapted to be **cross buildable** `xbps-src` will a
If the build for whatever reason fails, might be a new build issue or simply because it hasn't been adapted to be **cross compiled**.
-<a name="foreign"></a>
### Using xbps-src in a foreign Linux distribution
xbps-src can be used in any recent Linux distribution matching the CPU architecture.
@@ -439,7 +427,6 @@ and `xbps-src` should be fully functional; just start the `bootstrap` process, i
The default masterdir is created in the current working directory, i.e `void-packages/masterdir`.
-<a name="remaking-masterdir"></a>
### Remaking the masterdir
If for some reason you must update xbps-src and the `bootstrap-update` target is not enough, it's possible to recreate a masterdir with two simple commands (please note that `zap` keeps your `ccache/distcc/host` directories intact):
@@ -447,14 +434,12 @@ If for some reason you must update xbps-src and the `bootstrap-update` target is
$ ./xbps-src zap
$ ./xbps-src binary-bootstrap
-<a name="updating-masterdir"></a>
### Keeping your masterdir uptodate
Sometimes the bootstrap packages must be updated to the latest available version in repositories, this is accomplished with the `bootstrap-update` target:
$ ./xbps-src bootstrap-update
-<a name="building-32bit"></a>
### Building 32bit packages on x86_64
Two ways are available to build 32bit packages on x86\_64:
@@ -471,7 +456,6 @@ The second mode (native) needs a new x86 `masterdir`:
$ ./xbps-src -m masterdir-x86 binary-bootstrap i686
$ ./xbps-src -m masterdir-x86 ...
-<a name="building-for-musl"></a>
### Building packages natively for the musl C library
A native build environment is required to be able to cross compile the bootstrap packages for the musl C library; this is accomplished by installing them via `binary-bootstrap`:
@@ -493,7 +477,6 @@ Your new masterdir is now ready to build packages natively for the musl C librar
To see if the musl C dynamic linker is working as expected.
-<a name="building-base-system"></a>
### Building void base-system from scratch
To rebuild all packages in `base-system` for your native architecture:
From 7e8b14ca5c5f83130a7ffe9323b735251ba2a851 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Mon, 4 May 2020 11:03:29 -0300
Subject: [PATCH 5/6] README.md: format with vmdfmt
---
README.md | 581 +++++++++++++++++++++++++++++++++---------------------
1 file changed, 358 insertions(+), 223 deletions(-)
diff --git a/README.md b/README.md
index 47ad8f25252..afe50b766be 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,18 @@
## The XBPS source packages collection
-This repository contains the XBPS source packages collection to build binary packages
-for the Void Linux distribution.
+This repository contains the XBPS source packages collection to build binary
+packages for the Void Linux distribution.
-The included `xbps-src` script will fetch and compile the sources, and install its
-files into a `fake destdir` to generate XBPS binary packages that can be installed
-or queried through the `xbps-install(1)` and `xbps-query(1)` utilities, respectively.
+The included `xbps-src` script will fetch and compile the sources, and install
+its files into a `fake destdir` to generate XBPS binary packages that can be
+installed or queried through the `xbps-install(1)` and `xbps-query(1)`
+utilities, respectively.
-See [Contributing](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
+See
+[Contributing](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
for a general overview of how to contribute and the
-[Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md)
-for details of how to create source packages.
+[Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md) for
+details of how to create source packages.
### Table of Contents
@@ -22,17 +24,24 @@ for details of how to create source packages.
- [Directory hierarchy](#directory-hierarchy)
- [Building packages](#building-packages)
- [Package build options](#package-build-options)
-- [Sharing and signing your local repositories](#sharing-and-signing-your-local-repositories)
-- [Rebuilding and overwriting existing local packages](#rebuilding-and-overwriting-existing-local-packages)
-- [Enabling distcc for distributed compilation](#enabling-distcc-for-distributed-compilation)
+- [Sharing and signing your local
+ repositories](#sharing-and-signing-your-local-repositories)
+- [Rebuilding and overwriting existing local
+ packages](#rebuilding-and-overwriting-existing-local-packages)
+- [Enabling distcc for distributed
+ compilation](#enabling-distcc-for-distributed-compilation)
- [Distfiles mirrors](#distfiles-mirrors)
-- [Cross compiling packages for a target architecture](#cross-compiling-packages-for-a-target-architecture)
-- [Using xbps-src in a foreign Linux distribution](#using-xbps-src-in-a-foreign-linux-distribution)
+- [Cross compiling packages for a target
+ architecture](#cross-compiling-packages-for-a-target-architecture)
+- [Using xbps-src in a foreign Linux
+ distribution](#using-xbps-src-in-a-foreign-linux-distribution)
- [Remaking the masterdir](#remaking-the-masterdir)
- [Keeping your masterdir uptodate](#keeping-your-masterdir-uptodate)
-- [Building 32bit packages on x86\_64](#building-32bit-packages-on-x86_64)
-- [Building packages natively for the musl C library](#building-packages-natively-for-the-musl-c-library)
-- [Building void base-system from scratch](#building-void-base-system-from-scratch)
+- [Building 32bit packages on x86_64](#building-32bit-packages-on-x86_64)
+- [Building packages natively for the musl C
+ library](#building-packages-natively-for-the-musl-c-library)
+- [Building void base-system from
+ scratch](#building-void-base-system-from-scratch)
### Requirements
@@ -45,18 +54,22 @@ for details of how to create source packages.
- objcopy(1), objdump(1), strip(1): binutils
- other common POSIX utilities included by default in almost all UNIX systems.
-`xbps-src` requires a utility to chroot and bind mount existing directories
-into a `masterdir` that is used as its main `chroot` directory. `xbps-src` supports
+`xbps-src` requires a utility to chroot and bind mount existing directories into
+a `masterdir` that is used as its main `chroot` directory. `xbps-src` supports
multiple utilities to accomplish this task:
- - `bwrap` - bubblewrap, see https://github.com/projectatomic/bubblewrap.
- - `ethereal` - only useful for one-shot containers, i.e docker (used with travis).
- - `xbps-uunshare(1)` - XBPS utility that uses `user_namespaces(7)` (part of xbps, default).
- - `xbps-uchroot(1)` - XBPS utility that uses `namespaces` and must be `setgid` (part of xbps).
- - `proot(1)` - utility that implements chroot/bind mounts in user space, see https://proot-me.github.io/.
+- `bwrap` - bubblewrap, see https://github.com/projectatomic/bubblewrap.
+- `ethereal` - only useful for one-shot containers, i.e docker (used with
+ travis).
+- `xbps-uunshare(1)` - XBPS utility that uses `user_namespaces(7)` (part of
+ xbps, default).
+- `xbps-uchroot(1)` - XBPS utility that uses `namespaces` and must be `setgid`
+ (part of xbps).
+- `proot(1)` - utility that implements chroot/bind mounts in user space, see
+ https://proot-me.github.io/.
-> NOTE: `xbps-src` does not allow building as root anymore. Use one of the chroot
-methods shown above.
+> NOTE: `xbps-src` does not allow building as root anymore. Use one of the
+> chroot methods shown above.
### Quick start
@@ -82,13 +95,16 @@ To build packages marked as 'restricted', modify `etc/conf`:
$ echo XBPS_ALLOW_RESTRICTED=yes >> etc/conf
```
-Once built, the package will be available in `hostdir/binpkgs` or an appropriate subdirectory (e.g. `hostdir/binpkgs/nonfree`). To install the package:
+Once built, the package will be available in `hostdir/binpkgs` or an appropriate
+subdirectory (e.g. `hostdir/binpkgs/nonfree`). To install the package:
```
# xbps-install --repository hostdir/binpkgs <package_name>
```
-Alternatively, packages can be installed with the `xi` utility, from the `xtools` package. `xi` takes the repository of the current working directory into account.
+Alternatively, packages can be installed with the `xi` utility, from the
+`xtools` package. `xi` takes the repository of the current working directory
+into account.
```
# xi <package_name>
@@ -100,380 +116,492 @@ Alternatively, packages can be installed with the `xi` utility, from the `xtools
This utility requires these Linux kernel options:
-- CONFIG\_NAMESPACES
-- CONFIG\_IPC\_NS
-- CONFIG\_UTS\_NS
-- CONFIG\_USER\_NS
+- CONFIG_NAMESPACES
+- CONFIG_IPC_NS
+- CONFIG_UTS_NS
+- CONFIG_USER_NS
-This is the default method, and if your system does not support any of the required kernel
-options it will fail with `EINVAL (Invalid argument)`.
+This is the default method, and if your system does not support any of the
+required kernel options it will fail with `EINVAL (Invalid argument)`.
#### xbps-uchroot(1)
This utility requires these Linux kernel options:
-- CONFIG\_NAMESPACES
-- CONFIG\_IPC\_NS
-- CONFIG\_PID\_NS
-- CONFIG\_UTS\_NS
+- CONFIG_NAMESPACES
+- CONFIG_IPC_NS
+- CONFIG_PID_NS
+- CONFIG_UTS_NS
-Your user must be added to a special group to be able to use `xbps-uchroot(1)` and the
-executable must be `setgid`:
+Your user must be added to a special group to be able to use `xbps-uchroot(1)`
+and the executable must be `setgid`:
- # chown root:<group> xbps-uchroot
- # chmod 4750 xbps-uchroot
- # usermod -a -G <group> <user>
+```
+# chown root:<group> xbps-uchroot
+# chmod 4750 xbps-uchroot
+# usermod -a -G <group> <user>
+```
-> NOTE: by default in void you shouldn't do this manually, your user must be a member of
-the `xbuilder` group.
+> NOTE: by default in void you shouldn't do this manually, your user must be a
+> member of the `xbuilder` group.
To enable it:
- $ cd void-packages
- $ echo XBPS_CHROOT_CMD=uchroot >> etc/conf
+```
+$ cd void-packages
+$ echo XBPS_CHROOT_CMD=uchroot >> etc/conf
+```
-If for some reason it's erroring out as `ERROR clone (Operation not permitted)`, check that
-your user is a member of the required `group` and that `xbps-uchroot(1)` utility has the
-proper permissions and owner/group as explained above.
+If for some reason it's erroring out as `ERROR clone (Operation not permitted)`,
+check that your user is a member of the required `group` and that
+`xbps-uchroot(1)` utility has the proper permissions and owner/group as
+explained above.
#### proot(1)
-The `proot(1)` utility implements chroot and bind mounts support completely in user space,
-and can be used if your Linux kernel does not have support for namespaces. See https://proot-me.github.io/.
-for more information.
+The `proot(1)` utility implements chroot and bind mounts support completely in
+user space, and can be used if your Linux kernel does not have support for
+namespaces. See https://proot-me.github.io/. for more information.
To enable it:
- $ cd void-packages
- $ echo XBPS_CHROOT_CMD=proot >> etc/conf
+```
+$ cd void-packages
+$ echo XBPS_CHROOT_CMD=proot >> etc/conf
+```
### Install the bootstrap packages
-The `bootstrap` packages are a set of packages required to build any available source package in a container. There are two methods to install the `bootstrap`:
-
- - `bootstrap`: all bootstrap packages will be built from scratch; additional utilities are required in the
-host system to allow building the `base-chroot` package: binutils, gcc, perl, texinfo, etc.
+The `bootstrap` packages are a set of packages required to build any available
+source package in a container. There are two methods to install the `bootstrap`:
- - `binary-bootstrap`: the bootstrap binary packages are downloaded via XBPS repositories.
+- `bootstrap`: all bootstrap packages will be built from scratch; additional
+ utilities are required in the host system to allow building the `base-chroot`
+ package: binutils, gcc, perl, texinfo, etc.
+- `binary-bootstrap`: the bootstrap binary packages are downloaded via XBPS
+ repositories.
-If you don't want to waste your time building everything from scratch probably it's better to use `binary-bootstrap`.
+If you don't want to waste your time building everything from scratch probably
+it's better to use `binary-bootstrap`.
### Configuration
-The `etc/defaults.conf` file contains the possible settings that can be overridden
-through the `etc/conf` configuration file for the `xbps-src` utility; if that file
-does not exist, will try to read configuration settings from `~/.xbps-src.conf`.
+The `etc/defaults.conf` file contains the possible settings that can be
+overridden through the `etc/conf` configuration file for the `xbps-src` utility;
+if that file does not exist, will try to read configuration settings from
+`~/.xbps-src.conf`.
-If you want to customize default `CFLAGS`, `CXXFLAGS` and `LDFLAGS`, don't override
-those defined in `etc/defaults.conf`, set them on `etc/conf` instead i.e:
+If you want to customize default `CFLAGS`, `CXXFLAGS` and `LDFLAGS`, don't
+override those defined in `etc/defaults.conf`, set them on `etc/conf` instead
+i.e:
- $ echo 'XBPS_CFLAGS="your flags here"' >> etc/conf
- $ echo 'XBPS_LDFLAGS="your flags here"' >> etc/conf
+```
+$ echo 'XBPS_CFLAGS="your flags here"' >> etc/conf
+$ echo 'XBPS_LDFLAGS="your flags here"' >> etc/conf
+```
-Native and cross compiler/linker flags are set per architecture in `common/build-profiles`
-and `common/cross-profiles` respectively. Ideally those settings are good enough by default,
-and there's no need to set your own unless you know what you are doing.
+Native and cross compiler/linker flags are set per architecture in
+`common/build-profiles` and `common/cross-profiles` respectively. Ideally those
+settings are good enough by default, and there's no need to set your own unless
+you know what you are doing.
#### Virtual packages
-The `etc/defaults.virtual` file contains the default replacements for virtual packages,
-used as dependencies in the source packages tree.
+The `etc/defaults.virtual` file contains the default replacements for virtual
+packages, used as dependencies in the source packages tree.
-If you want to customize those replacements, copy `etc/defaults.virtual` to `etc/virtual`
-and edit it accordingly to your needs.
+If you want to customize those replacements, copy `etc/defaults.virtual` to
+`etc/virtual` and edit it accordingly to your needs.
### Directory hierarchy
The following directory hierarchy is used with a default configuration file:
- /void-packages
- |- common
- |- etc
- |- srcpkgs
- | |- xbps
- | |- template
- |
- |- hostdir
- | |- binpkgs ...
- | |- ccache ...
- | |- distcc-<arch> ...
- | |- repocache ...
- | |- sources ...
- |
- |- masterdir
- | |- builddir -> ...
- | |- destdir -> ...
- | |- host -> bind mounted from <hostdir>
- | |- void-packages -> bind mounted from <void-packages>
-
+```
+ /void-packages
+ |- common
+ |- etc
+ |- srcpkgs
+ | |- xbps
+ | |- template
+ |
+ |- hostdir
+ | |- binpkgs ...
+ | |- ccache ...
+ | |- distcc-<arch> ...
+ | |- repocache ...
+ | |- sources ...
+ |
+ |- masterdir
+ | |- builddir -> ...
+ | |- destdir -> ...
+ | |- host -> bind mounted from <hostdir>
+ | |- void-packages -> bind mounted from <void-packages>
+```
The description of these directories is as follows:
- - `masterdir`: master directory to be used as rootfs to build/install packages.
- - `builddir`: to unpack package source tarballs and where packages are built.
- - `destdir`: to install packages, aka **fake destdir**.
- - `hostdir/ccache`: to store ccache data if the `XBPS_CCACHE` option is enabled.
- - `hostdir/distcc-<arch>`: to store distcc data if the `XBPS_DISTCC` option is enabled.
- - `hostdir/repocache`: to store binary packages from remote repositories.
- - `hostdir/sources`: to store package sources.
- - `hostdir/binpkgs`: local repository to store generated binary packages.
+- `masterdir`: master directory to be used as rootfs to build/install packages.
+- `builddir`: to unpack package source tarballs and where packages are built.
+- `destdir`: to install packages, aka **fake destdir**.
+- `hostdir/ccache`: to store ccache data if the `XBPS_CCACHE` option is enabled.
+- `hostdir/distcc-<arch>`: to store distcc data if the `XBPS_DISTCC` option is
+ enabled.
+- `hostdir/repocache`: to store binary packages from remote repositories.
+- `hostdir/sources`: to store package sources.
+- `hostdir/binpkgs`: local repository to store generated binary packages.
### Building packages
-The simplest form of building package is accomplished by running the `pkg` target in `xbps-src`:
+The simplest form of building package is accomplished by running the `pkg`
+target in `xbps-src`:
```
$ cd void-packages
$ ./xbps-src pkg <pkgname>
```
-When the package and its required dependencies are built, the binary packages will be created
-and registered in the default local repository at `hostdir/binpkgs`; the path to this local repository can be added to
-any xbps configuration file (see xbps.d(5)) or by explicitly appending them via cmdline, i.e:
+When the package and its required dependencies are built, the binary packages
+will be created and registered in the default local repository at
+`hostdir/binpkgs`; the path to this local repository can be added to any xbps
+configuration file (see xbps.d(5)) or by explicitly appending them via cmdline,
+i.e:
- $ xbps-install --repository=hostdir/binpkgs ...
- $ xbps-query --repository=hostdir/binpkgs ...
+```
+$ xbps-install --repository=hostdir/binpkgs ...
+$ xbps-query --repository=hostdir/binpkgs ...
+```
By default **xbps-src** will try to resolve package dependencies in this order:
- - If a dependency exists in the local repository, use it (`hostdir/binpkgs`).
- - If a dependency exists in a remote repository, use it.
- - If a dependency exists in a source package, use it.
+- If a dependency exists in the local repository, use it (`hostdir/binpkgs`).
+- If a dependency exists in a remote repository, use it.
+- If a dependency exists in a source package, use it.
-It is possible to avoid using remote repositories completely by using the `-N` flag.
+It is possible to avoid using remote repositories completely by using the `-N`
+flag.
-> The default local repository may contain multiple *sub-repositories*: `debug`, `multilib`, etc.
+> The default local repository may contain multiple *sub-repositories*: `debug`,
+> `multilib`, etc.
### Package build options
-The supported build options for a source package can be shown with `xbps-src show-options`:
+The supported build options for a source package can be shown with `xbps-src
+show-options`:
- $ ./xbps-src show-options foo
+```
+$ ./xbps-src show-options foo
+```
Build options can be enabled with the `-o` flag of `xbps-src`:
- $ ./xbps-src -o option,option1 pkg foo
+```
+$ ./xbps-src -o option,option1 pkg foo
+```
Build options can be disabled by prefixing them with `~`:
- $ ./xbps-src -o ~option,~option1 pkg foo
+```
+$ ./xbps-src -o ~option,~option1 pkg foo
+```
-Both ways can be used together to enable and/or disable multiple options
-at the same time with `xbps-src`:
+Both ways can be used together to enable and/or disable multiple options at the
+same time with `xbps-src`:
- $ ./xbps-src -o option,~option1,~option2 pkg foo
+```
+$ ./xbps-src -o option,~option1,~option2 pkg foo
+```
The build options can also be shown for binary packages via `xbps-query(1)`:
- $ xbps-query -R --property=build-options foo
+```
+$ xbps-query -R --property=build-options foo
+```
-> NOTE: if you build a package with a custom option, and that package is available
-in an official void repository, an update will ignore those options. Put that package
-on `hold` mode via `xbps-pkgdb(1)`, i.e `xbps-pkgdb -m hold foo` to ignore updates
-with `xbps-install -u`. Once the package is on `hold`, the only way to update it
-is by declaring it explicitly: `xbps-install -u foo`.
+> NOTE: if you build a package with a custom option, and that package is
+> available in an official void repository, an update will ignore those options.
+> Put that package on `hold` mode via `xbps-pkgdb(1)`, i.e `xbps-pkgdb -m hold
+> foo` to ignore updates with `xbps-install -u`. Once the package is on `hold`,
+> the only way to update it is by declaring it explicitly: `xbps-install -u
+> foo`.
-Permanent global package build options can be set via `XBPS_PKG_OPTIONS` variable in the
-`etc/conf` configuration file. Per package build options can be set via
-`XBPS_PKG_OPTIONS_<pkgname>`.
+Permanent global package build options can be set via `XBPS_PKG_OPTIONS`
+variable in the `etc/conf` configuration file. Per package build options can be
+set via `XBPS_PKG_OPTIONS_<pkgname>`.
-> NOTE: if `pkgname` contains `dashes`, those should be replaced by `underscores`
-i.e `XBPS_PKG_OPTIONS_xorg_server=opt`.
+> NOTE: if `pkgname` contains `dashes`, those should be replaced by
+> `underscores` i.e `XBPS_PKG_OPTIONS_xorg_server=opt`.
-The list of supported package build options and its description is defined in the
-`common/options.description` file or in the `template` file.
+The list of supported package build options and its description is defined in
+the `common/options.description` file or in the `template` file.
### Sharing and signing your local repositories
-To share a local repository remotely it's mandatory to sign it and the binary packages
-stored on it. This is accomplished with the `xbps-rindex(1)` utility.
+To share a local repository remotely it's mandatory to sign it and the binary
+packages stored on it. This is accomplished with the `xbps-rindex(1)` utility.
First a RSA key must be created with `openssl(1)` or `ssh-keygen(1)`:
- $ openssl genrsa -des3 -out privkey.pem 4096
+```
+$ openssl genrsa -des3 -out privkey.pem 4096
+```
or
- $ ssh-keygen -t rsa -b 4096 -m PEM -f privkey.pem
+```
+$ ssh-keygen -t rsa -b 4096 -m PEM -f privkey.pem
+```
> Only RSA keys in PEM format are currently accepted by xbps.
-Once the RSA private key is ready you can use it to initialize the repository metadata:
+Once the RSA private key is ready you can use it to initialize the repository
+metadata:
- $ xbps-rindex --sign --signedby "I'm Groot" --privkey privkey.pem $PWD/hostdir/binpkgs
+```
+$ xbps-rindex --sign --signedby "I'm Groot" --privkey privkey.pem $PWD/hostdir/binpkgs
+```
And then make a signature per package:
- $ xbps-rindex --sign-pkg --privkey privkey.pem $PWD/hostdir/binpkgs/*.xbps
+```
+$ xbps-rindex --sign-pkg --privkey privkey.pem $PWD/hostdir/binpkgs/*.xbps
+```
> If --privkey is unset, it defaults to `~/.ssh/id_rsa`.
-If the RSA key was protected with a passphrase you'll have to type it, or alternatively set
-it via the `XBPS_PASSPHRASE` environment variable.
+If the RSA key was protected with a passphrase you'll have to type it, or
+alternatively set it via the `XBPS_PASSPHRASE` environment variable.
-Once the binary packages have been signed, check the repository contains the appropriate `hex fingerprint`:
+Once the binary packages have been signed, check the repository contains the
+appropriate `hex fingerprint`:
- $ xbps-query --repository=hostdir/binpkgs -vL
- ...
+```
+$ xbps-query --repository=hostdir/binpkgs -vL
+...
+```
-Each time a binary package is created, a package signature must be created with `--sign-pkg`.
+Each time a binary package is created, a package signature must be created with
+`--sign-pkg`.
> It is not possible to sign a repository with multiple RSA keys.
### Rebuilding and overwriting existing local packages
-If for whatever reason a package has been built and it is available in your local repository
-and you have to rebuild it without bumping its `version` or `revision` fields, it is possible
-to accomplish this task easily with `xbps-src`:
+If for whatever reason a package has been built and it is available in your
+local repository and you have to rebuild it without bumping its `version` or
+`revision` fields, it is possible to accomplish this task easily with
+`xbps-src`:
- $ ./xbps-src -f pkg xbps
+```
+$ ./xbps-src -f pkg xbps
+```
Reinstalling this package in your target `rootdir` can be easily done too:
- $ xbps-install --repository=/path/to/local/repo -yff xbps-0.25_1
+```
+$ xbps-install --repository=/path/to/local/repo -yff xbps-0.25_1
+```
-> Please note that the `package expression` must be properly defined to explicitly pick up
-the package from the desired repository.
+> Please note that the `package expression` must be properly defined to
+> explicitly pick up the package from the desired repository.
### Enabling distcc for distributed compilation
Setup the slaves (machines that will compile the code):
- # xbps-install -Sy distcc
+```
+# xbps-install -Sy distcc
+```
-Modify the configuration to allow your local network machines to use distcc (e.g. `192.168.2.0/24`):
+Modify the configuration to allow your local network machines to use distcc
+(e.g. `192.168.2.0/24`):
- # echo "192.168.2.0/24" >> /etc/distcc/clients.allow
+```
+# echo "192.168.2.0/24" >> /etc/distcc/clients.allow
+```
Enable and start the `distccd` service:
- # ln -s /etc/sv/distccd /var/service
+```
+# ln -s /etc/sv/distccd /var/service
+```
-Install distcc on the host (machine that executes xbps-src) as well.
-Unless you want to use the host as slave from other machines, there is no need
-to modify the configuration.
+Install distcc on the host (machine that executes xbps-src) as well. Unless you
+want to use the host as slave from other machines, there is no need to modify
+the configuration.
On the host you can now enable distcc in the `void-packages/etc/conf` file:
- XBPS_DISTCC=yes
- XBPS_DISTCC_HOSTS="localhost/2 --localslots_cpp=24 192.168.2.101/9 192.168.2.102/2"
- XBPS_MAKEJOBS=16
+```
+XBPS_DISTCC=yes
+XBPS_DISTCC_HOSTS="localhost/2 --localslots_cpp=24 192.168.2.101/9 192.168.2.102/2"
+XBPS_MAKEJOBS=16
+```
-The example values assume a localhost CPU with 4 cores of which at most 2 are used for compiler jobs.
-The number of slots for preprocessor jobs is set to 24 in order to have enough preprocessed data for other CPUs to compile.
-The slave 192.168.2.101 has a CPU with 8 cores and the /9 for the number of jobs is a saturating choice.
-The slave 192.168.2.102 is set to run at most 2 compile jobs to keep its load low, even if its CPU has 4 cores.
-The XBPS_MAKEJOBS setting is increased to 16 to account for the possible parallelism (2 + 9 + 2 + some slack).
+The example values assume a localhost CPU with 4 cores of which at most 2 are
+used for compiler jobs. The number of slots for preprocessor jobs is set to 24
+in order to have enough preprocessed data for other CPUs to compile. The slave
+192.168.2.101 has a CPU with 8 cores and the /9 for the number of jobs is a
+saturating choice. The slave 192.168.2.102 is set to run at most 2 compile jobs
+to keep its load low, even if its CPU has 4 cores. The XBPS_MAKEJOBS setting is
+increased to 16 to account for the possible parallelism (2 + 9 + 2 + some
+slack).
### Distfiles mirror(s)
-In etc/conf you may optionally define a mirror or a list of mirrors to search for distfiles.
+In etc/conf you may optionally define a mirror or a list of mirrors to search
+for distfiles.
- $ echo 'XBPS_DISTFILES_MIRROR="ftp://192.168.100.5/gentoo/distfiles"' >> etc/conf
+```
+$ echo 'XBPS_DISTFILES_MIRROR="ftp://192.168.100.5/gentoo/distfiles"' >> etc/conf
+```
-If more than one mirror is to be searched, you can either specify multiple URLs separated
-with blanks, or add to the variable like this
+If more than one mirror is to be searched, you can either specify multiple URLs
+separated with blanks, or add to the variable like this
- $ echo 'XBPS_DISTFILES_MIRROR+=" http://repo.voidlinux.de/distfiles"' >> etc/conf
+```
+$ echo 'XBPS_DISTFILES_MIRROR+=" http://repo.voidlinux.de/distfiles"' >> etc/conf
+```
Make sure to put the blank after the first double quote in this case.
The mirrors are searched in order for the distfiles to build a package until the
checksum of the downloaded file matches the one specified in the template.
-Ultimately, if no mirror carries the distfile, or in case all downloads failed the
-checksum verification, the original download location is used.
+Ultimately, if no mirror carries the distfile, or in case all downloads failed
+the checksum verification, the original download location is used.
-If you use `proot` or `uchroot` for your XBPS_CHROOT_CMD, you may also specify a local path
-using the `file://` prefix or simply an absolute path on your build host (e.g. /mnt/distfiles).
-Mirror locations specified this way are bind mounted inside the chroot environment
-under $XBPS_MASTERDIR and searched for distfiles just the same as remote locations.
+If you use `proot` or `uchroot` for your XBPS_CHROOT_CMD, you may also specify a
+local path using the `file://` prefix or simply an absolute path on your build
+host (e.g. /mnt/distfiles). Mirror locations specified this way are bind mounted
+inside the chroot environment under $XBPS_MASTERDIR and searched for distfiles
+just the same as remote locations.
### Cross compiling packages for a target architecture
-Currently `xbps-src` can cross build packages for some target architectures with a cross compiler.
-The supported target is shown with `./xbps-src -h`.
+Currently `xbps-src` can cross build packages for some target architectures with
+a cross compiler. The supported target is shown with `./xbps-src -h`.
-If a source package has been adapted to be **cross buildable** `xbps-src` will automatically build the binary package(s) with a simple command:
+If a source package has been adapted to be **cross buildable** `xbps-src` will
+automatically build the binary package(s) with a simple command:
- $ ./xbps-src -a <target> pkg <pkgname>
+```
+$ ./xbps-src -a <target> pkg <pkgname>
+```
-If the build for whatever reason fails, might be a new build issue or simply because it hasn't been adapted to be **cross compiled**.
+If the build for whatever reason fails, might be a new build issue or simply
+because it hasn't been adapted to be **cross compiled**.
### Using xbps-src in a foreign Linux distribution
-xbps-src can be used in any recent Linux distribution matching the CPU architecture.
+xbps-src can be used in any recent Linux distribution matching the CPU
+architecture.
-To use xbps-src in your Linux distribution use the following instructions. Let's start downloading the xbps static binaries:
+To use xbps-src in your Linux distribution use the following instructions. Let's
+start downloading the xbps static binaries:
- $ wget http://alpha.de.repo.voidlinux.org/static/xbps-static-latest.<arch>-musl.tar.xz
- $ mkdir ~/XBPS
- $ tar xvf xbps-static-latest.<arch>.tar.xz -C ~/XBPS
- $ export PATH=~/XBPS/usr/bin:$PATH
+```
+$ wget http://alpha.de.repo.voidlinux.org/static/xbps-static-latest.<arch>-musl.tar.xz
+$ mkdir ~/XBPS
+$ tar xvf xbps-static-latest.<arch>.tar.xz -C ~/XBPS
+$ export PATH=~/XBPS/usr/bin:$PATH
+```
-If your system does not support `user namespaces`, a privileged group is required to be able to use
-`xbps-uchroot(1)` with xbps-src, by default it's set to the `xbuilder` group, change this to your desired group:
+If your system does not support `user namespaces`, a privileged group is
+required to be able to use `xbps-uchroot(1)` with xbps-src, by default it's set
+to the `xbuilder` group, change this to your desired group:
- # chown root:<group> ~/XBPS/usr/bin/xbps-uchroot.static
- # chmod 4750 ~/XBPS/usr/bin/xbps-uchroot.static
+```
+# chown root:<group> ~/XBPS/usr/bin/xbps-uchroot.static
+# chmod 4750 ~/XBPS/usr/bin/xbps-uchroot.static
+```
Clone the `void-packages` git repository:
- $ git clone git://github.com/void-linux/void-packages
+```
+$ git clone git://github.com/void-linux/void-packages
+```
-and `xbps-src` should be fully functional; just start the `bootstrap` process, i.e:
+and `xbps-src` should be fully functional; just start the `bootstrap` process,
+i.e:
- $ ./xbps-src binary-bootstrap
+```
+$ ./xbps-src binary-bootstrap
+```
-The default masterdir is created in the current working directory, i.e `void-packages/masterdir`.
+The default masterdir is created in the current working directory, i.e
+`void-packages/masterdir`.
### Remaking the masterdir
-If for some reason you must update xbps-src and the `bootstrap-update` target is not enough, it's possible to recreate a masterdir with two simple commands (please note that `zap` keeps your `ccache/distcc/host` directories intact):
+If for some reason you must update xbps-src and the `bootstrap-update` target is
+not enough, it's possible to recreate a masterdir with two simple commands
+(please note that `zap` keeps your `ccache/distcc/host` directories intact):
- $ ./xbps-src zap
- $ ./xbps-src binary-bootstrap
+```
+$ ./xbps-src zap
+$ ./xbps-src binary-bootstrap
+```
### Keeping your masterdir uptodate
-Sometimes the bootstrap packages must be updated to the latest available version in repositories, this is accomplished with the `bootstrap-update` target:
+Sometimes the bootstrap packages must be updated to the latest available version
+in repositories, this is accomplished with the `bootstrap-update` target:
- $ ./xbps-src bootstrap-update
+```
+$ ./xbps-src bootstrap-update
+```
### Building 32bit packages on x86_64
-Two ways are available to build 32bit packages on x86\_64:
+Two ways are available to build 32bit packages on x86_64:
- - cross compilation mode
- - native mode with a 32bit masterdir
+- cross compilation mode
+- native mode with a 32bit masterdir
The first mode (cross compilation) is as easy as:
- $ ./xbps-src -a i686 pkg ...
+```
+$ ./xbps-src -a i686 pkg ...
+```
The second mode (native) needs a new x86 `masterdir`:
- $ ./xbps-src -m masterdir-x86 binary-bootstrap i686
- $ ./xbps-src -m masterdir-x86 ...
+```
+$ ./xbps-src -m masterdir-x86 binary-bootstrap i686
+$ ./xbps-src -m masterdir-x86 ...
+```
### Building packages natively for the musl C library
-A native build environment is required to be able to cross compile the bootstrap packages for the musl C library; this is accomplished by installing them via `binary-bootstrap`:
+A native build environment is required to be able to cross compile the bootstrap
+packages for the musl C library; this is accomplished by installing them via
+`binary-bootstrap`:
- $ ./xbps-src binary-bootstrap
+```
+$ ./xbps-src binary-bootstrap
+```
Now cross compile `base-chroot-musl` for your native architecture:
- $ ./xbps-src -a x86_64-musl pkg base-chroot-musl
+```
+$ ./xbps-src -a x86_64-musl pkg base-chroot-musl
+```
-Wait until all packages are built and when ready, prepare a new masterdir with the musl packages:
+Wait until all packages are built and when ready, prepare a new masterdir with
+the musl packages:
- $ ./xbps-src -m masterdir-x86_64-musl binary-bootstrap x86_64-musl
+```
+$ ./xbps-src -m masterdir-x86_64-musl binary-bootstrap x86_64-musl
+```
-Your new masterdir is now ready to build packages natively for the musl C library. Try:
+Your new masterdir is now ready to build packages natively for the musl C
+library. Try:
- $ ./xbps-src -m masterdir-x86_64-musl chroot
- $ ldd
+```
+$ ./xbps-src -m masterdir-x86_64-musl chroot
+$ ldd
+```
To see if the musl C dynamic linker is working as expected.
@@ -481,14 +609,21 @@ To see if the musl C dynamic linker is working as expected.
To rebuild all packages in `base-system` for your native architecture:
- $ ./xbps-src -N pkg base-system
+```
+$ ./xbps-src -N pkg base-system
+```
It's also possible to cross compile everything from scratch:
- $ ./xbps-src -a <target> -N pkg base-system
+```
+$ ./xbps-src -a <target> -N pkg base-system
+```
-Once the build has finished, you can specify the path to the local repository to `void-mklive`, i.e:
+Once the build has finished, you can specify the path to the local repository to
+`void-mklive`, i.e:
- # cd void-mklive
- # make
- # ./mklive.sh ... -r /path/to/hostdir/binpkgs
+```
+# cd void-mklive
+# make
+# ./mklive.sh ... -r /path/to/hostdir/binpkgs
+```
From 6856243fa5b65e158092f209660e1238cae9b1e0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Mon, 4 May 2020 11:07:11 -0300
Subject: [PATCH 6/6] README, CONTRIBUTING, Manual: use file names instead of
links for files inside the repo
---
CONTRIBUTING.md | 16 ++++++----------
Manual.md | 2 +-
README.md | 8 +++-----
3 files changed, 10 insertions(+), 16 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1a90e742ee0..c3240cd591c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -11,11 +11,9 @@ packages, correcting bugs and adding features to void-packages.
If you really want to get a package into Void Linux, we recommend you package it
yourself.
-We provide a [comprehensive
-Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md) on
-how to create new packages. There's also a [manual for
-xbps-src](https://github.com/void-linux/void-packages/blob/master/README.md),
-which is used to build package files from templates.
+We provide a [comprehensive Manual](./Manual.md) on how to create new packages.
+There's also a [manual for xbps-src](./README.md), which is used to build
+package files from templates.
For this guide, we assume you have basic knowledge about
[git](http://git-scm.org), as well as a [GitHub Account](http://github.com).
@@ -37,9 +35,8 @@ Templates must have the name `void-packages/srcpkgs/<pkgname>/template`, where
`pkgname` is the same as the `pkgname` variable in the template.
For deeper insights on the contents of template files, please read the
-[manual](https://github.com/void-linux/void-packages/blob/master/Manual.md), and
-be sure to browse the existing template files in the `srcpkgs` directory of this
-repository for concrete examples.
+[manual](./Manual.md), and be sure to browse the existing template files in the
+`srcpkgs` directory of this repository for concrete examples.
When you've finished working on the template file, please check it with `xlint`
helper from the [xtools](https://github.com/chneukirchen/xtools) package:
@@ -69,8 +66,7 @@ If you want to describe your changes in more detail, add an empty line followed
by those details
([example](https://github.com/void-linux/void-packages/commit/f1c45a502086ba1952f23ace9084a870ce437bc6)).
-For further information, please consult the
-[manual](https://github.com/void-linux/void-packages/blob/master/Manual.md).
+For further information, please consult the [manual](./Manual.md).
`xbump`, available in the [xtools](https://github.com/chneukirchen/xtools)
package, can be used to commit a new or updated package:
diff --git a/Manual.md b/Manual.md
index b1cf9f9dc20..f1c82b66bdc 100644
--- a/Manual.md
+++ b/Manual.md
@@ -1892,7 +1892,7 @@ Fork the voidlinux `void-packages` git repository on github and clone it:
$ git clone git@github.com:<user>/void-packages.git
-See [CONTRIBUTING.md](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
+See [CONTRIBUTING.md](./CONTRIBUTING.md)
for information on how to format your commits and other tips for
contributing.
diff --git a/README.md b/README.md
index afe50b766be..13c677062c2 100644
--- a/README.md
+++ b/README.md
@@ -8,11 +8,9 @@ its files into a `fake destdir` to generate XBPS binary packages that can be
installed or queried through the `xbps-install(1)` and `xbps-query(1)`
utilities, respectively.
-See
-[Contributing](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
-for a general overview of how to contribute and the
-[Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md) for
-details of how to create source packages.
+See [Contributing](./CONTRIBUTING.md) for a general overview of how to
+contribute and the [Manual](./Manual.md) for details of how to create source
+packages.
### Table of Contents
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Run vmdfmt in the markdown files and update some information there
2020-05-04 14:20 [PR PATCH] Run vmdfmt in the markdown files and update some information there ericonr
2020-05-04 14:27 ` Duncaen
2020-05-04 14:31 ` [PR PATCH] [Updated] " ericonr
@ 2020-05-04 17:37 ` ericonr
2020-05-04 23:30 ` [PR PATCH] [Updated] " ericonr
` (4 subsequent siblings)
7 siblings, 0 replies; 9+ messages in thread
From: ericonr @ 2020-05-04 17:37 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 235 bytes --]
New comment by ericonr on void-packages repository
https://github.com/void-linux/void-packages/pull/21609#issuecomment-623603107
Comment:
@ahesford mentioned they thought it'd be better if the lines wrapped. I can revert it, though.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PR PATCH] [Updated] Run vmdfmt in the markdown files and update some information there
2020-05-04 14:20 [PR PATCH] Run vmdfmt in the markdown files and update some information there ericonr
` (2 preceding siblings ...)
2020-05-04 17:37 ` ericonr
@ 2020-05-04 23:30 ` ericonr
2020-05-04 23:34 ` ericonr
` (3 subsequent siblings)
7 siblings, 0 replies; 9+ messages in thread
From: ericonr @ 2020-05-04 23:30 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 900 bytes --]
There is an updated pull request by ericonr against master on the void-packages repository
https://github.com/ericonr/void-packages contributing
https://github.com/void-linux/void-packages/pull/21609
Run vmdfmt in the markdown files and update some information there
- Had to remove html tags from those files and use markdown anchors instead
- Changed how files in this repo are linked to each other, GH supports using `[contributing](./CONTRIBUTING.md)`.
- Added some information regarding PRs, which I took from #21481 and one of my own PRs as well. This commit can be split from the rest, but it was easier to include it, since I was already messing with the formatting.
I've tested the hyperlinks in the GH interface, and they should be good to go. The main commit for comments should be f272b49.
A patch file from https://github.com/void-linux/void-packages/pull/21609.patch is attached
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-contributing-21609.patch --]
[-- Type: text/x-diff, Size: 89778 bytes --]
From 99c6e7edfd97c121d500d35be25d86c97884350a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Thu, 30 Apr 2020 22:37:58 -0300
Subject: [PATCH 1/6] CONTRIBUTING.md: format with vmdfmt
---
CONTRIBUTING.md | 150 ++++++++++++++++++++++++++++++++----------------
1 file changed, 102 insertions(+), 48 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0490b5f11c2..a55dda679ec 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,65 +1,99 @@
# Contributing to void-packages
-void-packages is the backbone of the Void Linux distribution. It contains all the definitions to build packages from source.
+void-packages is the backbone of the Void Linux distribution. It contains all
+the definitions to build packages from source.
-This document describes how you, as a contributor, can help with adding packages, correcting bugs and adding features to void-packages.
+This document describes how you, as a contributor, can help with adding
+packages, correcting bugs and adding features to void-packages.
## Getting your packages into Void by yourself
-If you really want to get a package into Void Linux, we recommend you package it yourself.
+If you really want to get a package into Void Linux, we recommend you package it
+yourself.
-We provide a [comprehensive Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md)
-on how to create new packages. There's also a
-[manual for xbps-src](https://github.com/void-linux/void-packages/blob/master/README.md), which is used
-to build package files from templates.
+We provide a [comprehensive
+Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md) on
+how to create new packages. There's also a [manual for
+xbps-src](https://github.com/void-linux/void-packages/blob/master/README.md),
+which is used to build package files from templates.
-For this guide, we assume you have basic knowledge about [git](http://git-scm.org), as well as a [GitHub Account](http://github.com).
+For this guide, we assume you have basic knowledge about
+[git](http://git-scm.org), as well as a [GitHub Account](http://github.com).
-Please note that we do not accept any packages containing non-release versions, such as specific git- or svn-revisions anymore.
+Please note that we do not accept any packages containing non-release versions,
+such as specific git- or svn-revisions anymore.
### Creating a new template
-You can use the helper tool `xnew`, from the [xtools](https://github.com/chneukirchen/xtools) package, to create new templates:
+You can use the helper tool `xnew`, from the
+[xtools](https://github.com/chneukirchen/xtools) package, to create new
+templates:
- $ xnew pkgname subpkg1 subpkg2 ...
+```
+$ xnew pkgname subpkg1 subpkg2 ...
+```
-Templates must have the name `void-packages/srcpkgs/<pkgname>/template`, where `pkgname` is the same as the `pkgname` variable in the template.
+Templates must have the name `void-packages/srcpkgs/<pkgname>/template`, where
+`pkgname` is the same as the `pkgname` variable in the template.
-For deeper insights on the contents of template files, please read the [manual](https://github.com/void-linux/void-packages/blob/master/Manual.md), and be sure to browse the existing template files in the `srcpkgs` directory of this repository for concrete examples.
+For deeper insights on the contents of template files, please read the
+[manual](https://github.com/void-linux/void-packages/blob/master/Manual.md), and
+be sure to browse the existing template files in the `srcpkgs` directory of this
+repository for concrete examples.
-When you've finished working on the template file, please check it with `xlint` helper from the [xtools](https://github.com/chneukirchen/xtools) package:
+When you've finished working on the template file, please check it with `xlint`
+helper from the [xtools](https://github.com/chneukirchen/xtools) package:
- $ xlint template
+```
+$ xlint template
+```
If `xlint` reports any issues, resolve them before committing.
### Committing your changes
-Once you have built your template file or files, the commit message should have one of the following forms:
+Once you have built your template file or files, the commit message should have
+one of the following forms:
-* for new packages, use ```New package: <pkgname>-<version>``` ([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)).
+- for new packages, use `New package: <pkgname>-<version>`
+ ([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)).
+- for package updates, use `<pkgname>: update to <version>.`
+ ([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)).
+- for template modifications without a version change, use `<pkgname>: <reason>`
+ ([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)).
-* for package updates, use ```<pkgname>: update to <version>.``` ([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)).
+If you want to describe your changes in more detail, add an empty line followed
+by those details
+([example](https://github.com/void-linux/void-packages/commit/f1c45a502086ba1952f23ace9084a870ce437bc6)).
-* for template modifications without a version change, use ```<pkgname>: <reason>``` ([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)).
+For further information, please consult the
+[manual](https://github.com/void-linux/void-packages/blob/master/Manual.md).
-If you want to describe your changes in more detail, add an empty line followed by those details ([example](https://github.com/void-linux/void-packages/commit/f1c45a502086ba1952f23ace9084a870ce437bc6)).
+`xbump`, available in the [xtools](https://github.com/chneukirchen/xtools)
+package, can be used to commit a new or updated package:
-For further information, please consult the [manual](https://github.com/void-linux/void-packages/blob/master/Manual.md).
+```
+$ xbump <pkgname> <git commit options>
+```
-`xbump`, available in the [xtools](https://github.com/chneukirchen/xtools) package, can be used to commit a new or updated package:
+`xbump` will use `git commit` to commit the changes with the appropriate commit
+message. For more fine-grained control over the commit, specific options can be
+passed to `git commit` by adding them after the package name.
- $ xbump <pkgname> <git commit options>
+After committing your changes, please check that the package builds
+successfully. From the top level directory of your local copy of the
+`void-packages` repository, run:
-`xbump` will use `git commit` to commit the changes with the appropriate commit message. For more fine-grained control over the commit, specific options can be passed to `git commit` by adding them after the package name.
+```
+$ ./xbps-src pkg <pkgname>
+```
-After committing your changes, please check that the package builds successfully. From the top level directory of your local copy of the `void-packages` repository, run:
+Your package must build successfully for at least x86, but we recommend trying
+to build for armv* as well, e.g.:
- $ ./xbps-src pkg <pkgname>
-
-Your package must build successfully for at least x86, but we recommend trying to build for armv* as well, e.g.:
-
- $ ./xbps-src -a armv7l pkg <pkgname>
+```
+$ ./xbps-src -a armv7l pkg <pkgname>
+```
For further details, see the output of `./xbps-src -h`.
@@ -67,40 +101,60 @@ For further details, see the output of `./xbps-src -h`.
Once you have successfully built the package, you can start a pull request.
-Most pull requests should only contain a single package and dependencies which are not part of void-packages yet.
+Most pull requests should only contain a single package and dependencies which
+are not part of void-packages yet.
-If you make updates to packages containing a soname bump you also need to revbump all packages that are dependant. Those
-packages should also be part of the same pull request.
+If you make updates to packages containing a soname bump you also need to
+revbump all packages that are dependant. Those packages should also be part of
+the same pull request.
-When you make changes to your pull request, please *do not close and reopen your pull request*. Instead, just forcibly git push, overwriting any old commits. Closing and opening your pull requests repeatedly spams the Void maintainers.
+When you make changes to your pull request, please *do not close and reopen your
+pull request*. Instead, just forcibly git push, overwriting any old commits.
+Closing and opening your pull requests repeatedly spams the Void maintainers.
#### Travis
-Once you have started a pull request, you will get instant feedback from Travis. It will check if the templates you have changed
-comply with the our guidelines. At the moment not all packages comply with the rules, so if you update a package, it may happen that Travis reports errors about places you haven't touched. Please feel free to fix those errors too.
+Once you have started a pull request, you will get instant feedback from Travis.
+It will check if the templates you have changed comply with the our guidelines.
+At the moment not all packages comply with the rules, so if you update a
+package, it may happen that Travis reports errors about places you haven't
+touched. Please feel free to fix those errors too.
#### Review
-Most of the time your pull request will contain mistakes. It's nothing bad, it just happens.
+Most of the time your pull request will contain mistakes. It's nothing bad, it
+just happens.
-Reviewers will comment on your pull request and point out which changes are needed before the template can be included.
+Reviewers will comment on your pull request and point out which changes are
+needed before the template can be included.
-We recommend having only a single commit for pull request, so if you need to make changes in commits but already have a pull request, use the following commands:
+We recommend having only a single commit for pull request, so if you need to
+make changes in commits but already have a pull request, use the following
+commands:
- $ git add <file>
- $ git commit --amend
- $ git push -f
+```
+$ git add <file>
+$ git commit --amend
+$ git push -f
+```
#### Closing the pull request
-Once you have applied all requested changes, the reviewers will merge your request.
+Once you have applied all requested changes, the reviewers will merge your
+request.
-If the pull request becomes inactive for some days, the reviewers may or may not warn you when they are about to close it.
-If it stays inactive further, it will be closed.
+If the pull request becomes inactive for some days, the reviewers may or may not
+warn you when they are about to close it. If it stays inactive further, it will
+be closed.
-Please abstain from temporarily closing a pull request while revising the templates. Instead, leave a comment on the PR describing what still needs work, or add "[WIP]" to the PR title. Only close your pull request if you're sure you don't want your changes to be included.
+Please abstain from temporarily closing a pull request while revising the
+templates. Instead, leave a comment on the PR describing what still needs work,
+or add "[WIP]" to the PR title. Only close your pull request if you're sure you
+don't want your changes to be included.
#### Publishing the package
-Once the reviewers have merged the pull request, our [build server](http://build.voidlinux.org) is automatically triggered and builds
-all packages in the pull request for all supported platforms. Upon completion, the packages are available to all Void Linux users.
+Once the reviewers have merged the pull request, our [build
+server](http://build.voidlinux.org) is automatically triggered and builds all
+packages in the pull request for all supported platforms. Upon completion, the
+packages are available to all Void Linux users.
From d775a9cd6b1778612192539f40ed623b53b5da82 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Thu, 30 Apr 2020 22:42:29 -0300
Subject: [PATCH 2/6] CONTRIBUTING.md: update commit examples and PR process
- Add a commit example for shlibs modifications
- Explain the PR process a bit better, specially what needs to be
done when the packages involve a soname bump
---
CONTRIBUTING.md | 12 ++++++++----
1 file changed, 8 insertions(+), 4 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a55dda679ec..1a90e742ee0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -59,8 +59,11 @@ one of the following forms:
([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)).
- for package updates, use `<pkgname>: update to <version>.`
([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)).
-- for template modifications without a version change, use `<pkgname>: <reason>`
+- for template modifications without a version change, including removals, use
+ `<pkgname>: <reason>`
([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)).
+- for `common/shlibs` modifications, use `common/shlibs: <pkgname>`
+ ([example](https://github.com/void-linux/void-packages/commit/613651c91811cb4fd2e1a6be701c87072d759a9f)).
If you want to describe your changes in more detail, add an empty line followed
by those details
@@ -104,9 +107,10 @@ Once you have successfully built the package, you can start a pull request.
Most pull requests should only contain a single package and dependencies which
are not part of void-packages yet.
-If you make updates to packages containing a soname bump you also need to
-revbump all packages that are dependant. Those packages should also be part of
-the same pull request.
+If you make updates to packages containing a soname bump, you also need to
+update `common/shlibs` and revbump all packages that are dependant. There should
+be a commit for each package revbump, and those commits should be part of the
+same pull request.
When you make changes to your pull request, please *do not close and reopen your
pull request*. Instead, just forcibly git push, overwriting any old commits.
From 2146bf4785d6efb4249b5cfb62b467ecbdc65b8a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Thu, 30 Apr 2020 23:02:20 -0300
Subject: [PATCH 3/6] Manual.md: use markdown anchors instead of HTML tags
Match some titles in the index to the titles in the document itself.
---
Manual.md | 197 ++++++++++++++++++------------------------------------
1 file changed, 65 insertions(+), 132 deletions(-)
diff --git a/Manual.md b/Manual.md
index 576b3d2032e..b1cf9f9dc20 100644
--- a/Manual.md
+++ b/Manual.md
@@ -5,73 +5,72 @@ packages for XBPS, the `Void Linux` native packaging system.
*Table of Contents*
-* [Introduction](#Introduction)
- * [Quality Requirements](#quality_requirements)
- * [Package build phases](#buildphase)
- * [Package naming conventions](#namingconvention)
- * [Libraries](#libs)
- * [Language Modules](#language_modules)
- * [Language Bindings](#language_bindings)
+* [Introduction](#introduction)
+ * [Quality Requirements](#quality-requirements)
+ * [Package build phases](#package-build-phases)
+ * [Package naming conventions](#package-naming-conventions)
+ * [Libraries](#libraries)
+ * [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)
- * [About the depends variables](#explain_depends)
+ * [Global functions](#global-functions)
+ * [Global variables](#global-variables)
+ * [Available variables](#available-variables)
+ * [Mandatory variables](#mandatory-variables)
+ * [Optional variables](#optional-variables)
+ * [About the many types of `depends` variables](#about-the-many-types-of-depends-variables)
* [Repositories](#repositories)
- * [Repositories defined by Branch](#repo_by_branch)
- * [Package defined repositories](#pkg_defined_repo)
- * [Checking for new upstream releases](#updates)
- * [Handling patches](#patches)
- * [Build style scripts](#build_scripts)
- * [Build helper scripts](#build_helper)
+ * [Repositories defined by Branch](#repositories-defined-by-branch)
+ * [Package defined Repositories](#package-defined-repositories)
+ * [Checking for new upstream releases](#checking-for-new-upstream-releases)
+ * [Handling patches](#handling-patches)
+ * [build\_style scripts](#build_style-scripts)
+ * [build\_helper scripts](#build_helper-scripts)
* [Functions](#functions)
- * [Build options](#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)
- * [Writing runit services](#writing_runit_services)
- * [32bit packages](#32bit_pkgs)
- * [Subpackages](#pkgs_sub)
- * [Development packages](#pkgs_development)
- * [Data packages](#pkgs_data)
- * [Documentation packages](#pkgs_documentation)
- * [Python packages](#pkgs_python)
- * [Go packages](#pkgs_go)
- * [Haskell packages](#pkgs_haskell)
- * [Font packages](#pkgs_font)
- * [Removing a package](#pkg_remove)
- * [XBPS Triggers](#xbps_triggers)
- * [appstream-cache](#triggers_appstream_cache)
- * [binfmts](#triggers_binfmts)
- * [dkms](#triggers_dkms)
- * [gconf-schemas](#triggers_gconf_schemas)
- * [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders)
- * [gio-modules](#triggers_gio_modules)
- * [gettings-schemas](#triggers_gsettings_schemas)
- * [gtk-icon-cache](#triggers_gtk_icon_cache)
- * [gtk-immodules](#triggers_gtk_immodules)
- * [gtk-pixbuf-loaders](#triggers_gtk_pixbuf_loaders)
- * [gtk3-immodules](#triggers_gtk3_immodules)
- * [hwdb.d-dir](#triggers_hwdb.d_dir)
- * [info-files](#triggers_info_files)
- * [kernel-hooks](#triggers_kernel_hooks)
- * [mimedb](#triggers_mimedb)
- * [mkdirs](#triggers_mkdirs)
- * [pango-modules](#triggers_pango_module)
- * [pycompile](#triggers_pycompile)
- * [register-shell](#triggers_register_shell)
- * [system-accounts](#triggers_system_accounts)
- * [update-desktopdb](#triggers_update_desktopdb)
- * [x11-fonts](#triggers_x11_fonts)
- * [xml-catalog](#triggers_xml_catalog)
+ * [Build options](#build-options)
+ * [Runtime dependencies](#runtime-dependencies)
+ * [INSTALL and REMOVE files](#install-and-remove-files)
+ * [INSTALL.msg and REMOVE.msg files](#installmsg-and-removemsg-files)
+ * [Creating system accounts/groups at runtime](#creating-system-accountsgroups-at-runtime)
+ * [Writing runit services](#writing-runit-services)
+ * [32bit packages](#32bit-packages)
+ * [Subpackages](#subpackages)
+ * [Development packages](#development-packages)
+ * [Data packages](#data-packages)
+ * [Documentation packages](#documentation-packages)
+ * [Python packages](#python-packages)
+ * [Go packages](#go-packages)
+ * [Haskell packages](#haskell-packages)
+ * [Font packages](#font-packages)
+ * [Removing a package](#removing-a-package)
+ * [XBPS Triggers](#xbps-triggers)
+ * [appstream-cache](#appstream-cache)
+ * [binfmts](#binfmts)
+ * [dkms](#dkms)
+ * [gconf-schemas](#gconf-schemas)
+ * [gdk-pixbuf-loaders](#gdk-pixbuf-loaders)
+ * [gio-modules](#gio-modules)
+ * [gettings-schemas](#gsettings-schemas)
+ * [gtk-icon-cache](#gtk-icon-cache)
+ * [gtk-immodules](#gtk-immodules)
+ * [gtk-pixbuf-loaders](#gtk-pixbuf-loaders)
+ * [gtk3-immodules](#gtk3-immodules)
+ * [hwdb.d-dir](#hwdbd-dir)
+ * [info-files](#info-files)
+ * [kernel-hooks](#kernel-hooks)
+ * [mimedb](#mimedb)
+ * [mkdirs](#mkdirs)
+ * [pango-modules](#pango-modules)
+ * [pycompile](#pycompile)
+ * [register-shell](#register-shell)
+ * [system-accounts](#system-accounts)
+ * [update-desktopdb](#update-desktopdb)
+ * [x11-fonts](#x11-fonts)
+ * [xml-catalog](#xml-catalog)
* [Notes](#notes)
- * [Contributing via git](#contributing)
+ * [Contributing via git](#contributing-via-git)
* [Help](#help)
-<a id="Introduction"></a>
## Introduction
The `void-packages` repository contains all `source` packages that are the
@@ -117,7 +116,6 @@ If everything went fine after running
a binary package named `foo-1.0_1.<arch>.xbps` will be generated in the local repository
`hostdir/binpkgs`.
-<a id="quality_requirements"></a>
### Quality Requirements
Follow this list to determine if a piece of software or other technology may be
@@ -135,7 +133,6 @@ the Void packages system.
1. Required: Another package either within the repository or pending inclusion
requires the package.
-<a id="buildphase"></a>
### Package build phases
Building a package consist of the following phases:
@@ -169,10 +166,8 @@ via `make install` or any other compatible method.
successfully, the phase will be skipped later (unless its work directory
`${wrksrc}` is removed with `xbps-src clean`).
-<a id="namingconventions"></a>
### Package naming conventions
-<a id="libs"></a>
#### Libraries
Libraries are packages which provide shared objects (\*.so) in /usr/lib.
@@ -196,7 +191,6 @@ a linked program.
against this package. If the library is a sub package, its corresponding
development package should be named `lib<name>-devel`
-<a id="language_modules"></a>
#### Language Modules
Language modules are extensions to script or compiled languages. Those packages
@@ -217,7 +211,6 @@ for the language prefix.
Example: python-pam, perl-URI, python3-pyside2
-<a id="language_bindings"></a>
#### Language Bindings
Language Bindings are packages which allow programs or libraries to have
@@ -230,7 +223,6 @@ The naming convention to those packages is:
Example: gimp-python, irssi-perl
-<a id="programs"></a>
#### Programs
Programs put executables under /usr/bin (or in very special cases in other
@@ -246,7 +238,6 @@ Programs can be split into program packages and library packages. The program
package should be named as described above. The library package should be
prefixed with "lib" (see section `Libraries`)
-<a id="global_funcs"></a>
### Global functions
The following functions are defined by `xbps-src` and can be used on any template:
@@ -305,12 +296,11 @@ The following functions are defined by `xbps-src` and can be used on any templat
`$DESTDIR`. The optional 2nd argument can be used to change the
`file name`.
-- <a id="vlicense"></a>
*vlicense()* `vlicense <file> [<name>]`
Installs `file` into `usr/share/licenses/<pkgname>` in the pkg
`$DESTDIR`. The optional 2nd argument can be used to change the
- `file name`. See [license](#var_license) for when to use it.
+ `file name`. See [license](#mandatory-license) for when to use it.
- *vsv()* `vsv <service>`
@@ -333,7 +323,6 @@ The following functions are defined by `xbps-src` and can be used on any templat
> Shell wildcards must be properly quoted, Example: `vmove "usr/lib/*.a"`.
-<a id="global_vars"></a>
### Global variables
The following variables are defined by `xbps-src` and can be used on any template:
@@ -393,10 +382,8 @@ in this directory such as `${XBPS_BUILDDIR}/${wrksrc}`.
- `XBPS_RUST_TARGET` The target architecture triplet used by `rustc` and `cargo`.
-<a id="available_vars"></a>
### Available variables
-<a id="mandatory_vars"></a>
#### Mandatory variables
The list of mandatory variables for a template:
@@ -404,8 +391,7 @@ The list of mandatory variables for a template:
- `homepage` A string pointing to the `upstream` homepage.
-- <a id="var_license"></a>
-`license` A string matching the license's [SPDX Short identifier](https://spdx.org/licenses),
+- `license` A string matching the license's [SPDX Short identifier](https://spdx.org/licenses),
`Public Domain`, or string prefixed with `custom:` for other licenses.
Multiple licenses should be separated by commas, Example: `GPL-3.0-or-later, custom:Hugware`.
@@ -432,7 +418,6 @@ the generated `binary packages` have been modified.
- `version` A string with the package version. Must not contain dashes or underscore
and at least one digit is required. Shell's variable substition usage is not allowed.
-<a id="optional_vars"></a>
#### Optional variables
- `hostmakedepends` The list of `host` dependencies required to build the package, and
@@ -702,8 +687,7 @@ Examples:
archs=noarch
```
-<a id="explain_depends"></a>
-#### About the many types of `depends` variable.
+#### About the many types of `depends` variables
So far we have listed four types of `depends`, there are `hostmakedepends`,
`makedepends`, `checkdepends` and plain old `depends`.To understand the difference
@@ -734,10 +718,8 @@ Finally, as a general rule, if something compiles the exact same way whether or
not you add a particular package to `makedepends` or `hostmakedepends`, it
shouldn't be added.
-<a id="repositories"></a>
#### Repositories
-<a id="repo_by_branch"></a>
##### Repositories defined by Branch
The global repository takes the name of
@@ -745,7 +727,6 @@ 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
update multiple packages in a second branch without polluting his local repository.
-<a id="pkg_defined_repo"></a>
##### Package defined Repositories
The second way to define a repository is by setting the `repository` variable in
@@ -758,7 +739,6 @@ The following repository names are valid:
* `nonfree`: Repository for closed source packages.
-<a id="updates"></a>
### Checking for new upstream releases
New upstream versions can be automatically checked using
@@ -797,7 +777,6 @@ in url. Defaults to `(|v|$pkgname)[-_.]*`.
part that follows numeric part of version directory
in url. Defaults to `(|\.x)`.
-<a id="patches"></a>
### Handling patches
Sometimes software needs to be patched, most commonly to fix bugs that have
@@ -820,8 +799,7 @@ be used to set the args passed to `patch(1)`. As an example, if `foo.patch` requ
special arguments to be passed to `patch(1)` that can't be used when applying other
patches, `foo.patch.args` can be created containing those args.
-<a id="build_scripts"></a>
-### build style scripts
+### 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
@@ -933,8 +911,7 @@ matching the `build_style` name, Example:
`common/environment/build-style/gnu-configure.sh`
-<a id="build_helper"></a>
-### build helper scripts
+### build\_helper scripts
The `build_helper` variable specifies shell snippets to be sourced that will create a
suitable environment for working with certain sets of packages.
@@ -963,7 +940,6 @@ This aims to fix cross-builds for when the build-style is mixed: e.g. when in a
`gnu-configure` style the configure script calls `qmake` or a `Makefile` in
`gnu-makefile` style, respectively.
-<a id="functions"></a>
### Functions
The following functions can be defined to change the behavior of how the
@@ -1022,7 +998,6 @@ Current working directory for functions is set as follows:
- For pre_configure through post_install: `build_wrksrc`
if it is defined, otherwise `wrksrc`.
-<a id="build_options"></a>
### Build options
Some packages might be built with different build options to enable/disable
@@ -1127,7 +1102,6 @@ Example: `XBPS_PKG_OPTIONS_xorg_server=opt`.
The list of supported package build options and its description is defined in the
`common/options.description` file.
-<a id="deps_runtime"></a>
#### Runtime dependencies
Dependencies for ELF objects are detected automatically by `xbps-src`, hence runtime
@@ -1167,7 +1141,6 @@ 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
when the package is being built with `xbps-src`.
-<a id="install_remove_files"></a>
### INSTALL and REMOVE files
The INSTALL and REMOVE shell snippets can be used to execute certain actions at a specified
@@ -1211,7 +1184,6 @@ be executed via `chroot(2)` won't work correctly.
> NOTE: do not use INSTALL/REMOVE scripts to print messages, see the next section for
more information.
-<a id="install_remove_files_msg"></a>
### INSTALL.msg and REMOVE.msg files
The `INSTALL.msg` and `REMOVE.msg` files can be used to print a message at post-install
@@ -1222,7 +1194,6 @@ 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
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
There's a trigger along with some variables that are specifically to create
@@ -1254,7 +1225,6 @@ accounts.
> NOTE: The underscore policy does not apply to old packages, due to the inevitable breakage of
> changing the username only new packages should follow it.
-<a id="writing_runit_services"></a>
### Writing runit services
Void Linux uses [runit](http://smarden.org/runit/) for booting and supervision of services.
@@ -1293,7 +1263,6 @@ If the service requires directories in parts of the system that are not generall
temporary filesystems. Then use the `make_dirs` variable in the template to create
those directories when the package is installed.
-<a id="32bit_pkgs"></a>
### 32bit packages
32bit packages are built automatically when the builder is x86 (32bit), but
@@ -1315,7 +1284,6 @@ This expects the basename of the target file, Example: `lib32symlinks="foo"`.
- `lib32mode` If unset, only shared/static libraries and pkg-config files will be copied to the
**32bit** package. If set to `full` all files will be copied to the 32bit package, unmodified.
-<a id="pkgs_sub"></a>
### Subpackages
In the example shown above just a binary package is generated, but with some
@@ -1375,7 +1343,6 @@ destdir (`$DESTDIR`) to the `subpackage` destdir (`$PKGDESTDIR`).
Subpackages are processed always in alphabetical order; To force a custom order,
the `subpackages` variable can be declared with the wanted order.
-<a id="pkgs_development"></a>
### Development packages
A development package, commonly generated as a subpackage, shall only contain
@@ -1405,7 +1372,6 @@ following subset of files from the main package:
* Gobject introspection XML files `usr/share/gir-1.0`
* Vala bindings `usr/share/vala`
-<a id="pkgs_data"></a>
### Data packages
Another common subpackage type is the `-data` subpackage. This subpackage
@@ -1417,7 +1383,6 @@ or card material (maps). Data subpackages are almost always `archs=noarch`.
The main package must then have `depends="${pkgname}-data-${version}_${revision}"`,
possibly in addition to other, non-automatic depends.
-<a id="pkgs_documentation"></a>
### Documentation packages
Packages intended for user interaction do not always unconditionally require
@@ -1432,7 +1397,6 @@ building packages depending on a specific package there is no need to install la
amounts of documentation for no reason. Thus the size of the documentation part should
be your guidance to decide whether or not to split off a `-doc` subpackage.
-<a id="pkgs_python"></a>
### Python packages
Python packages should be built with the `python{,2,3}-module` build style, if possible.
@@ -1481,7 +1445,6 @@ Also, a set of useful variables are defined to use in the templates:
> NOTE: it's expected that additional subpkgs must be generated to allow packaging for multiple
python versions.
-<a id="pkgs_go"></a>
### Go packages
Go packages should be built with the `go` build style, if possible.
@@ -1518,7 +1481,6 @@ otherwise preping some assets. If possible do this in pre_build().
The path to the package's source inside `$GOPATH` is available as
`$GOSRCPATH`.
-<a id="pkgs_haskell"></a>
### Haskell packages
We build Haskell package using `stack` from
@@ -1536,7 +1498,6 @@ The following variables influence how Haskell packages are built:
- `make_build_args`: This is passed as-is to `stack build ...`, so
you can add your `--flag ...` parameters there.
-<a id="pkgs_font"></a>
### Font packages
Font packages are very straightforward to write, they are always set with the
@@ -1548,7 +1509,6 @@ cache during the install/removal of the package
- `font_dirs`: which should be set to the directory where the package
installs its fonts
-<a id="pkg_remove"></a>
### Removing a package
Follows a list of things that should be done to help guarantee that a
@@ -1576,7 +1536,6 @@ the source of those patches/files.
- Remove the package from the repository index
or contact a team member that can do so.
-<a id="xbps_triggers"></a>
### XBPS Triggers
XBPS triggers are a collection of snippets of code, provided by the `xbps-triggers`
@@ -1591,7 +1550,6 @@ package.
This is not a complete overview of the package. It is recommended to read the variables
referenced and the triggers themselves.
-<a id="triggers_appstream_cache"></a>
#### appstream-cache
The appstream-cache trigger is responsible for rebuilding the appstream metadata cache.
@@ -1613,7 +1571,6 @@ directory.
It is automatically added to packages that have XML files under one of the directories
searched by appstreamcli.
-<a id="triggers_binfmts"></a>
#### binfmts
The binfmts trigger is responsible for registration and removal of arbitrary
@@ -1625,7 +1582,6 @@ to register/remove entries from the arbitrary executable binary formats database
To include the trigger use the `binfmts` variable, as the trigger won't do anything unless
it is defined.
-<a id="triggers_dkms"></a>
#### dkms
The dkms trigger is responsible for compiling and removing dynamic kernel modules of a
@@ -1638,7 +1594,6 @@ the corresponding module will be removed
To include the trigger use the `dkms_modules` variable, as the trigger won't do anything
unless it is defined.
-<a id="triggers_gconf_schemas"></a>
#### gconf-schemas
The gconf-schemas trigger is responsible for registering and removing .schemas and
@@ -1655,7 +1610,6 @@ It is automatically added to packages that have `/usr/share/gconf/schemas` prese
as a directory. All files with the schemas file extension under that directory
are passed to the trigger.
-<a id="triggers_gdk_pixbuf_loaders"></a>
#### gdk-pixbuf-loaders
The gdk-pixbuf-loaders trigger is responsible for maintaining the GDK Pixbuf loaders cache.
@@ -1669,7 +1623,6 @@ It can be added by defining `gdk-pixbuf-loaders` in the `triggers` variable. It
added automatically to any package that has the path `usr/lib/gdk-pixbuf-2.0/2.10.0/loaders`
available as a directory.
-<a id="triggers_gio_modules"></a>
#### gio-modules
The gio-modules trigger is responsible for updating the Glib GIO module cache with
@@ -1681,7 +1634,6 @@ present under `usr/lib/gio/modules`.
It is automatically added to packages that have `/usr/lib/gio/modules` present
as a directory.
-<a id="triggers_gsettings_schemas"></a>
#### gsettings-schemas
The gsettings-schemas trigger is responsible for compiling Glib's GSettings XML
@@ -1696,7 +1648,6 @@ During removal of the glib package it deletes all files inside
It is automatically added to packages that have `/usr/share/glib-2.0/schemas` present
as a directory.
-<a id="triggers_gtk_icon_cache"></a>
#### gtk-icon-cache
The gtk-icon-cache trigger is responsible for updating the gtk+ icon cache.
@@ -1710,7 +1661,6 @@ It is automatically added on packages that have `/usr/share/icons` available
as a directory, all directories under that directory have their absolute path
passed to the trigger.
-<a id="triggers_gtk_immodules"></a>
#### gtk-immodules
The gtk-immodules trigger is responsible for updating the IM (Input Method) modules
@@ -1726,7 +1676,6 @@ During removal of the `gtk+` package it removes the cache file which is located
It is automatically added to packages that have `/usr/lib/gtk-2.0/2.10.0/immodules`
present as a directory.
-<a id="triggers_gtk_pixbuf_loaders"></a>
#### gtk-pixbuf-loaders
gtk-pixbuf-loaders is the old name for the current `gdk-pixbuf-loaders` trigger and is
@@ -1735,7 +1684,6 @@ compatibility measure.
For information about how it works refer to [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders).
-<a id="triggers_gtk3_immodules"></a>
#### gtk3-immodules
The gtk3-immodules trigger is responsible for updating the IM (Input Method) modules
@@ -1751,7 +1699,6 @@ During removal of the `gtk+3` package it removes the cache file which is located
It is automatically added to packages that have `/usr/lib/gtk-3.0/3.0.0/immodules`
present as a directory.
-<a id="triggers_hwdb.d_dir"></a>
#### hwdb.d-dir
The hwdb.d-dir trigger is responsible for updating the hardware database.
@@ -1761,7 +1708,6 @@ During installation and removal it runs `usr/bin/udevadm hwdb --root=. --update`
It is automatically added to packages that have `/usr/lib/udev/hwdb.d` present
as a directory.
-<a id="triggers_info_files"></a>
#### info-files
The info-files trigger is responsible for registering and unregistering the GNU info
@@ -1779,7 +1725,6 @@ registry located at `usr/share/info`.
If it is running under another architecture it tries to use the host's `install-info`
utility.
-<a id="triggers_kernel_hooks"></a>
#### kernel-hooks
The kernel-hooks trigger is responsible for running scripts during installation/removal
@@ -1797,7 +1742,6 @@ target.
It is automatically added if the helper variable `kernel_hooks_version` is defined.
However it is not obligatory to have it defined.
-<a id="triggers_mimedb"></a>
#### mimedb
The mimedb trigger is responsible for updating the shared-mime-info database.
@@ -1807,7 +1751,6 @@ In all runs it will just execute `update-mime-database -n usr/share/mime`.
It is automatically added to packages that have `/usr/share/mime` available as
a directory.
-<a id="triggers_mkdirs"></a>
#### mkdirs
The mkdirs trigger is responsible for creating and removing directories dictated
@@ -1832,7 +1775,6 @@ During removal it will delete the directory using `rmdir`.
To include this trigger use the `make_dirs` variable, as the trigger won't do anything
unless it is defined.
-<a id="triggers_pango_module"></a>
#### pango-modules
The pango-modules trigger is currently being removed since upstream has removed the
@@ -1846,7 +1788,6 @@ Currently it removes `etc/pango/pango.modules` file during removal of the pango
It can be added by defining `pango-modules` in the `triggers` variable and has no way to get
added automatically to a package.
-<a id="triggers_pycompile"></a>
#### pycompile
The pycompile trigger is responsible for compiling python code into native
@@ -1863,7 +1804,6 @@ trigger won't do anything unless at least one of those variables is defined.
A `python_version` variable can be set to direct behaviour of the trigger.
-<a id="triggers_register_shell"></a>
#### register-shell
The register-shell trigger is responsible for registering and removing shell entries
@@ -1877,7 +1817,6 @@ During removal it will use `sed` to delete the shell from the file.
To include this trigger use the `register_shell` variable, as the trigger won't do
anything unless it is defined.
-<a id="triggers_system_accounts"></a>
#### system-accounts
The system-accounts trigger is responsible for creating and disabling system accounts
@@ -1890,7 +1829,6 @@ Example: `transmission unprivileged user - for uninstalled package transmission`
This trigger can only be used by using the `system_accounts` variable.
-<a id="triggers_update_desktopdb"></a>
#### update-desktopdb
The update-desktopdb trigger is responsible for updating the system's MIME database.
@@ -1904,7 +1842,6 @@ was created during installation.
It is automatically added to packages that have `/usr/share/applications` available as
a directory.
-<a id="triggers_x11_fonts"></a>
#### x11-fonts
The x11-fonts trigger is responsible for rebuilding the fonts.dir and fonts.scale files
@@ -1916,7 +1853,6 @@ all font directories it was given via the `font_dirs` variable.
To include this trigger use the `font_dirs` variable, as the trigger won't do anything
unless it is defined.
-<a id="triggers_xml_catalog"></a>
#### xml-catalog
The xml-catalog trigger is responsible for registering and removing SGML/XML catalog entries.
@@ -1932,7 +1868,6 @@ During removal it uses `xmlcatmgr` to remove all catalogs passed to it by the
To include this trigger use the `sgml_entries` variable or/and the `xml_entries` variable,
as the trigger won't do anything unless either of them are defined.
-<a id="notes"></a>
### Notes
- Make sure that all software is configured to use the `/usr` prefix.
@@ -1951,7 +1886,6 @@ 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;
otherwise the `debug` packages won't have debugging symbols.
-<a id="contributing"></a>
### Contributing via git
Fork the voidlinux `void-packages` git repository on github and clone it:
@@ -1971,7 +1905,6 @@ to pull in new changes:
$ git remote add upstream git://github.com/void-linux/void-packages.git
$ git pull upstream master
-<a id="help"></a>
## Help
If after reading this `manual` you still need some kind of help, please join
From 9669f6f44da125c013774f2672766b54eacf032f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Mon, 4 May 2020 10:55:53 -0300
Subject: [PATCH 4/6] README.md: use markdown anchors instead of HTML flags
---
README.md | 41 ++++++++++++-----------------------------
1 file changed, 12 insertions(+), 29 deletions(-)
diff --git a/README.md b/README.md
index 752fb3d4fdc..47ad8f25252 100644
--- a/README.md
+++ b/README.md
@@ -17,22 +17,22 @@ for details of how to create source packages.
- [Requirements](#requirements)
- [Quick start](#quick-start)
- [chroot methods](#chroot-methods)
-- [Install the bootstrap packages](#install-bootstrap)
+- [Install the bootstrap packages](#install-the-bootstrap-packages)
- [Configuration](#configuration)
- [Directory hierarchy](#directory-hierarchy)
- [Building packages](#building-packages)
-- [Package build options](#build-options)
-- [Sharing and signing your local repositories](#sharing-and-signing)
-- [Rebuilding and overwriting existing local packages](#rebuilding)
-- [Enabling distcc for distributed compilation](#distcc)
+- [Package build options](#package-build-options)
+- [Sharing and signing your local repositories](#sharing-and-signing-your-local-repositories)
+- [Rebuilding and overwriting existing local packages](#rebuilding-and-overwriting-existing-local-packages)
+- [Enabling distcc for distributed compilation](#enabling-distcc-for-distributed-compilation)
- [Distfiles mirrors](#distfiles-mirrors)
-- [Cross compiling packages for a target architecture](#cross-compiling)
-- [Using xbps-src in a foreign Linux distribution](#foreign)
-- [Remaking the masterdir](#remaking-masterdir)
-- [Keeping your masterdir uptodate](#updating-masterdir)
-- [Building 32bit packages on x86_64](#building-32bit)
-- [Building packages natively for the musl C library](#building-for-musl)
-- [Building void base-system from scratch](#building-base-system)
+- [Cross compiling packages for a target architecture](#cross-compiling-packages-for-a-target-architecture)
+- [Using xbps-src in a foreign Linux distribution](#using-xbps-src-in-a-foreign-linux-distribution)
+- [Remaking the masterdir](#remaking-the-masterdir)
+- [Keeping your masterdir uptodate](#keeping-your-masterdir-uptodate)
+- [Building 32bit packages on x86\_64](#building-32bit-packages-on-x86_64)
+- [Building packages natively for the musl C library](#building-packages-natively-for-the-musl-c-library)
+- [Building void base-system from scratch](#building-void-base-system-from-scratch)
### Requirements
@@ -58,7 +58,6 @@ multiple utilities to accomplish this task:
> NOTE: `xbps-src` does not allow building as root anymore. Use one of the chroot
methods shown above.
-<a name="quick-start"></a>
### Quick start
Clone the `void-packages` git repository and install the bootstrap packages:
@@ -95,7 +94,6 @@ Alternatively, packages can be installed with the `xi` utility, from the `xtools
# xi <package_name>
```
-<a name="chroot-methods"></a>
### chroot methods
#### xbps-uunshare(1) (default)
@@ -149,7 +147,6 @@ To enable it:
$ cd void-packages
$ echo XBPS_CHROOT_CMD=proot >> etc/conf
-<a name="install-bootstrap"></a>
### Install the bootstrap packages
The `bootstrap` packages are a set of packages required to build any available source package in a container. There are two methods to install the `bootstrap`:
@@ -185,7 +182,6 @@ used as dependencies in the source packages tree.
If you want to customize those replacements, copy `etc/defaults.virtual` to `etc/virtual`
and edit it accordingly to your needs.
-<a name="directory-hierarchy"></a>
### Directory hierarchy
The following directory hierarchy is used with a default configuration file:
@@ -222,7 +218,6 @@ The description of these directories is as follows:
- `hostdir/sources`: to store package sources.
- `hostdir/binpkgs`: local repository to store generated binary packages.
-<a name="building-packages"></a>
### Building packages
The simplest form of building package is accomplished by running the `pkg` target in `xbps-src`:
@@ -249,7 +244,6 @@ It is possible to avoid using remote repositories completely by using the `-N` f
> The default local repository may contain multiple *sub-repositories*: `debug`, `multilib`, etc.
-<a name="build-options"></a>
### Package build options
The supported build options for a source package can be shown with `xbps-src show-options`:
@@ -289,7 +283,6 @@ i.e `XBPS_PKG_OPTIONS_xorg_server=opt`.
The list of supported package build options and its description is defined in the
`common/options.description` file or in the `template` file.
-<a name="sharing-and-signing"></a>
### Sharing and signing your local repositories
To share a local repository remotely it's mandatory to sign it and the binary packages
@@ -327,7 +320,6 @@ Each time a binary package is created, a package signature must be created with
> It is not possible to sign a repository with multiple RSA keys.
-<a name="rebuilding"></a>
### Rebuilding and overwriting existing local packages
If for whatever reason a package has been built and it is available in your local repository
@@ -343,7 +335,6 @@ Reinstalling this package in your target `rootdir` can be easily done too:
> Please note that the `package expression` must be properly defined to explicitly pick up
the package from the desired repository.
-<a name="distcc"></a>
### Enabling distcc for distributed compilation
Setup the slaves (machines that will compile the code):
@@ -374,7 +365,6 @@ The slave 192.168.2.101 has a CPU with 8 cores and the /9 for the number of jobs
The slave 192.168.2.102 is set to run at most 2 compile jobs to keep its load low, even if its CPU has 4 cores.
The XBPS_MAKEJOBS setting is increased to 16 to account for the possible parallelism (2 + 9 + 2 + some slack).
-<a name="distfiles-mirrors"></a>
### Distfiles mirror(s)
In etc/conf you may optionally define a mirror or a list of mirrors to search for distfiles.
@@ -399,7 +389,6 @@ using the `file://` prefix or simply an absolute path on your build host (e.g. /
Mirror locations specified this way are bind mounted inside the chroot environment
under $XBPS_MASTERDIR and searched for distfiles just the same as remote locations.
-<a name="cross-compiling"></a>
### Cross compiling packages for a target architecture
Currently `xbps-src` can cross build packages for some target architectures with a cross compiler.
@@ -411,7 +400,6 @@ If a source package has been adapted to be **cross buildable** `xbps-src` will a
If the build for whatever reason fails, might be a new build issue or simply because it hasn't been adapted to be **cross compiled**.
-<a name="foreign"></a>
### Using xbps-src in a foreign Linux distribution
xbps-src can be used in any recent Linux distribution matching the CPU architecture.
@@ -439,7 +427,6 @@ and `xbps-src` should be fully functional; just start the `bootstrap` process, i
The default masterdir is created in the current working directory, i.e `void-packages/masterdir`.
-<a name="remaking-masterdir"></a>
### Remaking the masterdir
If for some reason you must update xbps-src and the `bootstrap-update` target is not enough, it's possible to recreate a masterdir with two simple commands (please note that `zap` keeps your `ccache/distcc/host` directories intact):
@@ -447,14 +434,12 @@ If for some reason you must update xbps-src and the `bootstrap-update` target is
$ ./xbps-src zap
$ ./xbps-src binary-bootstrap
-<a name="updating-masterdir"></a>
### Keeping your masterdir uptodate
Sometimes the bootstrap packages must be updated to the latest available version in repositories, this is accomplished with the `bootstrap-update` target:
$ ./xbps-src bootstrap-update
-<a name="building-32bit"></a>
### Building 32bit packages on x86_64
Two ways are available to build 32bit packages on x86\_64:
@@ -471,7 +456,6 @@ The second mode (native) needs a new x86 `masterdir`:
$ ./xbps-src -m masterdir-x86 binary-bootstrap i686
$ ./xbps-src -m masterdir-x86 ...
-<a name="building-for-musl"></a>
### Building packages natively for the musl C library
A native build environment is required to be able to cross compile the bootstrap packages for the musl C library; this is accomplished by installing them via `binary-bootstrap`:
@@ -493,7 +477,6 @@ Your new masterdir is now ready to build packages natively for the musl C librar
To see if the musl C dynamic linker is working as expected.
-<a name="building-base-system"></a>
### Building void base-system from scratch
To rebuild all packages in `base-system` for your native architecture:
From 7e8b14ca5c5f83130a7ffe9323b735251ba2a851 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Mon, 4 May 2020 11:03:29 -0300
Subject: [PATCH 5/6] README.md: format with vmdfmt
---
README.md | 581 +++++++++++++++++++++++++++++++++---------------------
1 file changed, 358 insertions(+), 223 deletions(-)
diff --git a/README.md b/README.md
index 47ad8f25252..afe50b766be 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,18 @@
## The XBPS source packages collection
-This repository contains the XBPS source packages collection to build binary packages
-for the Void Linux distribution.
+This repository contains the XBPS source packages collection to build binary
+packages for the Void Linux distribution.
-The included `xbps-src` script will fetch and compile the sources, and install its
-files into a `fake destdir` to generate XBPS binary packages that can be installed
-or queried through the `xbps-install(1)` and `xbps-query(1)` utilities, respectively.
+The included `xbps-src` script will fetch and compile the sources, and install
+its files into a `fake destdir` to generate XBPS binary packages that can be
+installed or queried through the `xbps-install(1)` and `xbps-query(1)`
+utilities, respectively.
-See [Contributing](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
+See
+[Contributing](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
for a general overview of how to contribute and the
-[Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md)
-for details of how to create source packages.
+[Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md) for
+details of how to create source packages.
### Table of Contents
@@ -22,17 +24,24 @@ for details of how to create source packages.
- [Directory hierarchy](#directory-hierarchy)
- [Building packages](#building-packages)
- [Package build options](#package-build-options)
-- [Sharing and signing your local repositories](#sharing-and-signing-your-local-repositories)
-- [Rebuilding and overwriting existing local packages](#rebuilding-and-overwriting-existing-local-packages)
-- [Enabling distcc for distributed compilation](#enabling-distcc-for-distributed-compilation)
+- [Sharing and signing your local
+ repositories](#sharing-and-signing-your-local-repositories)
+- [Rebuilding and overwriting existing local
+ packages](#rebuilding-and-overwriting-existing-local-packages)
+- [Enabling distcc for distributed
+ compilation](#enabling-distcc-for-distributed-compilation)
- [Distfiles mirrors](#distfiles-mirrors)
-- [Cross compiling packages for a target architecture](#cross-compiling-packages-for-a-target-architecture)
-- [Using xbps-src in a foreign Linux distribution](#using-xbps-src-in-a-foreign-linux-distribution)
+- [Cross compiling packages for a target
+ architecture](#cross-compiling-packages-for-a-target-architecture)
+- [Using xbps-src in a foreign Linux
+ distribution](#using-xbps-src-in-a-foreign-linux-distribution)
- [Remaking the masterdir](#remaking-the-masterdir)
- [Keeping your masterdir uptodate](#keeping-your-masterdir-uptodate)
-- [Building 32bit packages on x86\_64](#building-32bit-packages-on-x86_64)
-- [Building packages natively for the musl C library](#building-packages-natively-for-the-musl-c-library)
-- [Building void base-system from scratch](#building-void-base-system-from-scratch)
+- [Building 32bit packages on x86_64](#building-32bit-packages-on-x86_64)
+- [Building packages natively for the musl C
+ library](#building-packages-natively-for-the-musl-c-library)
+- [Building void base-system from
+ scratch](#building-void-base-system-from-scratch)
### Requirements
@@ -45,18 +54,22 @@ for details of how to create source packages.
- objcopy(1), objdump(1), strip(1): binutils
- other common POSIX utilities included by default in almost all UNIX systems.
-`xbps-src` requires a utility to chroot and bind mount existing directories
-into a `masterdir` that is used as its main `chroot` directory. `xbps-src` supports
+`xbps-src` requires a utility to chroot and bind mount existing directories into
+a `masterdir` that is used as its main `chroot` directory. `xbps-src` supports
multiple utilities to accomplish this task:
- - `bwrap` - bubblewrap, see https://github.com/projectatomic/bubblewrap.
- - `ethereal` - only useful for one-shot containers, i.e docker (used with travis).
- - `xbps-uunshare(1)` - XBPS utility that uses `user_namespaces(7)` (part of xbps, default).
- - `xbps-uchroot(1)` - XBPS utility that uses `namespaces` and must be `setgid` (part of xbps).
- - `proot(1)` - utility that implements chroot/bind mounts in user space, see https://proot-me.github.io/.
+- `bwrap` - bubblewrap, see https://github.com/projectatomic/bubblewrap.
+- `ethereal` - only useful for one-shot containers, i.e docker (used with
+ travis).
+- `xbps-uunshare(1)` - XBPS utility that uses `user_namespaces(7)` (part of
+ xbps, default).
+- `xbps-uchroot(1)` - XBPS utility that uses `namespaces` and must be `setgid`
+ (part of xbps).
+- `proot(1)` - utility that implements chroot/bind mounts in user space, see
+ https://proot-me.github.io/.
-> NOTE: `xbps-src` does not allow building as root anymore. Use one of the chroot
-methods shown above.
+> NOTE: `xbps-src` does not allow building as root anymore. Use one of the
+> chroot methods shown above.
### Quick start
@@ -82,13 +95,16 @@ To build packages marked as 'restricted', modify `etc/conf`:
$ echo XBPS_ALLOW_RESTRICTED=yes >> etc/conf
```
-Once built, the package will be available in `hostdir/binpkgs` or an appropriate subdirectory (e.g. `hostdir/binpkgs/nonfree`). To install the package:
+Once built, the package will be available in `hostdir/binpkgs` or an appropriate
+subdirectory (e.g. `hostdir/binpkgs/nonfree`). To install the package:
```
# xbps-install --repository hostdir/binpkgs <package_name>
```
-Alternatively, packages can be installed with the `xi` utility, from the `xtools` package. `xi` takes the repository of the current working directory into account.
+Alternatively, packages can be installed with the `xi` utility, from the
+`xtools` package. `xi` takes the repository of the current working directory
+into account.
```
# xi <package_name>
@@ -100,380 +116,492 @@ Alternatively, packages can be installed with the `xi` utility, from the `xtools
This utility requires these Linux kernel options:
-- CONFIG\_NAMESPACES
-- CONFIG\_IPC\_NS
-- CONFIG\_UTS\_NS
-- CONFIG\_USER\_NS
+- CONFIG_NAMESPACES
+- CONFIG_IPC_NS
+- CONFIG_UTS_NS
+- CONFIG_USER_NS
-This is the default method, and if your system does not support any of the required kernel
-options it will fail with `EINVAL (Invalid argument)`.
+This is the default method, and if your system does not support any of the
+required kernel options it will fail with `EINVAL (Invalid argument)`.
#### xbps-uchroot(1)
This utility requires these Linux kernel options:
-- CONFIG\_NAMESPACES
-- CONFIG\_IPC\_NS
-- CONFIG\_PID\_NS
-- CONFIG\_UTS\_NS
+- CONFIG_NAMESPACES
+- CONFIG_IPC_NS
+- CONFIG_PID_NS
+- CONFIG_UTS_NS
-Your user must be added to a special group to be able to use `xbps-uchroot(1)` and the
-executable must be `setgid`:
+Your user must be added to a special group to be able to use `xbps-uchroot(1)`
+and the executable must be `setgid`:
- # chown root:<group> xbps-uchroot
- # chmod 4750 xbps-uchroot
- # usermod -a -G <group> <user>
+```
+# chown root:<group> xbps-uchroot
+# chmod 4750 xbps-uchroot
+# usermod -a -G <group> <user>
+```
-> NOTE: by default in void you shouldn't do this manually, your user must be a member of
-the `xbuilder` group.
+> NOTE: by default in void you shouldn't do this manually, your user must be a
+> member of the `xbuilder` group.
To enable it:
- $ cd void-packages
- $ echo XBPS_CHROOT_CMD=uchroot >> etc/conf
+```
+$ cd void-packages
+$ echo XBPS_CHROOT_CMD=uchroot >> etc/conf
+```
-If for some reason it's erroring out as `ERROR clone (Operation not permitted)`, check that
-your user is a member of the required `group` and that `xbps-uchroot(1)` utility has the
-proper permissions and owner/group as explained above.
+If for some reason it's erroring out as `ERROR clone (Operation not permitted)`,
+check that your user is a member of the required `group` and that
+`xbps-uchroot(1)` utility has the proper permissions and owner/group as
+explained above.
#### proot(1)
-The `proot(1)` utility implements chroot and bind mounts support completely in user space,
-and can be used if your Linux kernel does not have support for namespaces. See https://proot-me.github.io/.
-for more information.
+The `proot(1)` utility implements chroot and bind mounts support completely in
+user space, and can be used if your Linux kernel does not have support for
+namespaces. See https://proot-me.github.io/. for more information.
To enable it:
- $ cd void-packages
- $ echo XBPS_CHROOT_CMD=proot >> etc/conf
+```
+$ cd void-packages
+$ echo XBPS_CHROOT_CMD=proot >> etc/conf
+```
### Install the bootstrap packages
-The `bootstrap` packages are a set of packages required to build any available source package in a container. There are two methods to install the `bootstrap`:
-
- - `bootstrap`: all bootstrap packages will be built from scratch; additional utilities are required in the
-host system to allow building the `base-chroot` package: binutils, gcc, perl, texinfo, etc.
+The `bootstrap` packages are a set of packages required to build any available
+source package in a container. There are two methods to install the `bootstrap`:
- - `binary-bootstrap`: the bootstrap binary packages are downloaded via XBPS repositories.
+- `bootstrap`: all bootstrap packages will be built from scratch; additional
+ utilities are required in the host system to allow building the `base-chroot`
+ package: binutils, gcc, perl, texinfo, etc.
+- `binary-bootstrap`: the bootstrap binary packages are downloaded via XBPS
+ repositories.
-If you don't want to waste your time building everything from scratch probably it's better to use `binary-bootstrap`.
+If you don't want to waste your time building everything from scratch probably
+it's better to use `binary-bootstrap`.
### Configuration
-The `etc/defaults.conf` file contains the possible settings that can be overridden
-through the `etc/conf` configuration file for the `xbps-src` utility; if that file
-does not exist, will try to read configuration settings from `~/.xbps-src.conf`.
+The `etc/defaults.conf` file contains the possible settings that can be
+overridden through the `etc/conf` configuration file for the `xbps-src` utility;
+if that file does not exist, will try to read configuration settings from
+`~/.xbps-src.conf`.
-If you want to customize default `CFLAGS`, `CXXFLAGS` and `LDFLAGS`, don't override
-those defined in `etc/defaults.conf`, set them on `etc/conf` instead i.e:
+If you want to customize default `CFLAGS`, `CXXFLAGS` and `LDFLAGS`, don't
+override those defined in `etc/defaults.conf`, set them on `etc/conf` instead
+i.e:
- $ echo 'XBPS_CFLAGS="your flags here"' >> etc/conf
- $ echo 'XBPS_LDFLAGS="your flags here"' >> etc/conf
+```
+$ echo 'XBPS_CFLAGS="your flags here"' >> etc/conf
+$ echo 'XBPS_LDFLAGS="your flags here"' >> etc/conf
+```
-Native and cross compiler/linker flags are set per architecture in `common/build-profiles`
-and `common/cross-profiles` respectively. Ideally those settings are good enough by default,
-and there's no need to set your own unless you know what you are doing.
+Native and cross compiler/linker flags are set per architecture in
+`common/build-profiles` and `common/cross-profiles` respectively. Ideally those
+settings are good enough by default, and there's no need to set your own unless
+you know what you are doing.
#### Virtual packages
-The `etc/defaults.virtual` file contains the default replacements for virtual packages,
-used as dependencies in the source packages tree.
+The `etc/defaults.virtual` file contains the default replacements for virtual
+packages, used as dependencies in the source packages tree.
-If you want to customize those replacements, copy `etc/defaults.virtual` to `etc/virtual`
-and edit it accordingly to your needs.
+If you want to customize those replacements, copy `etc/defaults.virtual` to
+`etc/virtual` and edit it accordingly to your needs.
### Directory hierarchy
The following directory hierarchy is used with a default configuration file:
- /void-packages
- |- common
- |- etc
- |- srcpkgs
- | |- xbps
- | |- template
- |
- |- hostdir
- | |- binpkgs ...
- | |- ccache ...
- | |- distcc-<arch> ...
- | |- repocache ...
- | |- sources ...
- |
- |- masterdir
- | |- builddir -> ...
- | |- destdir -> ...
- | |- host -> bind mounted from <hostdir>
- | |- void-packages -> bind mounted from <void-packages>
-
+```
+ /void-packages
+ |- common
+ |- etc
+ |- srcpkgs
+ | |- xbps
+ | |- template
+ |
+ |- hostdir
+ | |- binpkgs ...
+ | |- ccache ...
+ | |- distcc-<arch> ...
+ | |- repocache ...
+ | |- sources ...
+ |
+ |- masterdir
+ | |- builddir -> ...
+ | |- destdir -> ...
+ | |- host -> bind mounted from <hostdir>
+ | |- void-packages -> bind mounted from <void-packages>
+```
The description of these directories is as follows:
- - `masterdir`: master directory to be used as rootfs to build/install packages.
- - `builddir`: to unpack package source tarballs and where packages are built.
- - `destdir`: to install packages, aka **fake destdir**.
- - `hostdir/ccache`: to store ccache data if the `XBPS_CCACHE` option is enabled.
- - `hostdir/distcc-<arch>`: to store distcc data if the `XBPS_DISTCC` option is enabled.
- - `hostdir/repocache`: to store binary packages from remote repositories.
- - `hostdir/sources`: to store package sources.
- - `hostdir/binpkgs`: local repository to store generated binary packages.
+- `masterdir`: master directory to be used as rootfs to build/install packages.
+- `builddir`: to unpack package source tarballs and where packages are built.
+- `destdir`: to install packages, aka **fake destdir**.
+- `hostdir/ccache`: to store ccache data if the `XBPS_CCACHE` option is enabled.
+- `hostdir/distcc-<arch>`: to store distcc data if the `XBPS_DISTCC` option is
+ enabled.
+- `hostdir/repocache`: to store binary packages from remote repositories.
+- `hostdir/sources`: to store package sources.
+- `hostdir/binpkgs`: local repository to store generated binary packages.
### Building packages
-The simplest form of building package is accomplished by running the `pkg` target in `xbps-src`:
+The simplest form of building package is accomplished by running the `pkg`
+target in `xbps-src`:
```
$ cd void-packages
$ ./xbps-src pkg <pkgname>
```
-When the package and its required dependencies are built, the binary packages will be created
-and registered in the default local repository at `hostdir/binpkgs`; the path to this local repository can be added to
-any xbps configuration file (see xbps.d(5)) or by explicitly appending them via cmdline, i.e:
+When the package and its required dependencies are built, the binary packages
+will be created and registered in the default local repository at
+`hostdir/binpkgs`; the path to this local repository can be added to any xbps
+configuration file (see xbps.d(5)) or by explicitly appending them via cmdline,
+i.e:
- $ xbps-install --repository=hostdir/binpkgs ...
- $ xbps-query --repository=hostdir/binpkgs ...
+```
+$ xbps-install --repository=hostdir/binpkgs ...
+$ xbps-query --repository=hostdir/binpkgs ...
+```
By default **xbps-src** will try to resolve package dependencies in this order:
- - If a dependency exists in the local repository, use it (`hostdir/binpkgs`).
- - If a dependency exists in a remote repository, use it.
- - If a dependency exists in a source package, use it.
+- If a dependency exists in the local repository, use it (`hostdir/binpkgs`).
+- If a dependency exists in a remote repository, use it.
+- If a dependency exists in a source package, use it.
-It is possible to avoid using remote repositories completely by using the `-N` flag.
+It is possible to avoid using remote repositories completely by using the `-N`
+flag.
-> The default local repository may contain multiple *sub-repositories*: `debug`, `multilib`, etc.
+> The default local repository may contain multiple *sub-repositories*: `debug`,
+> `multilib`, etc.
### Package build options
-The supported build options for a source package can be shown with `xbps-src show-options`:
+The supported build options for a source package can be shown with `xbps-src
+show-options`:
- $ ./xbps-src show-options foo
+```
+$ ./xbps-src show-options foo
+```
Build options can be enabled with the `-o` flag of `xbps-src`:
- $ ./xbps-src -o option,option1 pkg foo
+```
+$ ./xbps-src -o option,option1 pkg foo
+```
Build options can be disabled by prefixing them with `~`:
- $ ./xbps-src -o ~option,~option1 pkg foo
+```
+$ ./xbps-src -o ~option,~option1 pkg foo
+```
-Both ways can be used together to enable and/or disable multiple options
-at the same time with `xbps-src`:
+Both ways can be used together to enable and/or disable multiple options at the
+same time with `xbps-src`:
- $ ./xbps-src -o option,~option1,~option2 pkg foo
+```
+$ ./xbps-src -o option,~option1,~option2 pkg foo
+```
The build options can also be shown for binary packages via `xbps-query(1)`:
- $ xbps-query -R --property=build-options foo
+```
+$ xbps-query -R --property=build-options foo
+```
-> NOTE: if you build a package with a custom option, and that package is available
-in an official void repository, an update will ignore those options. Put that package
-on `hold` mode via `xbps-pkgdb(1)`, i.e `xbps-pkgdb -m hold foo` to ignore updates
-with `xbps-install -u`. Once the package is on `hold`, the only way to update it
-is by declaring it explicitly: `xbps-install -u foo`.
+> NOTE: if you build a package with a custom option, and that package is
+> available in an official void repository, an update will ignore those options.
+> Put that package on `hold` mode via `xbps-pkgdb(1)`, i.e `xbps-pkgdb -m hold
+> foo` to ignore updates with `xbps-install -u`. Once the package is on `hold`,
+> the only way to update it is by declaring it explicitly: `xbps-install -u
+> foo`.
-Permanent global package build options can be set via `XBPS_PKG_OPTIONS` variable in the
-`etc/conf` configuration file. Per package build options can be set via
-`XBPS_PKG_OPTIONS_<pkgname>`.
+Permanent global package build options can be set via `XBPS_PKG_OPTIONS`
+variable in the `etc/conf` configuration file. Per package build options can be
+set via `XBPS_PKG_OPTIONS_<pkgname>`.
-> NOTE: if `pkgname` contains `dashes`, those should be replaced by `underscores`
-i.e `XBPS_PKG_OPTIONS_xorg_server=opt`.
+> NOTE: if `pkgname` contains `dashes`, those should be replaced by
+> `underscores` i.e `XBPS_PKG_OPTIONS_xorg_server=opt`.
-The list of supported package build options and its description is defined in the
-`common/options.description` file or in the `template` file.
+The list of supported package build options and its description is defined in
+the `common/options.description` file or in the `template` file.
### Sharing and signing your local repositories
-To share a local repository remotely it's mandatory to sign it and the binary packages
-stored on it. This is accomplished with the `xbps-rindex(1)` utility.
+To share a local repository remotely it's mandatory to sign it and the binary
+packages stored on it. This is accomplished with the `xbps-rindex(1)` utility.
First a RSA key must be created with `openssl(1)` or `ssh-keygen(1)`:
- $ openssl genrsa -des3 -out privkey.pem 4096
+```
+$ openssl genrsa -des3 -out privkey.pem 4096
+```
or
- $ ssh-keygen -t rsa -b 4096 -m PEM -f privkey.pem
+```
+$ ssh-keygen -t rsa -b 4096 -m PEM -f privkey.pem
+```
> Only RSA keys in PEM format are currently accepted by xbps.
-Once the RSA private key is ready you can use it to initialize the repository metadata:
+Once the RSA private key is ready you can use it to initialize the repository
+metadata:
- $ xbps-rindex --sign --signedby "I'm Groot" --privkey privkey.pem $PWD/hostdir/binpkgs
+```
+$ xbps-rindex --sign --signedby "I'm Groot" --privkey privkey.pem $PWD/hostdir/binpkgs
+```
And then make a signature per package:
- $ xbps-rindex --sign-pkg --privkey privkey.pem $PWD/hostdir/binpkgs/*.xbps
+```
+$ xbps-rindex --sign-pkg --privkey privkey.pem $PWD/hostdir/binpkgs/*.xbps
+```
> If --privkey is unset, it defaults to `~/.ssh/id_rsa`.
-If the RSA key was protected with a passphrase you'll have to type it, or alternatively set
-it via the `XBPS_PASSPHRASE` environment variable.
+If the RSA key was protected with a passphrase you'll have to type it, or
+alternatively set it via the `XBPS_PASSPHRASE` environment variable.
-Once the binary packages have been signed, check the repository contains the appropriate `hex fingerprint`:
+Once the binary packages have been signed, check the repository contains the
+appropriate `hex fingerprint`:
- $ xbps-query --repository=hostdir/binpkgs -vL
- ...
+```
+$ xbps-query --repository=hostdir/binpkgs -vL
+...
+```
-Each time a binary package is created, a package signature must be created with `--sign-pkg`.
+Each time a binary package is created, a package signature must be created with
+`--sign-pkg`.
> It is not possible to sign a repository with multiple RSA keys.
### Rebuilding and overwriting existing local packages
-If for whatever reason a package has been built and it is available in your local repository
-and you have to rebuild it without bumping its `version` or `revision` fields, it is possible
-to accomplish this task easily with `xbps-src`:
+If for whatever reason a package has been built and it is available in your
+local repository and you have to rebuild it without bumping its `version` or
+`revision` fields, it is possible to accomplish this task easily with
+`xbps-src`:
- $ ./xbps-src -f pkg xbps
+```
+$ ./xbps-src -f pkg xbps
+```
Reinstalling this package in your target `rootdir` can be easily done too:
- $ xbps-install --repository=/path/to/local/repo -yff xbps-0.25_1
+```
+$ xbps-install --repository=/path/to/local/repo -yff xbps-0.25_1
+```
-> Please note that the `package expression` must be properly defined to explicitly pick up
-the package from the desired repository.
+> Please note that the `package expression` must be properly defined to
+> explicitly pick up the package from the desired repository.
### Enabling distcc for distributed compilation
Setup the slaves (machines that will compile the code):
- # xbps-install -Sy distcc
+```
+# xbps-install -Sy distcc
+```
-Modify the configuration to allow your local network machines to use distcc (e.g. `192.168.2.0/24`):
+Modify the configuration to allow your local network machines to use distcc
+(e.g. `192.168.2.0/24`):
- # echo "192.168.2.0/24" >> /etc/distcc/clients.allow
+```
+# echo "192.168.2.0/24" >> /etc/distcc/clients.allow
+```
Enable and start the `distccd` service:
- # ln -s /etc/sv/distccd /var/service
+```
+# ln -s /etc/sv/distccd /var/service
+```
-Install distcc on the host (machine that executes xbps-src) as well.
-Unless you want to use the host as slave from other machines, there is no need
-to modify the configuration.
+Install distcc on the host (machine that executes xbps-src) as well. Unless you
+want to use the host as slave from other machines, there is no need to modify
+the configuration.
On the host you can now enable distcc in the `void-packages/etc/conf` file:
- XBPS_DISTCC=yes
- XBPS_DISTCC_HOSTS="localhost/2 --localslots_cpp=24 192.168.2.101/9 192.168.2.102/2"
- XBPS_MAKEJOBS=16
+```
+XBPS_DISTCC=yes
+XBPS_DISTCC_HOSTS="localhost/2 --localslots_cpp=24 192.168.2.101/9 192.168.2.102/2"
+XBPS_MAKEJOBS=16
+```
-The example values assume a localhost CPU with 4 cores of which at most 2 are used for compiler jobs.
-The number of slots for preprocessor jobs is set to 24 in order to have enough preprocessed data for other CPUs to compile.
-The slave 192.168.2.101 has a CPU with 8 cores and the /9 for the number of jobs is a saturating choice.
-The slave 192.168.2.102 is set to run at most 2 compile jobs to keep its load low, even if its CPU has 4 cores.
-The XBPS_MAKEJOBS setting is increased to 16 to account for the possible parallelism (2 + 9 + 2 + some slack).
+The example values assume a localhost CPU with 4 cores of which at most 2 are
+used for compiler jobs. The number of slots for preprocessor jobs is set to 24
+in order to have enough preprocessed data for other CPUs to compile. The slave
+192.168.2.101 has a CPU with 8 cores and the /9 for the number of jobs is a
+saturating choice. The slave 192.168.2.102 is set to run at most 2 compile jobs
+to keep its load low, even if its CPU has 4 cores. The XBPS_MAKEJOBS setting is
+increased to 16 to account for the possible parallelism (2 + 9 + 2 + some
+slack).
### Distfiles mirror(s)
-In etc/conf you may optionally define a mirror or a list of mirrors to search for distfiles.
+In etc/conf you may optionally define a mirror or a list of mirrors to search
+for distfiles.
- $ echo 'XBPS_DISTFILES_MIRROR="ftp://192.168.100.5/gentoo/distfiles"' >> etc/conf
+```
+$ echo 'XBPS_DISTFILES_MIRROR="ftp://192.168.100.5/gentoo/distfiles"' >> etc/conf
+```
-If more than one mirror is to be searched, you can either specify multiple URLs separated
-with blanks, or add to the variable like this
+If more than one mirror is to be searched, you can either specify multiple URLs
+separated with blanks, or add to the variable like this
- $ echo 'XBPS_DISTFILES_MIRROR+=" http://repo.voidlinux.de/distfiles"' >> etc/conf
+```
+$ echo 'XBPS_DISTFILES_MIRROR+=" http://repo.voidlinux.de/distfiles"' >> etc/conf
+```
Make sure to put the blank after the first double quote in this case.
The mirrors are searched in order for the distfiles to build a package until the
checksum of the downloaded file matches the one specified in the template.
-Ultimately, if no mirror carries the distfile, or in case all downloads failed the
-checksum verification, the original download location is used.
+Ultimately, if no mirror carries the distfile, or in case all downloads failed
+the checksum verification, the original download location is used.
-If you use `proot` or `uchroot` for your XBPS_CHROOT_CMD, you may also specify a local path
-using the `file://` prefix or simply an absolute path on your build host (e.g. /mnt/distfiles).
-Mirror locations specified this way are bind mounted inside the chroot environment
-under $XBPS_MASTERDIR and searched for distfiles just the same as remote locations.
+If you use `proot` or `uchroot` for your XBPS_CHROOT_CMD, you may also specify a
+local path using the `file://` prefix or simply an absolute path on your build
+host (e.g. /mnt/distfiles). Mirror locations specified this way are bind mounted
+inside the chroot environment under $XBPS_MASTERDIR and searched for distfiles
+just the same as remote locations.
### Cross compiling packages for a target architecture
-Currently `xbps-src` can cross build packages for some target architectures with a cross compiler.
-The supported target is shown with `./xbps-src -h`.
+Currently `xbps-src` can cross build packages for some target architectures with
+a cross compiler. The supported target is shown with `./xbps-src -h`.
-If a source package has been adapted to be **cross buildable** `xbps-src` will automatically build the binary package(s) with a simple command:
+If a source package has been adapted to be **cross buildable** `xbps-src` will
+automatically build the binary package(s) with a simple command:
- $ ./xbps-src -a <target> pkg <pkgname>
+```
+$ ./xbps-src -a <target> pkg <pkgname>
+```
-If the build for whatever reason fails, might be a new build issue or simply because it hasn't been adapted to be **cross compiled**.
+If the build for whatever reason fails, might be a new build issue or simply
+because it hasn't been adapted to be **cross compiled**.
### Using xbps-src in a foreign Linux distribution
-xbps-src can be used in any recent Linux distribution matching the CPU architecture.
+xbps-src can be used in any recent Linux distribution matching the CPU
+architecture.
-To use xbps-src in your Linux distribution use the following instructions. Let's start downloading the xbps static binaries:
+To use xbps-src in your Linux distribution use the following instructions. Let's
+start downloading the xbps static binaries:
- $ wget http://alpha.de.repo.voidlinux.org/static/xbps-static-latest.<arch>-musl.tar.xz
- $ mkdir ~/XBPS
- $ tar xvf xbps-static-latest.<arch>.tar.xz -C ~/XBPS
- $ export PATH=~/XBPS/usr/bin:$PATH
+```
+$ wget http://alpha.de.repo.voidlinux.org/static/xbps-static-latest.<arch>-musl.tar.xz
+$ mkdir ~/XBPS
+$ tar xvf xbps-static-latest.<arch>.tar.xz -C ~/XBPS
+$ export PATH=~/XBPS/usr/bin:$PATH
+```
-If your system does not support `user namespaces`, a privileged group is required to be able to use
-`xbps-uchroot(1)` with xbps-src, by default it's set to the `xbuilder` group, change this to your desired group:
+If your system does not support `user namespaces`, a privileged group is
+required to be able to use `xbps-uchroot(1)` with xbps-src, by default it's set
+to the `xbuilder` group, change this to your desired group:
- # chown root:<group> ~/XBPS/usr/bin/xbps-uchroot.static
- # chmod 4750 ~/XBPS/usr/bin/xbps-uchroot.static
+```
+# chown root:<group> ~/XBPS/usr/bin/xbps-uchroot.static
+# chmod 4750 ~/XBPS/usr/bin/xbps-uchroot.static
+```
Clone the `void-packages` git repository:
- $ git clone git://github.com/void-linux/void-packages
+```
+$ git clone git://github.com/void-linux/void-packages
+```
-and `xbps-src` should be fully functional; just start the `bootstrap` process, i.e:
+and `xbps-src` should be fully functional; just start the `bootstrap` process,
+i.e:
- $ ./xbps-src binary-bootstrap
+```
+$ ./xbps-src binary-bootstrap
+```
-The default masterdir is created in the current working directory, i.e `void-packages/masterdir`.
+The default masterdir is created in the current working directory, i.e
+`void-packages/masterdir`.
### Remaking the masterdir
-If for some reason you must update xbps-src and the `bootstrap-update` target is not enough, it's possible to recreate a masterdir with two simple commands (please note that `zap` keeps your `ccache/distcc/host` directories intact):
+If for some reason you must update xbps-src and the `bootstrap-update` target is
+not enough, it's possible to recreate a masterdir with two simple commands
+(please note that `zap` keeps your `ccache/distcc/host` directories intact):
- $ ./xbps-src zap
- $ ./xbps-src binary-bootstrap
+```
+$ ./xbps-src zap
+$ ./xbps-src binary-bootstrap
+```
### Keeping your masterdir uptodate
-Sometimes the bootstrap packages must be updated to the latest available version in repositories, this is accomplished with the `bootstrap-update` target:
+Sometimes the bootstrap packages must be updated to the latest available version
+in repositories, this is accomplished with the `bootstrap-update` target:
- $ ./xbps-src bootstrap-update
+```
+$ ./xbps-src bootstrap-update
+```
### Building 32bit packages on x86_64
-Two ways are available to build 32bit packages on x86\_64:
+Two ways are available to build 32bit packages on x86_64:
- - cross compilation mode
- - native mode with a 32bit masterdir
+- cross compilation mode
+- native mode with a 32bit masterdir
The first mode (cross compilation) is as easy as:
- $ ./xbps-src -a i686 pkg ...
+```
+$ ./xbps-src -a i686 pkg ...
+```
The second mode (native) needs a new x86 `masterdir`:
- $ ./xbps-src -m masterdir-x86 binary-bootstrap i686
- $ ./xbps-src -m masterdir-x86 ...
+```
+$ ./xbps-src -m masterdir-x86 binary-bootstrap i686
+$ ./xbps-src -m masterdir-x86 ...
+```
### Building packages natively for the musl C library
-A native build environment is required to be able to cross compile the bootstrap packages for the musl C library; this is accomplished by installing them via `binary-bootstrap`:
+A native build environment is required to be able to cross compile the bootstrap
+packages for the musl C library; this is accomplished by installing them via
+`binary-bootstrap`:
- $ ./xbps-src binary-bootstrap
+```
+$ ./xbps-src binary-bootstrap
+```
Now cross compile `base-chroot-musl` for your native architecture:
- $ ./xbps-src -a x86_64-musl pkg base-chroot-musl
+```
+$ ./xbps-src -a x86_64-musl pkg base-chroot-musl
+```
-Wait until all packages are built and when ready, prepare a new masterdir with the musl packages:
+Wait until all packages are built and when ready, prepare a new masterdir with
+the musl packages:
- $ ./xbps-src -m masterdir-x86_64-musl binary-bootstrap x86_64-musl
+```
+$ ./xbps-src -m masterdir-x86_64-musl binary-bootstrap x86_64-musl
+```
-Your new masterdir is now ready to build packages natively for the musl C library. Try:
+Your new masterdir is now ready to build packages natively for the musl C
+library. Try:
- $ ./xbps-src -m masterdir-x86_64-musl chroot
- $ ldd
+```
+$ ./xbps-src -m masterdir-x86_64-musl chroot
+$ ldd
+```
To see if the musl C dynamic linker is working as expected.
@@ -481,14 +609,21 @@ To see if the musl C dynamic linker is working as expected.
To rebuild all packages in `base-system` for your native architecture:
- $ ./xbps-src -N pkg base-system
+```
+$ ./xbps-src -N pkg base-system
+```
It's also possible to cross compile everything from scratch:
- $ ./xbps-src -a <target> -N pkg base-system
+```
+$ ./xbps-src -a <target> -N pkg base-system
+```
-Once the build has finished, you can specify the path to the local repository to `void-mklive`, i.e:
+Once the build has finished, you can specify the path to the local repository to
+`void-mklive`, i.e:
- # cd void-mklive
- # make
- # ./mklive.sh ... -r /path/to/hostdir/binpkgs
+```
+# cd void-mklive
+# make
+# ./mklive.sh ... -r /path/to/hostdir/binpkgs
+```
From 6856243fa5b65e158092f209660e1238cae9b1e0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Mon, 4 May 2020 11:07:11 -0300
Subject: [PATCH 6/6] README, CONTRIBUTING, Manual: use file names instead of
links for files inside the repo
---
CONTRIBUTING.md | 16 ++++++----------
Manual.md | 2 +-
README.md | 8 +++-----
3 files changed, 10 insertions(+), 16 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1a90e742ee0..c3240cd591c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -11,11 +11,9 @@ packages, correcting bugs and adding features to void-packages.
If you really want to get a package into Void Linux, we recommend you package it
yourself.
-We provide a [comprehensive
-Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md) on
-how to create new packages. There's also a [manual for
-xbps-src](https://github.com/void-linux/void-packages/blob/master/README.md),
-which is used to build package files from templates.
+We provide a [comprehensive Manual](./Manual.md) on how to create new packages.
+There's also a [manual for xbps-src](./README.md), which is used to build
+package files from templates.
For this guide, we assume you have basic knowledge about
[git](http://git-scm.org), as well as a [GitHub Account](http://github.com).
@@ -37,9 +35,8 @@ Templates must have the name `void-packages/srcpkgs/<pkgname>/template`, where
`pkgname` is the same as the `pkgname` variable in the template.
For deeper insights on the contents of template files, please read the
-[manual](https://github.com/void-linux/void-packages/blob/master/Manual.md), and
-be sure to browse the existing template files in the `srcpkgs` directory of this
-repository for concrete examples.
+[manual](./Manual.md), and be sure to browse the existing template files in the
+`srcpkgs` directory of this repository for concrete examples.
When you've finished working on the template file, please check it with `xlint`
helper from the [xtools](https://github.com/chneukirchen/xtools) package:
@@ -69,8 +66,7 @@ If you want to describe your changes in more detail, add an empty line followed
by those details
([example](https://github.com/void-linux/void-packages/commit/f1c45a502086ba1952f23ace9084a870ce437bc6)).
-For further information, please consult the
-[manual](https://github.com/void-linux/void-packages/blob/master/Manual.md).
+For further information, please consult the [manual](./Manual.md).
`xbump`, available in the [xtools](https://github.com/chneukirchen/xtools)
package, can be used to commit a new or updated package:
diff --git a/Manual.md b/Manual.md
index b1cf9f9dc20..f1c82b66bdc 100644
--- a/Manual.md
+++ b/Manual.md
@@ -1892,7 +1892,7 @@ Fork the voidlinux `void-packages` git repository on github and clone it:
$ git clone git@github.com:<user>/void-packages.git
-See [CONTRIBUTING.md](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
+See [CONTRIBUTING.md](./CONTRIBUTING.md)
for information on how to format your commits and other tips for
contributing.
diff --git a/README.md b/README.md
index afe50b766be..13c677062c2 100644
--- a/README.md
+++ b/README.md
@@ -8,11 +8,9 @@ its files into a `fake destdir` to generate XBPS binary packages that can be
installed or queried through the `xbps-install(1)` and `xbps-query(1)`
utilities, respectively.
-See
-[Contributing](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
-for a general overview of how to contribute and the
-[Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md) for
-details of how to create source packages.
+See [Contributing](./CONTRIBUTING.md) for a general overview of how to
+contribute and the [Manual](./Manual.md) for details of how to create source
+packages.
### Table of Contents
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Run vmdfmt in the markdown files and update some information there
2020-05-04 14:20 [PR PATCH] Run vmdfmt in the markdown files and update some information there ericonr
` (3 preceding siblings ...)
2020-05-04 23:30 ` [PR PATCH] [Updated] " ericonr
@ 2020-05-04 23:34 ` ericonr
2020-05-05 0:09 ` [PR PATCH] [Updated] " ericonr
` (2 subsequent siblings)
7 siblings, 0 replies; 9+ messages in thread
From: ericonr @ 2020-05-04 23:34 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 335 bytes --]
New comment by ericonr on void-packages repository
https://github.com/void-linux/void-packages/pull/21609#issuecomment-623762823
Comment:
@Duncaen and @Chocimier , I updated it. Now it's only some formatting stuff (using anchors instead of html tags, and local files instead of GH links, when possible) plus changes to CONTRIBUTING.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PR PATCH] [Updated] Run vmdfmt in the markdown files and update some information there
2020-05-04 14:20 [PR PATCH] Run vmdfmt in the markdown files and update some information there ericonr
` (4 preceding siblings ...)
2020-05-04 23:34 ` ericonr
@ 2020-05-05 0:09 ` ericonr
2020-05-05 0:11 ` ericonr
2020-07-08 19:43 ` [PR PATCH] [Closed]: Use markdown anchors " ericonr
7 siblings, 0 replies; 9+ messages in thread
From: ericonr @ 2020-05-05 0:09 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 900 bytes --]
There is an updated pull request by ericonr against master on the void-packages repository
https://github.com/ericonr/void-packages contributing
https://github.com/void-linux/void-packages/pull/21609
Run vmdfmt in the markdown files and update some information there
- Had to remove html tags from those files and use markdown anchors instead
- Changed how files in this repo are linked to each other, GH supports using `[contributing](./CONTRIBUTING.md)`.
- Added some information regarding PRs, which I took from #21481 and one of my own PRs as well. This commit can be split from the rest, but it was easier to include it, since I was already messing with the formatting.
I've tested the hyperlinks in the GH interface, and they should be good to go. The main commit for comments should be f272b49.
A patch file from https://github.com/void-linux/void-packages/pull/21609.patch is attached
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-contributing-21609.patch --]
[-- Type: text/x-diff, Size: 42325 bytes --]
From cee18a79d54d9caeef1cbc9ec15b487454c8ab75 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Mon, 4 May 2020 20:21:45 -0300
Subject: [PATCH 1/4] CONTRIBUTING.md: add commit examples and expl. to PR
process
- Add commit examples for package removal and shlibs modifications
- Explain the PR process, specially when related to soname bumps
---
CONTRIBUTING.md | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0490b5f11c2..23b3fe68bff 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -43,6 +43,10 @@ Once you have built your template file or files, the commit message should have
* for template modifications without a version change, use ```<pkgname>: <reason>``` ([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)).
+* for package removals, use ```<pkgname>: remove package``` ([example](https://github.com/void-linux/void-packages/commit/83784632d94deee5d038c8e1c4c1dffa922fca21)).
+
+* for `common/shlibs` modifications, use `common/shlibs: <pkgname>` ([example](https://github.com/void-linux/void-packages/commit/613651c91811cb4fd2e1a6be701c87072d759a9f)).
+
If you want to describe your changes in more detail, add an empty line followed by those details ([example](https://github.com/void-linux/void-packages/commit/f1c45a502086ba1952f23ace9084a870ce437bc6)).
For further information, please consult the [manual](https://github.com/void-linux/void-packages/blob/master/Manual.md).
@@ -69,8 +73,8 @@ Once you have successfully built the package, you can start a pull request.
Most pull requests should only contain a single package and dependencies which are not part of void-packages yet.
-If you make updates to packages containing a soname bump you also need to revbump all packages that are dependant. Those
-packages should also be part of the same pull request.
+If you make updates to packages containing a soname bump, you also need to update `common/shlibs` and revbump all packages that are dependant.
+There should be a commit for each package revbump, and those commits should be part of the same pull request.
When you make changes to your pull request, please *do not close and reopen your pull request*. Instead, just forcibly git push, overwriting any old commits. Closing and opening your pull requests repeatedly spams the Void maintainers.
From 2cce0c1f38f6665ddb1b8e4b61c93494eee62c41 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Mon, 4 May 2020 20:29:38 -0300
Subject: [PATCH 2/4] CONTRIBUTING.md: use local links instead of GH ones
---
CONTRIBUTING.md | 7 +++----
1 file changed, 3 insertions(+), 4 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 23b3fe68bff..ddc9e59a42a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -8,9 +8,8 @@ This document describes how you, as a contributor, can help with adding packages
If you really want to get a package into Void Linux, we recommend you package it yourself.
-We provide a [comprehensive Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md)
-on how to create new packages. There's also a
-[manual for xbps-src](https://github.com/void-linux/void-packages/blob/master/README.md), which is used
+We provide a [comprehensive Manual](./Manual.md) on how to create new packages.
+There's also a [manual for xbps-src](./README.md), which is used
to build package files from templates.
For this guide, we assume you have basic knowledge about [git](http://git-scm.org), as well as a [GitHub Account](http://github.com).
@@ -25,7 +24,7 @@ You can use the helper tool `xnew`, from the [xtools](https://github.com/chneuki
Templates must have the name `void-packages/srcpkgs/<pkgname>/template`, where `pkgname` is the same as the `pkgname` variable in the template.
-For deeper insights on the contents of template files, please read the [manual](https://github.com/void-linux/void-packages/blob/master/Manual.md), and be sure to browse the existing template files in the `srcpkgs` directory of this repository for concrete examples.
+For deeper insights on the contents of template files, please read the [manual](./Manual.md), and be sure to browse the existing template files in the `srcpkgs` directory of this repository for concrete examples.
When you've finished working on the template file, please check it with `xlint` helper from the [xtools](https://github.com/chneukirchen/xtools) package:
From 8ca3820e26a7e3cac1c45a769a36ba77392256dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Thu, 30 Apr 2020 23:02:20 -0300
Subject: [PATCH 3/4] Manual.md: use markdown anchors instead of HTML tags
Match some titles in the index to the titles in the document itself.
Use links to local files instead of GH links.
---
Manual.md | 205 ++++++++++++++++++------------------------------------
1 file changed, 69 insertions(+), 136 deletions(-)
diff --git a/Manual.md b/Manual.md
index 576b3d2032e..adbfab1c7c6 100644
--- a/Manual.md
+++ b/Manual.md
@@ -5,73 +5,72 @@ packages for XBPS, the `Void Linux` native packaging system.
*Table of Contents*
-* [Introduction](#Introduction)
- * [Quality Requirements](#quality_requirements)
- * [Package build phases](#buildphase)
- * [Package naming conventions](#namingconvention)
- * [Libraries](#libs)
- * [Language Modules](#language_modules)
- * [Language Bindings](#language_bindings)
+* [Introduction](#introduction)
+ * [Quality Requirements](#quality-requirements)
+ * [Package build phases](#package-build-phases)
+ * [Package naming conventions](#package-naming-conventions)
+ * [Libraries](#libraries)
+ * [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)
- * [About the depends variables](#explain_depends)
+ * [Global functions](#global-functions)
+ * [Global variables](#global-variables)
+ * [Available variables](#available-variables)
+ * [Mandatory variables](#mandatory-variables)
+ * [Optional variables](#optional-variables)
+ * [About the many types of `depends` variables](#about-the-many-types-of-depends-variables)
* [Repositories](#repositories)
- * [Repositories defined by Branch](#repo_by_branch)
- * [Package defined repositories](#pkg_defined_repo)
- * [Checking for new upstream releases](#updates)
- * [Handling patches](#patches)
- * [Build style scripts](#build_scripts)
- * [Build helper scripts](#build_helper)
+ * [Repositories defined by Branch](#repositories-defined-by-branch)
+ * [Package defined Repositories](#package-defined-repositories)
+ * [Checking for new upstream releases](#checking-for-new-upstream-releases)
+ * [Handling patches](#handling-patches)
+ * [build\_style scripts](#build_style-scripts)
+ * [build\_helper scripts](#build_helper-scripts)
* [Functions](#functions)
- * [Build options](#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)
- * [Writing runit services](#writing_runit_services)
- * [32bit packages](#32bit_pkgs)
- * [Subpackages](#pkgs_sub)
- * [Development packages](#pkgs_development)
- * [Data packages](#pkgs_data)
- * [Documentation packages](#pkgs_documentation)
- * [Python packages](#pkgs_python)
- * [Go packages](#pkgs_go)
- * [Haskell packages](#pkgs_haskell)
- * [Font packages](#pkgs_font)
- * [Removing a package](#pkg_remove)
- * [XBPS Triggers](#xbps_triggers)
- * [appstream-cache](#triggers_appstream_cache)
- * [binfmts](#triggers_binfmts)
- * [dkms](#triggers_dkms)
- * [gconf-schemas](#triggers_gconf_schemas)
- * [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders)
- * [gio-modules](#triggers_gio_modules)
- * [gettings-schemas](#triggers_gsettings_schemas)
- * [gtk-icon-cache](#triggers_gtk_icon_cache)
- * [gtk-immodules](#triggers_gtk_immodules)
- * [gtk-pixbuf-loaders](#triggers_gtk_pixbuf_loaders)
- * [gtk3-immodules](#triggers_gtk3_immodules)
- * [hwdb.d-dir](#triggers_hwdb.d_dir)
- * [info-files](#triggers_info_files)
- * [kernel-hooks](#triggers_kernel_hooks)
- * [mimedb](#triggers_mimedb)
- * [mkdirs](#triggers_mkdirs)
- * [pango-modules](#triggers_pango_module)
- * [pycompile](#triggers_pycompile)
- * [register-shell](#triggers_register_shell)
- * [system-accounts](#triggers_system_accounts)
- * [update-desktopdb](#triggers_update_desktopdb)
- * [x11-fonts](#triggers_x11_fonts)
- * [xml-catalog](#triggers_xml_catalog)
+ * [Build options](#build-options)
+ * [Runtime dependencies](#runtime-dependencies)
+ * [INSTALL and REMOVE files](#install-and-remove-files)
+ * [INSTALL.msg and REMOVE.msg files](#installmsg-and-removemsg-files)
+ * [Creating system accounts/groups at runtime](#creating-system-accountsgroups-at-runtime)
+ * [Writing runit services](#writing-runit-services)
+ * [32bit packages](#32bit-packages)
+ * [Subpackages](#subpackages)
+ * [Development packages](#development-packages)
+ * [Data packages](#data-packages)
+ * [Documentation packages](#documentation-packages)
+ * [Python packages](#python-packages)
+ * [Go packages](#go-packages)
+ * [Haskell packages](#haskell-packages)
+ * [Font packages](#font-packages)
+ * [Removing a package](#removing-a-package)
+ * [XBPS Triggers](#xbps-triggers)
+ * [appstream-cache](#appstream-cache)
+ * [binfmts](#binfmts)
+ * [dkms](#dkms)
+ * [gconf-schemas](#gconf-schemas)
+ * [gdk-pixbuf-loaders](#gdk-pixbuf-loaders)
+ * [gio-modules](#gio-modules)
+ * [gettings-schemas](#gsettings-schemas)
+ * [gtk-icon-cache](#gtk-icon-cache)
+ * [gtk-immodules](#gtk-immodules)
+ * [gtk-pixbuf-loaders](#gtk-pixbuf-loaders)
+ * [gtk3-immodules](#gtk3-immodules)
+ * [hwdb.d-dir](#hwdbd-dir)
+ * [info-files](#info-files)
+ * [kernel-hooks](#kernel-hooks)
+ * [mimedb](#mimedb)
+ * [mkdirs](#mkdirs)
+ * [pango-modules](#pango-modules)
+ * [pycompile](#pycompile)
+ * [register-shell](#register-shell)
+ * [system-accounts](#system-accounts)
+ * [update-desktopdb](#update-desktopdb)
+ * [x11-fonts](#x11-fonts)
+ * [xml-catalog](#xml-catalog)
* [Notes](#notes)
- * [Contributing via git](#contributing)
+ * [Contributing via git](#contributing-via-git)
* [Help](#help)
-<a id="Introduction"></a>
## Introduction
The `void-packages` repository contains all `source` packages that are the
@@ -117,7 +116,6 @@ If everything went fine after running
a binary package named `foo-1.0_1.<arch>.xbps` will be generated in the local repository
`hostdir/binpkgs`.
-<a id="quality_requirements"></a>
### Quality Requirements
Follow this list to determine if a piece of software or other technology may be
@@ -135,7 +133,6 @@ the Void packages system.
1. Required: Another package either within the repository or pending inclusion
requires the package.
-<a id="buildphase"></a>
### Package build phases
Building a package consist of the following phases:
@@ -169,10 +166,8 @@ via `make install` or any other compatible method.
successfully, the phase will be skipped later (unless its work directory
`${wrksrc}` is removed with `xbps-src clean`).
-<a id="namingconventions"></a>
### Package naming conventions
-<a id="libs"></a>
#### Libraries
Libraries are packages which provide shared objects (\*.so) in /usr/lib.
@@ -196,7 +191,6 @@ a linked program.
against this package. If the library is a sub package, its corresponding
development package should be named `lib<name>-devel`
-<a id="language_modules"></a>
#### Language Modules
Language modules are extensions to script or compiled languages. Those packages
@@ -217,7 +211,6 @@ for the language prefix.
Example: python-pam, perl-URI, python3-pyside2
-<a id="language_bindings"></a>
#### Language Bindings
Language Bindings are packages which allow programs or libraries to have
@@ -230,7 +223,6 @@ The naming convention to those packages is:
Example: gimp-python, irssi-perl
-<a id="programs"></a>
#### Programs
Programs put executables under /usr/bin (or in very special cases in other
@@ -246,7 +238,6 @@ Programs can be split into program packages and library packages. The program
package should be named as described above. The library package should be
prefixed with "lib" (see section `Libraries`)
-<a id="global_funcs"></a>
### Global functions
The following functions are defined by `xbps-src` and can be used on any template:
@@ -305,12 +296,12 @@ The following functions are defined by `xbps-src` and can be used on any templat
`$DESTDIR`. The optional 2nd argument can be used to change the
`file name`.
-- <a id="vlicense"></a>
- *vlicense()* `vlicense <file> [<name>]`
+- *vlicense()* `vlicense <file> [<name>]`
Installs `file` into `usr/share/licenses/<pkgname>` in the pkg
`$DESTDIR`. The optional 2nd argument can be used to change the
- `file name`. See [license](#var_license) for when to use it.
+ `file name`. See license in [Mandatory variables](#mandatory-variables)
+ for when to use it.
- *vsv()* `vsv <service>`
@@ -333,7 +324,6 @@ The following functions are defined by `xbps-src` and can be used on any templat
> Shell wildcards must be properly quoted, Example: `vmove "usr/lib/*.a"`.
-<a id="global_vars"></a>
### Global variables
The following variables are defined by `xbps-src` and can be used on any template:
@@ -393,10 +383,8 @@ in this directory such as `${XBPS_BUILDDIR}/${wrksrc}`.
- `XBPS_RUST_TARGET` The target architecture triplet used by `rustc` and `cargo`.
-<a id="available_vars"></a>
### Available variables
-<a id="mandatory_vars"></a>
#### Mandatory variables
The list of mandatory variables for a template:
@@ -404,8 +392,7 @@ The list of mandatory variables for a template:
- `homepage` A string pointing to the `upstream` homepage.
-- <a id="var_license"></a>
-`license` A string matching the license's [SPDX Short identifier](https://spdx.org/licenses),
+- `license` A string matching the license's [SPDX Short identifier](https://spdx.org/licenses),
`Public Domain`, or string prefixed with `custom:` for other licenses.
Multiple licenses should be separated by commas, Example: `GPL-3.0-or-later, custom:Hugware`.
@@ -432,7 +419,6 @@ the generated `binary packages` have been modified.
- `version` A string with the package version. Must not contain dashes or underscore
and at least one digit is required. Shell's variable substition usage is not allowed.
-<a id="optional_vars"></a>
#### Optional variables
- `hostmakedepends` The list of `host` dependencies required to build the package, and
@@ -702,8 +688,7 @@ Examples:
archs=noarch
```
-<a id="explain_depends"></a>
-#### About the many types of `depends` variable.
+#### About the many types of `depends` variables
So far we have listed four types of `depends`, there are `hostmakedepends`,
`makedepends`, `checkdepends` and plain old `depends`.To understand the difference
@@ -734,10 +719,8 @@ Finally, as a general rule, if something compiles the exact same way whether or
not you add a particular package to `makedepends` or `hostmakedepends`, it
shouldn't be added.
-<a id="repositories"></a>
#### Repositories
-<a id="repo_by_branch"></a>
##### Repositories defined by Branch
The global repository takes the name of
@@ -745,7 +728,6 @@ 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
update multiple packages in a second branch without polluting his local repository.
-<a id="pkg_defined_repo"></a>
##### Package defined Repositories
The second way to define a repository is by setting the `repository` variable in
@@ -758,7 +740,6 @@ The following repository names are valid:
* `nonfree`: Repository for closed source packages.
-<a id="updates"></a>
### Checking for new upstream releases
New upstream versions can be automatically checked using
@@ -797,7 +778,6 @@ in url. Defaults to `(|v|$pkgname)[-_.]*`.
part that follows numeric part of version directory
in url. Defaults to `(|\.x)`.
-<a id="patches"></a>
### Handling patches
Sometimes software needs to be patched, most commonly to fix bugs that have
@@ -820,8 +800,7 @@ be used to set the args passed to `patch(1)`. As an example, if `foo.patch` requ
special arguments to be passed to `patch(1)` that can't be used when applying other
patches, `foo.patch.args` can be created containing those args.
-<a id="build_scripts"></a>
-### build style scripts
+### 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
@@ -933,8 +912,7 @@ matching the `build_style` name, Example:
`common/environment/build-style/gnu-configure.sh`
-<a id="build_helper"></a>
-### build helper scripts
+### build\_helper scripts
The `build_helper` variable specifies shell snippets to be sourced that will create a
suitable environment for working with certain sets of packages.
@@ -963,7 +941,6 @@ This aims to fix cross-builds for when the build-style is mixed: e.g. when in a
`gnu-configure` style the configure script calls `qmake` or a `Makefile` in
`gnu-makefile` style, respectively.
-<a id="functions"></a>
### Functions
The following functions can be defined to change the behavior of how the
@@ -1022,7 +999,6 @@ Current working directory for functions is set as follows:
- For pre_configure through post_install: `build_wrksrc`
if it is defined, otherwise `wrksrc`.
-<a id="build_options"></a>
### Build options
Some packages might be built with different build options to enable/disable
@@ -1127,7 +1103,6 @@ Example: `XBPS_PKG_OPTIONS_xorg_server=opt`.
The list of supported package build options and its description is defined in the
`common/options.description` file.
-<a id="deps_runtime"></a>
#### Runtime dependencies
Dependencies for ELF objects are detected automatically by `xbps-src`, hence runtime
@@ -1167,7 +1142,6 @@ 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
when the package is being built with `xbps-src`.
-<a id="install_remove_files"></a>
### INSTALL and REMOVE files
The INSTALL and REMOVE shell snippets can be used to execute certain actions at a specified
@@ -1211,7 +1185,6 @@ be executed via `chroot(2)` won't work correctly.
> NOTE: do not use INSTALL/REMOVE scripts to print messages, see the next section for
more information.
-<a id="install_remove_files_msg"></a>
### INSTALL.msg and REMOVE.msg files
The `INSTALL.msg` and `REMOVE.msg` files can be used to print a message at post-install
@@ -1222,7 +1195,6 @@ 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
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
There's a trigger along with some variables that are specifically to create
@@ -1254,7 +1226,6 @@ accounts.
> NOTE: The underscore policy does not apply to old packages, due to the inevitable breakage of
> changing the username only new packages should follow it.
-<a id="writing_runit_services"></a>
### Writing runit services
Void Linux uses [runit](http://smarden.org/runit/) for booting and supervision of services.
@@ -1293,7 +1264,6 @@ If the service requires directories in parts of the system that are not generall
temporary filesystems. Then use the `make_dirs` variable in the template to create
those directories when the package is installed.
-<a id="32bit_pkgs"></a>
### 32bit packages
32bit packages are built automatically when the builder is x86 (32bit), but
@@ -1315,7 +1285,6 @@ This expects the basename of the target file, Example: `lib32symlinks="foo"`.
- `lib32mode` If unset, only shared/static libraries and pkg-config files will be copied to the
**32bit** package. If set to `full` all files will be copied to the 32bit package, unmodified.
-<a id="pkgs_sub"></a>
### Subpackages
In the example shown above just a binary package is generated, but with some
@@ -1375,7 +1344,6 @@ destdir (`$DESTDIR`) to the `subpackage` destdir (`$PKGDESTDIR`).
Subpackages are processed always in alphabetical order; To force a custom order,
the `subpackages` variable can be declared with the wanted order.
-<a id="pkgs_development"></a>
### Development packages
A development package, commonly generated as a subpackage, shall only contain
@@ -1405,7 +1373,6 @@ following subset of files from the main package:
* Gobject introspection XML files `usr/share/gir-1.0`
* Vala bindings `usr/share/vala`
-<a id="pkgs_data"></a>
### Data packages
Another common subpackage type is the `-data` subpackage. This subpackage
@@ -1417,7 +1384,6 @@ or card material (maps). Data subpackages are almost always `archs=noarch`.
The main package must then have `depends="${pkgname}-data-${version}_${revision}"`,
possibly in addition to other, non-automatic depends.
-<a id="pkgs_documentation"></a>
### Documentation packages
Packages intended for user interaction do not always unconditionally require
@@ -1432,7 +1398,6 @@ building packages depending on a specific package there is no need to install la
amounts of documentation for no reason. Thus the size of the documentation part should
be your guidance to decide whether or not to split off a `-doc` subpackage.
-<a id="pkgs_python"></a>
### Python packages
Python packages should be built with the `python{,2,3}-module` build style, if possible.
@@ -1481,7 +1446,6 @@ Also, a set of useful variables are defined to use in the templates:
> NOTE: it's expected that additional subpkgs must be generated to allow packaging for multiple
python versions.
-<a id="pkgs_go"></a>
### Go packages
Go packages should be built with the `go` build style, if possible.
@@ -1518,7 +1482,6 @@ otherwise preping some assets. If possible do this in pre_build().
The path to the package's source inside `$GOPATH` is available as
`$GOSRCPATH`.
-<a id="pkgs_haskell"></a>
### Haskell packages
We build Haskell package using `stack` from
@@ -1536,7 +1499,6 @@ The following variables influence how Haskell packages are built:
- `make_build_args`: This is passed as-is to `stack build ...`, so
you can add your `--flag ...` parameters there.
-<a id="pkgs_font"></a>
### Font packages
Font packages are very straightforward to write, they are always set with the
@@ -1548,7 +1510,6 @@ cache during the install/removal of the package
- `font_dirs`: which should be set to the directory where the package
installs its fonts
-<a id="pkg_remove"></a>
### Removing a package
Follows a list of things that should be done to help guarantee that a
@@ -1576,7 +1537,6 @@ the source of those patches/files.
- Remove the package from the repository index
or contact a team member that can do so.
-<a id="xbps_triggers"></a>
### XBPS Triggers
XBPS triggers are a collection of snippets of code, provided by the `xbps-triggers`
@@ -1591,7 +1551,6 @@ package.
This is not a complete overview of the package. It is recommended to read the variables
referenced and the triggers themselves.
-<a id="triggers_appstream_cache"></a>
#### appstream-cache
The appstream-cache trigger is responsible for rebuilding the appstream metadata cache.
@@ -1613,7 +1572,6 @@ directory.
It is automatically added to packages that have XML files under one of the directories
searched by appstreamcli.
-<a id="triggers_binfmts"></a>
#### binfmts
The binfmts trigger is responsible for registration and removal of arbitrary
@@ -1625,7 +1583,6 @@ to register/remove entries from the arbitrary executable binary formats database
To include the trigger use the `binfmts` variable, as the trigger won't do anything unless
it is defined.
-<a id="triggers_dkms"></a>
#### dkms
The dkms trigger is responsible for compiling and removing dynamic kernel modules of a
@@ -1638,7 +1595,6 @@ the corresponding module will be removed
To include the trigger use the `dkms_modules` variable, as the trigger won't do anything
unless it is defined.
-<a id="triggers_gconf_schemas"></a>
#### gconf-schemas
The gconf-schemas trigger is responsible for registering and removing .schemas and
@@ -1655,7 +1611,6 @@ It is automatically added to packages that have `/usr/share/gconf/schemas` prese
as a directory. All files with the schemas file extension under that directory
are passed to the trigger.
-<a id="triggers_gdk_pixbuf_loaders"></a>
#### gdk-pixbuf-loaders
The gdk-pixbuf-loaders trigger is responsible for maintaining the GDK Pixbuf loaders cache.
@@ -1669,7 +1624,6 @@ It can be added by defining `gdk-pixbuf-loaders` in the `triggers` variable. It
added automatically to any package that has the path `usr/lib/gdk-pixbuf-2.0/2.10.0/loaders`
available as a directory.
-<a id="triggers_gio_modules"></a>
#### gio-modules
The gio-modules trigger is responsible for updating the Glib GIO module cache with
@@ -1681,7 +1635,6 @@ present under `usr/lib/gio/modules`.
It is automatically added to packages that have `/usr/lib/gio/modules` present
as a directory.
-<a id="triggers_gsettings_schemas"></a>
#### gsettings-schemas
The gsettings-schemas trigger is responsible for compiling Glib's GSettings XML
@@ -1696,7 +1649,6 @@ During removal of the glib package it deletes all files inside
It is automatically added to packages that have `/usr/share/glib-2.0/schemas` present
as a directory.
-<a id="triggers_gtk_icon_cache"></a>
#### gtk-icon-cache
The gtk-icon-cache trigger is responsible for updating the gtk+ icon cache.
@@ -1710,7 +1662,6 @@ It is automatically added on packages that have `/usr/share/icons` available
as a directory, all directories under that directory have their absolute path
passed to the trigger.
-<a id="triggers_gtk_immodules"></a>
#### gtk-immodules
The gtk-immodules trigger is responsible for updating the IM (Input Method) modules
@@ -1726,7 +1677,6 @@ During removal of the `gtk+` package it removes the cache file which is located
It is automatically added to packages that have `/usr/lib/gtk-2.0/2.10.0/immodules`
present as a directory.
-<a id="triggers_gtk_pixbuf_loaders"></a>
#### gtk-pixbuf-loaders
gtk-pixbuf-loaders is the old name for the current `gdk-pixbuf-loaders` trigger and is
@@ -1735,7 +1685,6 @@ compatibility measure.
For information about how it works refer to [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders).
-<a id="triggers_gtk3_immodules"></a>
#### gtk3-immodules
The gtk3-immodules trigger is responsible for updating the IM (Input Method) modules
@@ -1751,7 +1700,6 @@ During removal of the `gtk+3` package it removes the cache file which is located
It is automatically added to packages that have `/usr/lib/gtk-3.0/3.0.0/immodules`
present as a directory.
-<a id="triggers_hwdb.d_dir"></a>
#### hwdb.d-dir
The hwdb.d-dir trigger is responsible for updating the hardware database.
@@ -1761,7 +1709,6 @@ During installation and removal it runs `usr/bin/udevadm hwdb --root=. --update`
It is automatically added to packages that have `/usr/lib/udev/hwdb.d` present
as a directory.
-<a id="triggers_info_files"></a>
#### info-files
The info-files trigger is responsible for registering and unregistering the GNU info
@@ -1779,7 +1726,6 @@ registry located at `usr/share/info`.
If it is running under another architecture it tries to use the host's `install-info`
utility.
-<a id="triggers_kernel_hooks"></a>
#### kernel-hooks
The kernel-hooks trigger is responsible for running scripts during installation/removal
@@ -1797,7 +1743,6 @@ target.
It is automatically added if the helper variable `kernel_hooks_version` is defined.
However it is not obligatory to have it defined.
-<a id="triggers_mimedb"></a>
#### mimedb
The mimedb trigger is responsible for updating the shared-mime-info database.
@@ -1807,7 +1752,6 @@ In all runs it will just execute `update-mime-database -n usr/share/mime`.
It is automatically added to packages that have `/usr/share/mime` available as
a directory.
-<a id="triggers_mkdirs"></a>
#### mkdirs
The mkdirs trigger is responsible for creating and removing directories dictated
@@ -1832,7 +1776,6 @@ During removal it will delete the directory using `rmdir`.
To include this trigger use the `make_dirs` variable, as the trigger won't do anything
unless it is defined.
-<a id="triggers_pango_module"></a>
#### pango-modules
The pango-modules trigger is currently being removed since upstream has removed the
@@ -1846,7 +1789,6 @@ Currently it removes `etc/pango/pango.modules` file during removal of the pango
It can be added by defining `pango-modules` in the `triggers` variable and has no way to get
added automatically to a package.
-<a id="triggers_pycompile"></a>
#### pycompile
The pycompile trigger is responsible for compiling python code into native
@@ -1863,7 +1805,6 @@ trigger won't do anything unless at least one of those variables is defined.
A `python_version` variable can be set to direct behaviour of the trigger.
-<a id="triggers_register_shell"></a>
#### register-shell
The register-shell trigger is responsible for registering and removing shell entries
@@ -1877,7 +1818,6 @@ During removal it will use `sed` to delete the shell from the file.
To include this trigger use the `register_shell` variable, as the trigger won't do
anything unless it is defined.
-<a id="triggers_system_accounts"></a>
#### system-accounts
The system-accounts trigger is responsible for creating and disabling system accounts
@@ -1890,7 +1830,6 @@ Example: `transmission unprivileged user - for uninstalled package transmission`
This trigger can only be used by using the `system_accounts` variable.
-<a id="triggers_update_desktopdb"></a>
#### update-desktopdb
The update-desktopdb trigger is responsible for updating the system's MIME database.
@@ -1904,7 +1843,6 @@ was created during installation.
It is automatically added to packages that have `/usr/share/applications` available as
a directory.
-<a id="triggers_x11_fonts"></a>
#### x11-fonts
The x11-fonts trigger is responsible for rebuilding the fonts.dir and fonts.scale files
@@ -1916,7 +1854,6 @@ all font directories it was given via the `font_dirs` variable.
To include this trigger use the `font_dirs` variable, as the trigger won't do anything
unless it is defined.
-<a id="triggers_xml_catalog"></a>
#### xml-catalog
The xml-catalog trigger is responsible for registering and removing SGML/XML catalog entries.
@@ -1932,7 +1869,6 @@ During removal it uses `xmlcatmgr` to remove all catalogs passed to it by the
To include this trigger use the `sgml_entries` variable or/and the `xml_entries` variable,
as the trigger won't do anything unless either of them are defined.
-<a id="notes"></a>
### Notes
- Make sure that all software is configured to use the `/usr` prefix.
@@ -1951,16 +1887,14 @@ 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;
otherwise the `debug` packages won't have debugging symbols.
-<a id="contributing"></a>
### Contributing via git
Fork the voidlinux `void-packages` git repository on github and clone it:
$ git clone git@github.com:<user>/void-packages.git
-See [CONTRIBUTING.md](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
-for information on how to format your commits and other tips for
-contributing.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for information on how to format
+your commits and other tips for contributing.
Once you've made changes to your `forked` repository you can submit
a github pull request; see https://help.github.com/articles/fork-a-repo for more information.
@@ -1971,7 +1905,6 @@ to pull in new changes:
$ git remote add upstream git://github.com/void-linux/void-packages.git
$ git pull upstream master
-<a id="help"></a>
## Help
If after reading this `manual` you still need some kind of help, please join
From 514e62519a8420585054ce10183d5b2bd48aea00 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Mon, 4 May 2020 10:55:53 -0300
Subject: [PATCH 4/4] README.md: use markdown anchors instead of HTML flags
This involves using file names instead of links for files in the repo.
---
README.md | 47 ++++++++++++++---------------------------------
1 file changed, 14 insertions(+), 33 deletions(-)
diff --git a/README.md b/README.md
index 752fb3d4fdc..2f6a965b045 100644
--- a/README.md
+++ b/README.md
@@ -7,32 +7,30 @@ The included `xbps-src` script will fetch and compile the sources, and install i
files into a `fake destdir` to generate XBPS binary packages that can be installed
or queried through the `xbps-install(1)` and `xbps-query(1)` utilities, respectively.
-See [Contributing](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
-for a general overview of how to contribute and the
-[Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md)
-for details of how to create source packages.
+See [Contributing](./CONTRIBUTING.md) for a general overview of how to contribute and the
+[Manual](./Manual.md) for details of how to create source packages.
### Table of Contents
- [Requirements](#requirements)
- [Quick start](#quick-start)
- [chroot methods](#chroot-methods)
-- [Install the bootstrap packages](#install-bootstrap)
+- [Install the bootstrap packages](#install-the-bootstrap-packages)
- [Configuration](#configuration)
- [Directory hierarchy](#directory-hierarchy)
- [Building packages](#building-packages)
-- [Package build options](#build-options)
-- [Sharing and signing your local repositories](#sharing-and-signing)
-- [Rebuilding and overwriting existing local packages](#rebuilding)
-- [Enabling distcc for distributed compilation](#distcc)
+- [Package build options](#package-build-options)
+- [Sharing and signing your local repositories](#sharing-and-signing-your-local-repositories)
+- [Rebuilding and overwriting existing local packages](#rebuilding-and-overwriting-existing-local-packages)
+- [Enabling distcc for distributed compilation](#enabling-distcc-for-distributed-compilation)
- [Distfiles mirrors](#distfiles-mirrors)
-- [Cross compiling packages for a target architecture](#cross-compiling)
-- [Using xbps-src in a foreign Linux distribution](#foreign)
-- [Remaking the masterdir](#remaking-masterdir)
-- [Keeping your masterdir uptodate](#updating-masterdir)
-- [Building 32bit packages on x86_64](#building-32bit)
-- [Building packages natively for the musl C library](#building-for-musl)
-- [Building void base-system from scratch](#building-base-system)
+- [Cross compiling packages for a target architecture](#cross-compiling-packages-for-a-target-architecture)
+- [Using xbps-src in a foreign Linux distribution](#using-xbps-src-in-a-foreign-linux-distribution)
+- [Remaking the masterdir](#remaking-the-masterdir)
+- [Keeping your masterdir uptodate](#keeping-your-masterdir-uptodate)
+- [Building 32bit packages on x86\_64](#building-32bit-packages-on-x86_64)
+- [Building packages natively for the musl C library](#building-packages-natively-for-the-musl-c-library)
+- [Building void base-system from scratch](#building-void-base-system-from-scratch)
### Requirements
@@ -58,7 +56,6 @@ multiple utilities to accomplish this task:
> NOTE: `xbps-src` does not allow building as root anymore. Use one of the chroot
methods shown above.
-<a name="quick-start"></a>
### Quick start
Clone the `void-packages` git repository and install the bootstrap packages:
@@ -95,7 +92,6 @@ Alternatively, packages can be installed with the `xi` utility, from the `xtools
# xi <package_name>
```
-<a name="chroot-methods"></a>
### chroot methods
#### xbps-uunshare(1) (default)
@@ -149,7 +145,6 @@ To enable it:
$ cd void-packages
$ echo XBPS_CHROOT_CMD=proot >> etc/conf
-<a name="install-bootstrap"></a>
### Install the bootstrap packages
The `bootstrap` packages are a set of packages required to build any available source package in a container. There are two methods to install the `bootstrap`:
@@ -185,7 +180,6 @@ used as dependencies in the source packages tree.
If you want to customize those replacements, copy `etc/defaults.virtual` to `etc/virtual`
and edit it accordingly to your needs.
-<a name="directory-hierarchy"></a>
### Directory hierarchy
The following directory hierarchy is used with a default configuration file:
@@ -222,7 +216,6 @@ The description of these directories is as follows:
- `hostdir/sources`: to store package sources.
- `hostdir/binpkgs`: local repository to store generated binary packages.
-<a name="building-packages"></a>
### Building packages
The simplest form of building package is accomplished by running the `pkg` target in `xbps-src`:
@@ -249,7 +242,6 @@ It is possible to avoid using remote repositories completely by using the `-N` f
> The default local repository may contain multiple *sub-repositories*: `debug`, `multilib`, etc.
-<a name="build-options"></a>
### Package build options
The supported build options for a source package can be shown with `xbps-src show-options`:
@@ -289,7 +281,6 @@ i.e `XBPS_PKG_OPTIONS_xorg_server=opt`.
The list of supported package build options and its description is defined in the
`common/options.description` file or in the `template` file.
-<a name="sharing-and-signing"></a>
### Sharing and signing your local repositories
To share a local repository remotely it's mandatory to sign it and the binary packages
@@ -327,7 +318,6 @@ Each time a binary package is created, a package signature must be created with
> It is not possible to sign a repository with multiple RSA keys.
-<a name="rebuilding"></a>
### Rebuilding and overwriting existing local packages
If for whatever reason a package has been built and it is available in your local repository
@@ -343,7 +333,6 @@ Reinstalling this package in your target `rootdir` can be easily done too:
> Please note that the `package expression` must be properly defined to explicitly pick up
the package from the desired repository.
-<a name="distcc"></a>
### Enabling distcc for distributed compilation
Setup the slaves (machines that will compile the code):
@@ -374,7 +363,6 @@ The slave 192.168.2.101 has a CPU with 8 cores and the /9 for the number of jobs
The slave 192.168.2.102 is set to run at most 2 compile jobs to keep its load low, even if its CPU has 4 cores.
The XBPS_MAKEJOBS setting is increased to 16 to account for the possible parallelism (2 + 9 + 2 + some slack).
-<a name="distfiles-mirrors"></a>
### Distfiles mirror(s)
In etc/conf you may optionally define a mirror or a list of mirrors to search for distfiles.
@@ -399,7 +387,6 @@ using the `file://` prefix or simply an absolute path on your build host (e.g. /
Mirror locations specified this way are bind mounted inside the chroot environment
under $XBPS_MASTERDIR and searched for distfiles just the same as remote locations.
-<a name="cross-compiling"></a>
### Cross compiling packages for a target architecture
Currently `xbps-src` can cross build packages for some target architectures with a cross compiler.
@@ -411,7 +398,6 @@ If a source package has been adapted to be **cross buildable** `xbps-src` will a
If the build for whatever reason fails, might be a new build issue or simply because it hasn't been adapted to be **cross compiled**.
-<a name="foreign"></a>
### Using xbps-src in a foreign Linux distribution
xbps-src can be used in any recent Linux distribution matching the CPU architecture.
@@ -439,7 +425,6 @@ and `xbps-src` should be fully functional; just start the `bootstrap` process, i
The default masterdir is created in the current working directory, i.e `void-packages/masterdir`.
-<a name="remaking-masterdir"></a>
### Remaking the masterdir
If for some reason you must update xbps-src and the `bootstrap-update` target is not enough, it's possible to recreate a masterdir with two simple commands (please note that `zap` keeps your `ccache/distcc/host` directories intact):
@@ -447,14 +432,12 @@ If for some reason you must update xbps-src and the `bootstrap-update` target is
$ ./xbps-src zap
$ ./xbps-src binary-bootstrap
-<a name="updating-masterdir"></a>
### Keeping your masterdir uptodate
Sometimes the bootstrap packages must be updated to the latest available version in repositories, this is accomplished with the `bootstrap-update` target:
$ ./xbps-src bootstrap-update
-<a name="building-32bit"></a>
### Building 32bit packages on x86_64
Two ways are available to build 32bit packages on x86\_64:
@@ -471,7 +454,6 @@ The second mode (native) needs a new x86 `masterdir`:
$ ./xbps-src -m masterdir-x86 binary-bootstrap i686
$ ./xbps-src -m masterdir-x86 ...
-<a name="building-for-musl"></a>
### Building packages natively for the musl C library
A native build environment is required to be able to cross compile the bootstrap packages for the musl C library; this is accomplished by installing them via `binary-bootstrap`:
@@ -493,7 +475,6 @@ Your new masterdir is now ready to build packages natively for the musl C librar
To see if the musl C dynamic linker is working as expected.
-<a name="building-base-system"></a>
### Building void base-system from scratch
To rebuild all packages in `base-system` for your native architecture:
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PR PATCH] [Updated] Run vmdfmt in the markdown files and update some information there
2020-05-04 14:20 [PR PATCH] Run vmdfmt in the markdown files and update some information there ericonr
` (5 preceding siblings ...)
2020-05-05 0:09 ` [PR PATCH] [Updated] " ericonr
@ 2020-05-05 0:11 ` ericonr
2020-07-08 19:43 ` [PR PATCH] [Closed]: Use markdown anchors " ericonr
7 siblings, 0 replies; 9+ messages in thread
From: ericonr @ 2020-05-05 0:11 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 900 bytes --]
There is an updated pull request by ericonr against master on the void-packages repository
https://github.com/ericonr/void-packages contributing
https://github.com/void-linux/void-packages/pull/21609
Run vmdfmt in the markdown files and update some information there
- Had to remove html tags from those files and use markdown anchors instead
- Changed how files in this repo are linked to each other, GH supports using `[contributing](./CONTRIBUTING.md)`.
- Added some information regarding PRs, which I took from #21481 and one of my own PRs as well. This commit can be split from the rest, but it was easier to include it, since I was already messing with the formatting.
I've tested the hyperlinks in the GH interface, and they should be good to go. The main commit for comments should be f272b49.
A patch file from https://github.com/void-linux/void-packages/pull/21609.patch is attached
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-contributing-21609.patch --]
[-- Type: text/x-diff, Size: 42327 bytes --]
From cee18a79d54d9caeef1cbc9ec15b487454c8ab75 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Mon, 4 May 2020 20:21:45 -0300
Subject: [PATCH 1/4] CONTRIBUTING.md: add commit examples and expl. to PR
process
- Add commit examples for package removal and shlibs modifications
- Explain the PR process, specially when related to soname bumps
---
CONTRIBUTING.md | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0490b5f11c2..23b3fe68bff 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -43,6 +43,10 @@ Once you have built your template file or files, the commit message should have
* for template modifications without a version change, use ```<pkgname>: <reason>``` ([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)).
+* for package removals, use ```<pkgname>: remove package``` ([example](https://github.com/void-linux/void-packages/commit/83784632d94deee5d038c8e1c4c1dffa922fca21)).
+
+* for `common/shlibs` modifications, use `common/shlibs: <pkgname>` ([example](https://github.com/void-linux/void-packages/commit/613651c91811cb4fd2e1a6be701c87072d759a9f)).
+
If you want to describe your changes in more detail, add an empty line followed by those details ([example](https://github.com/void-linux/void-packages/commit/f1c45a502086ba1952f23ace9084a870ce437bc6)).
For further information, please consult the [manual](https://github.com/void-linux/void-packages/blob/master/Manual.md).
@@ -69,8 +73,8 @@ Once you have successfully built the package, you can start a pull request.
Most pull requests should only contain a single package and dependencies which are not part of void-packages yet.
-If you make updates to packages containing a soname bump you also need to revbump all packages that are dependant. Those
-packages should also be part of the same pull request.
+If you make updates to packages containing a soname bump, you also need to update `common/shlibs` and revbump all packages that are dependant.
+There should be a commit for each package revbump, and those commits should be part of the same pull request.
When you make changes to your pull request, please *do not close and reopen your pull request*. Instead, just forcibly git push, overwriting any old commits. Closing and opening your pull requests repeatedly spams the Void maintainers.
From 2cce0c1f38f6665ddb1b8e4b61c93494eee62c41 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Mon, 4 May 2020 20:29:38 -0300
Subject: [PATCH 2/4] CONTRIBUTING.md: use local links instead of GH ones
---
CONTRIBUTING.md | 7 +++----
1 file changed, 3 insertions(+), 4 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 23b3fe68bff..ddc9e59a42a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -8,9 +8,8 @@ This document describes how you, as a contributor, can help with adding packages
If you really want to get a package into Void Linux, we recommend you package it yourself.
-We provide a [comprehensive Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md)
-on how to create new packages. There's also a
-[manual for xbps-src](https://github.com/void-linux/void-packages/blob/master/README.md), which is used
+We provide a [comprehensive Manual](./Manual.md) on how to create new packages.
+There's also a [manual for xbps-src](./README.md), which is used
to build package files from templates.
For this guide, we assume you have basic knowledge about [git](http://git-scm.org), as well as a [GitHub Account](http://github.com).
@@ -25,7 +24,7 @@ You can use the helper tool `xnew`, from the [xtools](https://github.com/chneuki
Templates must have the name `void-packages/srcpkgs/<pkgname>/template`, where `pkgname` is the same as the `pkgname` variable in the template.
-For deeper insights on the contents of template files, please read the [manual](https://github.com/void-linux/void-packages/blob/master/Manual.md), and be sure to browse the existing template files in the `srcpkgs` directory of this repository for concrete examples.
+For deeper insights on the contents of template files, please read the [manual](./Manual.md), and be sure to browse the existing template files in the `srcpkgs` directory of this repository for concrete examples.
When you've finished working on the template file, please check it with `xlint` helper from the [xtools](https://github.com/chneukirchen/xtools) package:
From 60ddd68a6cc31c06b8449f73fc4c805417be1c20 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Thu, 30 Apr 2020 23:02:20 -0300
Subject: [PATCH 3/4] Manual.md: use markdown anchors instead of HTML tags
Match some titles in the index to the titles in the document itself.
Use links to local files instead of GH links.
---
Manual.md | 205 ++++++++++++++++++------------------------------------
1 file changed, 69 insertions(+), 136 deletions(-)
diff --git a/Manual.md b/Manual.md
index 576b3d2032e..5a5c56b6fcc 100644
--- a/Manual.md
+++ b/Manual.md
@@ -5,73 +5,72 @@ packages for XBPS, the `Void Linux` native packaging system.
*Table of Contents*
-* [Introduction](#Introduction)
- * [Quality Requirements](#quality_requirements)
- * [Package build phases](#buildphase)
- * [Package naming conventions](#namingconvention)
- * [Libraries](#libs)
- * [Language Modules](#language_modules)
- * [Language Bindings](#language_bindings)
+* [Introduction](#introduction)
+ * [Quality Requirements](#quality-requirements)
+ * [Package build phases](#package-build-phases)
+ * [Package naming conventions](#package-naming-conventions)
+ * [Libraries](#libraries)
+ * [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)
- * [About the depends variables](#explain_depends)
+ * [Global functions](#global-functions)
+ * [Global variables](#global-variables)
+ * [Available variables](#available-variables)
+ * [Mandatory variables](#mandatory-variables)
+ * [Optional variables](#optional-variables)
+ * [About the many types of `depends` variables](#about-the-many-types-of-depends-variables)
* [Repositories](#repositories)
- * [Repositories defined by Branch](#repo_by_branch)
- * [Package defined repositories](#pkg_defined_repo)
- * [Checking for new upstream releases](#updates)
- * [Handling patches](#patches)
- * [Build style scripts](#build_scripts)
- * [Build helper scripts](#build_helper)
+ * [Repositories defined by Branch](#repositories-defined-by-branch)
+ * [Package defined Repositories](#package-defined-repositories)
+ * [Checking for new upstream releases](#checking-for-new-upstream-releases)
+ * [Handling patches](#handling-patches)
+ * [build\_style scripts](#build_style-scripts)
+ * [build\_helper scripts](#build_helper-scripts)
* [Functions](#functions)
- * [Build options](#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)
- * [Writing runit services](#writing_runit_services)
- * [32bit packages](#32bit_pkgs)
- * [Subpackages](#pkgs_sub)
- * [Development packages](#pkgs_development)
- * [Data packages](#pkgs_data)
- * [Documentation packages](#pkgs_documentation)
- * [Python packages](#pkgs_python)
- * [Go packages](#pkgs_go)
- * [Haskell packages](#pkgs_haskell)
- * [Font packages](#pkgs_font)
- * [Removing a package](#pkg_remove)
- * [XBPS Triggers](#xbps_triggers)
- * [appstream-cache](#triggers_appstream_cache)
- * [binfmts](#triggers_binfmts)
- * [dkms](#triggers_dkms)
- * [gconf-schemas](#triggers_gconf_schemas)
- * [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders)
- * [gio-modules](#triggers_gio_modules)
- * [gettings-schemas](#triggers_gsettings_schemas)
- * [gtk-icon-cache](#triggers_gtk_icon_cache)
- * [gtk-immodules](#triggers_gtk_immodules)
- * [gtk-pixbuf-loaders](#triggers_gtk_pixbuf_loaders)
- * [gtk3-immodules](#triggers_gtk3_immodules)
- * [hwdb.d-dir](#triggers_hwdb.d_dir)
- * [info-files](#triggers_info_files)
- * [kernel-hooks](#triggers_kernel_hooks)
- * [mimedb](#triggers_mimedb)
- * [mkdirs](#triggers_mkdirs)
- * [pango-modules](#triggers_pango_module)
- * [pycompile](#triggers_pycompile)
- * [register-shell](#triggers_register_shell)
- * [system-accounts](#triggers_system_accounts)
- * [update-desktopdb](#triggers_update_desktopdb)
- * [x11-fonts](#triggers_x11_fonts)
- * [xml-catalog](#triggers_xml_catalog)
+ * [Build options](#build-options)
+ * [Runtime dependencies](#runtime-dependencies)
+ * [INSTALL and REMOVE files](#install-and-remove-files)
+ * [INSTALL.msg and REMOVE.msg files](#installmsg-and-removemsg-files)
+ * [Creating system accounts/groups at runtime](#creating-system-accountsgroups-at-runtime)
+ * [Writing runit services](#writing-runit-services)
+ * [32bit packages](#32bit-packages)
+ * [Subpackages](#subpackages)
+ * [Development packages](#development-packages)
+ * [Data packages](#data-packages)
+ * [Documentation packages](#documentation-packages)
+ * [Python packages](#python-packages)
+ * [Go packages](#go-packages)
+ * [Haskell packages](#haskell-packages)
+ * [Font packages](#font-packages)
+ * [Removing a package](#removing-a-package)
+ * [XBPS Triggers](#xbps-triggers)
+ * [appstream-cache](#appstream-cache)
+ * [binfmts](#binfmts)
+ * [dkms](#dkms)
+ * [gconf-schemas](#gconf-schemas)
+ * [gdk-pixbuf-loaders](#gdk-pixbuf-loaders)
+ * [gio-modules](#gio-modules)
+ * [gettings-schemas](#gsettings-schemas)
+ * [gtk-icon-cache](#gtk-icon-cache)
+ * [gtk-immodules](#gtk-immodules)
+ * [gtk-pixbuf-loaders](#gtk-pixbuf-loaders)
+ * [gtk3-immodules](#gtk3-immodules)
+ * [hwdb.d-dir](#hwdbd-dir)
+ * [info-files](#info-files)
+ * [kernel-hooks](#kernel-hooks)
+ * [mimedb](#mimedb)
+ * [mkdirs](#mkdirs)
+ * [pango-modules](#pango-modules)
+ * [pycompile](#pycompile)
+ * [register-shell](#register-shell)
+ * [system-accounts](#system-accounts)
+ * [update-desktopdb](#update-desktopdb)
+ * [x11-fonts](#x11-fonts)
+ * [xml-catalog](#xml-catalog)
* [Notes](#notes)
- * [Contributing via git](#contributing)
+ * [Contributing via git](#contributing-via-git)
* [Help](#help)
-<a id="Introduction"></a>
## Introduction
The `void-packages` repository contains all `source` packages that are the
@@ -117,7 +116,6 @@ If everything went fine after running
a binary package named `foo-1.0_1.<arch>.xbps` will be generated in the local repository
`hostdir/binpkgs`.
-<a id="quality_requirements"></a>
### Quality Requirements
Follow this list to determine if a piece of software or other technology may be
@@ -135,7 +133,6 @@ the Void packages system.
1. Required: Another package either within the repository or pending inclusion
requires the package.
-<a id="buildphase"></a>
### Package build phases
Building a package consist of the following phases:
@@ -169,10 +166,8 @@ via `make install` or any other compatible method.
successfully, the phase will be skipped later (unless its work directory
`${wrksrc}` is removed with `xbps-src clean`).
-<a id="namingconventions"></a>
### Package naming conventions
-<a id="libs"></a>
#### Libraries
Libraries are packages which provide shared objects (\*.so) in /usr/lib.
@@ -196,7 +191,6 @@ a linked program.
against this package. If the library is a sub package, its corresponding
development package should be named `lib<name>-devel`
-<a id="language_modules"></a>
#### Language Modules
Language modules are extensions to script or compiled languages. Those packages
@@ -217,7 +211,6 @@ for the language prefix.
Example: python-pam, perl-URI, python3-pyside2
-<a id="language_bindings"></a>
#### Language Bindings
Language Bindings are packages which allow programs or libraries to have
@@ -230,7 +223,6 @@ The naming convention to those packages is:
Example: gimp-python, irssi-perl
-<a id="programs"></a>
#### Programs
Programs put executables under /usr/bin (or in very special cases in other
@@ -246,7 +238,6 @@ Programs can be split into program packages and library packages. The program
package should be named as described above. The library package should be
prefixed with "lib" (see section `Libraries`)
-<a id="global_funcs"></a>
### Global functions
The following functions are defined by `xbps-src` and can be used on any template:
@@ -305,12 +296,12 @@ The following functions are defined by `xbps-src` and can be used on any templat
`$DESTDIR`. The optional 2nd argument can be used to change the
`file name`.
-- <a id="vlicense"></a>
- *vlicense()* `vlicense <file> [<name>]`
+- *vlicense()* `vlicense <file> [<name>]`
Installs `file` into `usr/share/licenses/<pkgname>` in the pkg
`$DESTDIR`. The optional 2nd argument can be used to change the
- `file name`. See [license](#var_license) for when to use it.
+ `file name`. See `license` in [Mandatory variables](#mandatory-variables)
+ for when to use it.
- *vsv()* `vsv <service>`
@@ -333,7 +324,6 @@ The following functions are defined by `xbps-src` and can be used on any templat
> Shell wildcards must be properly quoted, Example: `vmove "usr/lib/*.a"`.
-<a id="global_vars"></a>
### Global variables
The following variables are defined by `xbps-src` and can be used on any template:
@@ -393,10 +383,8 @@ in this directory such as `${XBPS_BUILDDIR}/${wrksrc}`.
- `XBPS_RUST_TARGET` The target architecture triplet used by `rustc` and `cargo`.
-<a id="available_vars"></a>
### Available variables
-<a id="mandatory_vars"></a>
#### Mandatory variables
The list of mandatory variables for a template:
@@ -404,8 +392,7 @@ The list of mandatory variables for a template:
- `homepage` A string pointing to the `upstream` homepage.
-- <a id="var_license"></a>
-`license` A string matching the license's [SPDX Short identifier](https://spdx.org/licenses),
+- `license` A string matching the license's [SPDX Short identifier](https://spdx.org/licenses),
`Public Domain`, or string prefixed with `custom:` for other licenses.
Multiple licenses should be separated by commas, Example: `GPL-3.0-or-later, custom:Hugware`.
@@ -432,7 +419,6 @@ the generated `binary packages` have been modified.
- `version` A string with the package version. Must not contain dashes or underscore
and at least one digit is required. Shell's variable substition usage is not allowed.
-<a id="optional_vars"></a>
#### Optional variables
- `hostmakedepends` The list of `host` dependencies required to build the package, and
@@ -702,8 +688,7 @@ Examples:
archs=noarch
```
-<a id="explain_depends"></a>
-#### About the many types of `depends` variable.
+#### About the many types of `depends` variables
So far we have listed four types of `depends`, there are `hostmakedepends`,
`makedepends`, `checkdepends` and plain old `depends`.To understand the difference
@@ -734,10 +719,8 @@ Finally, as a general rule, if something compiles the exact same way whether or
not you add a particular package to `makedepends` or `hostmakedepends`, it
shouldn't be added.
-<a id="repositories"></a>
#### Repositories
-<a id="repo_by_branch"></a>
##### Repositories defined by Branch
The global repository takes the name of
@@ -745,7 +728,6 @@ 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
update multiple packages in a second branch without polluting his local repository.
-<a id="pkg_defined_repo"></a>
##### Package defined Repositories
The second way to define a repository is by setting the `repository` variable in
@@ -758,7 +740,6 @@ The following repository names are valid:
* `nonfree`: Repository for closed source packages.
-<a id="updates"></a>
### Checking for new upstream releases
New upstream versions can be automatically checked using
@@ -797,7 +778,6 @@ in url. Defaults to `(|v|$pkgname)[-_.]*`.
part that follows numeric part of version directory
in url. Defaults to `(|\.x)`.
-<a id="patches"></a>
### Handling patches
Sometimes software needs to be patched, most commonly to fix bugs that have
@@ -820,8 +800,7 @@ be used to set the args passed to `patch(1)`. As an example, if `foo.patch` requ
special arguments to be passed to `patch(1)` that can't be used when applying other
patches, `foo.patch.args` can be created containing those args.
-<a id="build_scripts"></a>
-### build style scripts
+### 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
@@ -933,8 +912,7 @@ matching the `build_style` name, Example:
`common/environment/build-style/gnu-configure.sh`
-<a id="build_helper"></a>
-### build helper scripts
+### build\_helper scripts
The `build_helper` variable specifies shell snippets to be sourced that will create a
suitable environment for working with certain sets of packages.
@@ -963,7 +941,6 @@ This aims to fix cross-builds for when the build-style is mixed: e.g. when in a
`gnu-configure` style the configure script calls `qmake` or a `Makefile` in
`gnu-makefile` style, respectively.
-<a id="functions"></a>
### Functions
The following functions can be defined to change the behavior of how the
@@ -1022,7 +999,6 @@ Current working directory for functions is set as follows:
- For pre_configure through post_install: `build_wrksrc`
if it is defined, otherwise `wrksrc`.
-<a id="build_options"></a>
### Build options
Some packages might be built with different build options to enable/disable
@@ -1127,7 +1103,6 @@ Example: `XBPS_PKG_OPTIONS_xorg_server=opt`.
The list of supported package build options and its description is defined in the
`common/options.description` file.
-<a id="deps_runtime"></a>
#### Runtime dependencies
Dependencies for ELF objects are detected automatically by `xbps-src`, hence runtime
@@ -1167,7 +1142,6 @@ 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
when the package is being built with `xbps-src`.
-<a id="install_remove_files"></a>
### INSTALL and REMOVE files
The INSTALL and REMOVE shell snippets can be used to execute certain actions at a specified
@@ -1211,7 +1185,6 @@ be executed via `chroot(2)` won't work correctly.
> NOTE: do not use INSTALL/REMOVE scripts to print messages, see the next section for
more information.
-<a id="install_remove_files_msg"></a>
### INSTALL.msg and REMOVE.msg files
The `INSTALL.msg` and `REMOVE.msg` files can be used to print a message at post-install
@@ -1222,7 +1195,6 @@ 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
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
There's a trigger along with some variables that are specifically to create
@@ -1254,7 +1226,6 @@ accounts.
> NOTE: The underscore policy does not apply to old packages, due to the inevitable breakage of
> changing the username only new packages should follow it.
-<a id="writing_runit_services"></a>
### Writing runit services
Void Linux uses [runit](http://smarden.org/runit/) for booting and supervision of services.
@@ -1293,7 +1264,6 @@ If the service requires directories in parts of the system that are not generall
temporary filesystems. Then use the `make_dirs` variable in the template to create
those directories when the package is installed.
-<a id="32bit_pkgs"></a>
### 32bit packages
32bit packages are built automatically when the builder is x86 (32bit), but
@@ -1315,7 +1285,6 @@ This expects the basename of the target file, Example: `lib32symlinks="foo"`.
- `lib32mode` If unset, only shared/static libraries and pkg-config files will be copied to the
**32bit** package. If set to `full` all files will be copied to the 32bit package, unmodified.
-<a id="pkgs_sub"></a>
### Subpackages
In the example shown above just a binary package is generated, but with some
@@ -1375,7 +1344,6 @@ destdir (`$DESTDIR`) to the `subpackage` destdir (`$PKGDESTDIR`).
Subpackages are processed always in alphabetical order; To force a custom order,
the `subpackages` variable can be declared with the wanted order.
-<a id="pkgs_development"></a>
### Development packages
A development package, commonly generated as a subpackage, shall only contain
@@ -1405,7 +1373,6 @@ following subset of files from the main package:
* Gobject introspection XML files `usr/share/gir-1.0`
* Vala bindings `usr/share/vala`
-<a id="pkgs_data"></a>
### Data packages
Another common subpackage type is the `-data` subpackage. This subpackage
@@ -1417,7 +1384,6 @@ or card material (maps). Data subpackages are almost always `archs=noarch`.
The main package must then have `depends="${pkgname}-data-${version}_${revision}"`,
possibly in addition to other, non-automatic depends.
-<a id="pkgs_documentation"></a>
### Documentation packages
Packages intended for user interaction do not always unconditionally require
@@ -1432,7 +1398,6 @@ building packages depending on a specific package there is no need to install la
amounts of documentation for no reason. Thus the size of the documentation part should
be your guidance to decide whether or not to split off a `-doc` subpackage.
-<a id="pkgs_python"></a>
### Python packages
Python packages should be built with the `python{,2,3}-module` build style, if possible.
@@ -1481,7 +1446,6 @@ Also, a set of useful variables are defined to use in the templates:
> NOTE: it's expected that additional subpkgs must be generated to allow packaging for multiple
python versions.
-<a id="pkgs_go"></a>
### Go packages
Go packages should be built with the `go` build style, if possible.
@@ -1518,7 +1482,6 @@ otherwise preping some assets. If possible do this in pre_build().
The path to the package's source inside `$GOPATH` is available as
`$GOSRCPATH`.
-<a id="pkgs_haskell"></a>
### Haskell packages
We build Haskell package using `stack` from
@@ -1536,7 +1499,6 @@ The following variables influence how Haskell packages are built:
- `make_build_args`: This is passed as-is to `stack build ...`, so
you can add your `--flag ...` parameters there.
-<a id="pkgs_font"></a>
### Font packages
Font packages are very straightforward to write, they are always set with the
@@ -1548,7 +1510,6 @@ cache during the install/removal of the package
- `font_dirs`: which should be set to the directory where the package
installs its fonts
-<a id="pkg_remove"></a>
### Removing a package
Follows a list of things that should be done to help guarantee that a
@@ -1576,7 +1537,6 @@ the source of those patches/files.
- Remove the package from the repository index
or contact a team member that can do so.
-<a id="xbps_triggers"></a>
### XBPS Triggers
XBPS triggers are a collection of snippets of code, provided by the `xbps-triggers`
@@ -1591,7 +1551,6 @@ package.
This is not a complete overview of the package. It is recommended to read the variables
referenced and the triggers themselves.
-<a id="triggers_appstream_cache"></a>
#### appstream-cache
The appstream-cache trigger is responsible for rebuilding the appstream metadata cache.
@@ -1613,7 +1572,6 @@ directory.
It is automatically added to packages that have XML files under one of the directories
searched by appstreamcli.
-<a id="triggers_binfmts"></a>
#### binfmts
The binfmts trigger is responsible for registration and removal of arbitrary
@@ -1625,7 +1583,6 @@ to register/remove entries from the arbitrary executable binary formats database
To include the trigger use the `binfmts` variable, as the trigger won't do anything unless
it is defined.
-<a id="triggers_dkms"></a>
#### dkms
The dkms trigger is responsible for compiling and removing dynamic kernel modules of a
@@ -1638,7 +1595,6 @@ the corresponding module will be removed
To include the trigger use the `dkms_modules` variable, as the trigger won't do anything
unless it is defined.
-<a id="triggers_gconf_schemas"></a>
#### gconf-schemas
The gconf-schemas trigger is responsible for registering and removing .schemas and
@@ -1655,7 +1611,6 @@ It is automatically added to packages that have `/usr/share/gconf/schemas` prese
as a directory. All files with the schemas file extension under that directory
are passed to the trigger.
-<a id="triggers_gdk_pixbuf_loaders"></a>
#### gdk-pixbuf-loaders
The gdk-pixbuf-loaders trigger is responsible for maintaining the GDK Pixbuf loaders cache.
@@ -1669,7 +1624,6 @@ It can be added by defining `gdk-pixbuf-loaders` in the `triggers` variable. It
added automatically to any package that has the path `usr/lib/gdk-pixbuf-2.0/2.10.0/loaders`
available as a directory.
-<a id="triggers_gio_modules"></a>
#### gio-modules
The gio-modules trigger is responsible for updating the Glib GIO module cache with
@@ -1681,7 +1635,6 @@ present under `usr/lib/gio/modules`.
It is automatically added to packages that have `/usr/lib/gio/modules` present
as a directory.
-<a id="triggers_gsettings_schemas"></a>
#### gsettings-schemas
The gsettings-schemas trigger is responsible for compiling Glib's GSettings XML
@@ -1696,7 +1649,6 @@ During removal of the glib package it deletes all files inside
It is automatically added to packages that have `/usr/share/glib-2.0/schemas` present
as a directory.
-<a id="triggers_gtk_icon_cache"></a>
#### gtk-icon-cache
The gtk-icon-cache trigger is responsible for updating the gtk+ icon cache.
@@ -1710,7 +1662,6 @@ It is automatically added on packages that have `/usr/share/icons` available
as a directory, all directories under that directory have their absolute path
passed to the trigger.
-<a id="triggers_gtk_immodules"></a>
#### gtk-immodules
The gtk-immodules trigger is responsible for updating the IM (Input Method) modules
@@ -1726,7 +1677,6 @@ During removal of the `gtk+` package it removes the cache file which is located
It is automatically added to packages that have `/usr/lib/gtk-2.0/2.10.0/immodules`
present as a directory.
-<a id="triggers_gtk_pixbuf_loaders"></a>
#### gtk-pixbuf-loaders
gtk-pixbuf-loaders is the old name for the current `gdk-pixbuf-loaders` trigger and is
@@ -1735,7 +1685,6 @@ compatibility measure.
For information about how it works refer to [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders).
-<a id="triggers_gtk3_immodules"></a>
#### gtk3-immodules
The gtk3-immodules trigger is responsible for updating the IM (Input Method) modules
@@ -1751,7 +1700,6 @@ During removal of the `gtk+3` package it removes the cache file which is located
It is automatically added to packages that have `/usr/lib/gtk-3.0/3.0.0/immodules`
present as a directory.
-<a id="triggers_hwdb.d_dir"></a>
#### hwdb.d-dir
The hwdb.d-dir trigger is responsible for updating the hardware database.
@@ -1761,7 +1709,6 @@ During installation and removal it runs `usr/bin/udevadm hwdb --root=. --update`
It is automatically added to packages that have `/usr/lib/udev/hwdb.d` present
as a directory.
-<a id="triggers_info_files"></a>
#### info-files
The info-files trigger is responsible for registering and unregistering the GNU info
@@ -1779,7 +1726,6 @@ registry located at `usr/share/info`.
If it is running under another architecture it tries to use the host's `install-info`
utility.
-<a id="triggers_kernel_hooks"></a>
#### kernel-hooks
The kernel-hooks trigger is responsible for running scripts during installation/removal
@@ -1797,7 +1743,6 @@ target.
It is automatically added if the helper variable `kernel_hooks_version` is defined.
However it is not obligatory to have it defined.
-<a id="triggers_mimedb"></a>
#### mimedb
The mimedb trigger is responsible for updating the shared-mime-info database.
@@ -1807,7 +1752,6 @@ In all runs it will just execute `update-mime-database -n usr/share/mime`.
It is automatically added to packages that have `/usr/share/mime` available as
a directory.
-<a id="triggers_mkdirs"></a>
#### mkdirs
The mkdirs trigger is responsible for creating and removing directories dictated
@@ -1832,7 +1776,6 @@ During removal it will delete the directory using `rmdir`.
To include this trigger use the `make_dirs` variable, as the trigger won't do anything
unless it is defined.
-<a id="triggers_pango_module"></a>
#### pango-modules
The pango-modules trigger is currently being removed since upstream has removed the
@@ -1846,7 +1789,6 @@ Currently it removes `etc/pango/pango.modules` file during removal of the pango
It can be added by defining `pango-modules` in the `triggers` variable and has no way to get
added automatically to a package.
-<a id="triggers_pycompile"></a>
#### pycompile
The pycompile trigger is responsible for compiling python code into native
@@ -1863,7 +1805,6 @@ trigger won't do anything unless at least one of those variables is defined.
A `python_version` variable can be set to direct behaviour of the trigger.
-<a id="triggers_register_shell"></a>
#### register-shell
The register-shell trigger is responsible for registering and removing shell entries
@@ -1877,7 +1818,6 @@ During removal it will use `sed` to delete the shell from the file.
To include this trigger use the `register_shell` variable, as the trigger won't do
anything unless it is defined.
-<a id="triggers_system_accounts"></a>
#### system-accounts
The system-accounts trigger is responsible for creating and disabling system accounts
@@ -1890,7 +1830,6 @@ Example: `transmission unprivileged user - for uninstalled package transmission`
This trigger can only be used by using the `system_accounts` variable.
-<a id="triggers_update_desktopdb"></a>
#### update-desktopdb
The update-desktopdb trigger is responsible for updating the system's MIME database.
@@ -1904,7 +1843,6 @@ was created during installation.
It is automatically added to packages that have `/usr/share/applications` available as
a directory.
-<a id="triggers_x11_fonts"></a>
#### x11-fonts
The x11-fonts trigger is responsible for rebuilding the fonts.dir and fonts.scale files
@@ -1916,7 +1854,6 @@ all font directories it was given via the `font_dirs` variable.
To include this trigger use the `font_dirs` variable, as the trigger won't do anything
unless it is defined.
-<a id="triggers_xml_catalog"></a>
#### xml-catalog
The xml-catalog trigger is responsible for registering and removing SGML/XML catalog entries.
@@ -1932,7 +1869,6 @@ During removal it uses `xmlcatmgr` to remove all catalogs passed to it by the
To include this trigger use the `sgml_entries` variable or/and the `xml_entries` variable,
as the trigger won't do anything unless either of them are defined.
-<a id="notes"></a>
### Notes
- Make sure that all software is configured to use the `/usr` prefix.
@@ -1951,16 +1887,14 @@ 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;
otherwise the `debug` packages won't have debugging symbols.
-<a id="contributing"></a>
### Contributing via git
Fork the voidlinux `void-packages` git repository on github and clone it:
$ git clone git@github.com:<user>/void-packages.git
-See [CONTRIBUTING.md](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
-for information on how to format your commits and other tips for
-contributing.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for information on how to format
+your commits and other tips for contributing.
Once you've made changes to your `forked` repository you can submit
a github pull request; see https://help.github.com/articles/fork-a-repo for more information.
@@ -1971,7 +1905,6 @@ to pull in new changes:
$ git remote add upstream git://github.com/void-linux/void-packages.git
$ git pull upstream master
-<a id="help"></a>
## Help
If after reading this `manual` you still need some kind of help, please join
From 2f6fee047f0e71df953d0a4e61cb81f239bd5fe0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Mon, 4 May 2020 10:55:53 -0300
Subject: [PATCH 4/4] README.md: use markdown anchors instead of HTML flags
This involves using file names instead of links for files in the repo.
---
README.md | 47 ++++++++++++++---------------------------------
1 file changed, 14 insertions(+), 33 deletions(-)
diff --git a/README.md b/README.md
index 752fb3d4fdc..2f6a965b045 100644
--- a/README.md
+++ b/README.md
@@ -7,32 +7,30 @@ The included `xbps-src` script will fetch and compile the sources, and install i
files into a `fake destdir` to generate XBPS binary packages that can be installed
or queried through the `xbps-install(1)` and `xbps-query(1)` utilities, respectively.
-See [Contributing](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
-for a general overview of how to contribute and the
-[Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md)
-for details of how to create source packages.
+See [Contributing](./CONTRIBUTING.md) for a general overview of how to contribute and the
+[Manual](./Manual.md) for details of how to create source packages.
### Table of Contents
- [Requirements](#requirements)
- [Quick start](#quick-start)
- [chroot methods](#chroot-methods)
-- [Install the bootstrap packages](#install-bootstrap)
+- [Install the bootstrap packages](#install-the-bootstrap-packages)
- [Configuration](#configuration)
- [Directory hierarchy](#directory-hierarchy)
- [Building packages](#building-packages)
-- [Package build options](#build-options)
-- [Sharing and signing your local repositories](#sharing-and-signing)
-- [Rebuilding and overwriting existing local packages](#rebuilding)
-- [Enabling distcc for distributed compilation](#distcc)
+- [Package build options](#package-build-options)
+- [Sharing and signing your local repositories](#sharing-and-signing-your-local-repositories)
+- [Rebuilding and overwriting existing local packages](#rebuilding-and-overwriting-existing-local-packages)
+- [Enabling distcc for distributed compilation](#enabling-distcc-for-distributed-compilation)
- [Distfiles mirrors](#distfiles-mirrors)
-- [Cross compiling packages for a target architecture](#cross-compiling)
-- [Using xbps-src in a foreign Linux distribution](#foreign)
-- [Remaking the masterdir](#remaking-masterdir)
-- [Keeping your masterdir uptodate](#updating-masterdir)
-- [Building 32bit packages on x86_64](#building-32bit)
-- [Building packages natively for the musl C library](#building-for-musl)
-- [Building void base-system from scratch](#building-base-system)
+- [Cross compiling packages for a target architecture](#cross-compiling-packages-for-a-target-architecture)
+- [Using xbps-src in a foreign Linux distribution](#using-xbps-src-in-a-foreign-linux-distribution)
+- [Remaking the masterdir](#remaking-the-masterdir)
+- [Keeping your masterdir uptodate](#keeping-your-masterdir-uptodate)
+- [Building 32bit packages on x86\_64](#building-32bit-packages-on-x86_64)
+- [Building packages natively for the musl C library](#building-packages-natively-for-the-musl-c-library)
+- [Building void base-system from scratch](#building-void-base-system-from-scratch)
### Requirements
@@ -58,7 +56,6 @@ multiple utilities to accomplish this task:
> NOTE: `xbps-src` does not allow building as root anymore. Use one of the chroot
methods shown above.
-<a name="quick-start"></a>
### Quick start
Clone the `void-packages` git repository and install the bootstrap packages:
@@ -95,7 +92,6 @@ Alternatively, packages can be installed with the `xi` utility, from the `xtools
# xi <package_name>
```
-<a name="chroot-methods"></a>
### chroot methods
#### xbps-uunshare(1) (default)
@@ -149,7 +145,6 @@ To enable it:
$ cd void-packages
$ echo XBPS_CHROOT_CMD=proot >> etc/conf
-<a name="install-bootstrap"></a>
### Install the bootstrap packages
The `bootstrap` packages are a set of packages required to build any available source package in a container. There are two methods to install the `bootstrap`:
@@ -185,7 +180,6 @@ used as dependencies in the source packages tree.
If you want to customize those replacements, copy `etc/defaults.virtual` to `etc/virtual`
and edit it accordingly to your needs.
-<a name="directory-hierarchy"></a>
### Directory hierarchy
The following directory hierarchy is used with a default configuration file:
@@ -222,7 +216,6 @@ The description of these directories is as follows:
- `hostdir/sources`: to store package sources.
- `hostdir/binpkgs`: local repository to store generated binary packages.
-<a name="building-packages"></a>
### Building packages
The simplest form of building package is accomplished by running the `pkg` target in `xbps-src`:
@@ -249,7 +242,6 @@ It is possible to avoid using remote repositories completely by using the `-N` f
> The default local repository may contain multiple *sub-repositories*: `debug`, `multilib`, etc.
-<a name="build-options"></a>
### Package build options
The supported build options for a source package can be shown with `xbps-src show-options`:
@@ -289,7 +281,6 @@ i.e `XBPS_PKG_OPTIONS_xorg_server=opt`.
The list of supported package build options and its description is defined in the
`common/options.description` file or in the `template` file.
-<a name="sharing-and-signing"></a>
### Sharing and signing your local repositories
To share a local repository remotely it's mandatory to sign it and the binary packages
@@ -327,7 +318,6 @@ Each time a binary package is created, a package signature must be created with
> It is not possible to sign a repository with multiple RSA keys.
-<a name="rebuilding"></a>
### Rebuilding and overwriting existing local packages
If for whatever reason a package has been built and it is available in your local repository
@@ -343,7 +333,6 @@ Reinstalling this package in your target `rootdir` can be easily done too:
> Please note that the `package expression` must be properly defined to explicitly pick up
the package from the desired repository.
-<a name="distcc"></a>
### Enabling distcc for distributed compilation
Setup the slaves (machines that will compile the code):
@@ -374,7 +363,6 @@ The slave 192.168.2.101 has a CPU with 8 cores and the /9 for the number of jobs
The slave 192.168.2.102 is set to run at most 2 compile jobs to keep its load low, even if its CPU has 4 cores.
The XBPS_MAKEJOBS setting is increased to 16 to account for the possible parallelism (2 + 9 + 2 + some slack).
-<a name="distfiles-mirrors"></a>
### Distfiles mirror(s)
In etc/conf you may optionally define a mirror or a list of mirrors to search for distfiles.
@@ -399,7 +387,6 @@ using the `file://` prefix or simply an absolute path on your build host (e.g. /
Mirror locations specified this way are bind mounted inside the chroot environment
under $XBPS_MASTERDIR and searched for distfiles just the same as remote locations.
-<a name="cross-compiling"></a>
### Cross compiling packages for a target architecture
Currently `xbps-src` can cross build packages for some target architectures with a cross compiler.
@@ -411,7 +398,6 @@ If a source package has been adapted to be **cross buildable** `xbps-src` will a
If the build for whatever reason fails, might be a new build issue or simply because it hasn't been adapted to be **cross compiled**.
-<a name="foreign"></a>
### Using xbps-src in a foreign Linux distribution
xbps-src can be used in any recent Linux distribution matching the CPU architecture.
@@ -439,7 +425,6 @@ and `xbps-src` should be fully functional; just start the `bootstrap` process, i
The default masterdir is created in the current working directory, i.e `void-packages/masterdir`.
-<a name="remaking-masterdir"></a>
### Remaking the masterdir
If for some reason you must update xbps-src and the `bootstrap-update` target is not enough, it's possible to recreate a masterdir with two simple commands (please note that `zap` keeps your `ccache/distcc/host` directories intact):
@@ -447,14 +432,12 @@ If for some reason you must update xbps-src and the `bootstrap-update` target is
$ ./xbps-src zap
$ ./xbps-src binary-bootstrap
-<a name="updating-masterdir"></a>
### Keeping your masterdir uptodate
Sometimes the bootstrap packages must be updated to the latest available version in repositories, this is accomplished with the `bootstrap-update` target:
$ ./xbps-src bootstrap-update
-<a name="building-32bit"></a>
### Building 32bit packages on x86_64
Two ways are available to build 32bit packages on x86\_64:
@@ -471,7 +454,6 @@ The second mode (native) needs a new x86 `masterdir`:
$ ./xbps-src -m masterdir-x86 binary-bootstrap i686
$ ./xbps-src -m masterdir-x86 ...
-<a name="building-for-musl"></a>
### Building packages natively for the musl C library
A native build environment is required to be able to cross compile the bootstrap packages for the musl C library; this is accomplished by installing them via `binary-bootstrap`:
@@ -493,7 +475,6 @@ Your new masterdir is now ready to build packages natively for the musl C librar
To see if the musl C dynamic linker is working as expected.
-<a name="building-base-system"></a>
### Building void base-system from scratch
To rebuild all packages in `base-system` for your native architecture:
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PR PATCH] [Closed]: Use markdown anchors in the markdown files and update some information there
2020-05-04 14:20 [PR PATCH] Run vmdfmt in the markdown files and update some information there ericonr
` (6 preceding siblings ...)
2020-05-05 0:11 ` ericonr
@ 2020-07-08 19:43 ` ericonr
7 siblings, 0 replies; 9+ messages in thread
From: ericonr @ 2020-07-08 19:43 UTC (permalink / raw)
To: ml
[-- Attachment #1: Type: text/plain, Size: 749 bytes --]
There's a closed pull request on the void-packages repository
Use markdown anchors in the markdown files and update some information there
https://github.com/void-linux/void-packages/pull/21609
Description:
- Had to remove html tags from those files and use markdown anchors instead
- Changed how files in this repo are linked to each other, GH supports using `[contributing](./CONTRIBUTING.md)`.
- Added some information regarding PRs, which I took from #21481 and one of my own PRs as well. This commit can be split from the rest, but it was easier to include it, since I was already messing with the formatting.
I've tested the hyperlinks in the GH interface, and they should be good to go. The main commit for comments should be f272b49.
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2020-07-08 19:43 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-05-04 14:20 [PR PATCH] Run vmdfmt in the markdown files and update some information there ericonr
2020-05-04 14:27 ` Duncaen
2020-05-04 14:31 ` [PR PATCH] [Updated] " ericonr
2020-05-04 17:37 ` ericonr
2020-05-04 23:30 ` [PR PATCH] [Updated] " ericonr
2020-05-04 23:34 ` ericonr
2020-05-05 0:09 ` [PR PATCH] [Updated] " ericonr
2020-05-05 0:11 ` ericonr
2020-07-08 19:43 ` [PR PATCH] [Closed]: Use markdown anchors " ericonr
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).