cpanminus: update to 1.7048.
[void-pkg.git] / README.md
blobf1f3c170c1c520a4118df922245d515788ea419f
1 ## The XBPS source packages collection
3 This repository contains the XBPS source packages collection to build binary packages
4 for the Void Linux distribution.
6 The included `xbps-src` script will fetch and compile the sources, and install its
7 files into a `fake destdir` to generate XBPS binary packages that can be installed
8 or queried through the `xbps-install(1)` and `xbps-query(1)` utilities, respectively.
10 See [Contributing](./CONTRIBUTING.md) for a general overview of how to contribute and the
11 [Manual](./Manual.md) for details of how to create source packages.
13 ### Table of Contents
15 - [Requirements](#requirements)
16 - [Quick start](#quick-start)
17 - [chroot methods](#chroot-methods)
18 - [Install the bootstrap packages](#install-bootstrap)
19 - [Configuration](#configuration)
20 - [Directory hierarchy](#directory-hierarchy)
21 - [Building packages](#building-packages)
22 - [Package build options](#build-options)
23 - [Sharing and signing your local repositories](#sharing-and-signing)
24 - [Rebuilding and overwriting existing local packages](#rebuilding)
25 - [Enabling distcc for distributed compilation](#distcc)
26 - [Distfiles mirrors](#distfiles-mirrors)
27 - [Cross compiling packages for a target architecture](#cross-compiling)
28 - [Using xbps-src in a foreign Linux distribution](#foreign)
29 - [Remaking the masterdir](#remaking-masterdir)
30 - [Keeping your masterdir uptodate](#updating-masterdir)
31 - [Building 32bit packages on x86_64](#building-32bit)
32 - [Building packages natively for the musl C library](#building-for-musl)
33 - [Building void base-system from scratch](#building-base-system)
35 ### Requirements
37 - GNU bash
38 - xbps >= 0.56
39 - git(1) - unless configured to not, see etc/defaults.conf
40 - common POSIX utilities included by default in almost all UNIX systems
41 - curl(1) - required by `xbps-src update-check`
43 For bootstrapping additionally:
44 - flock(1) - util-linux
45 - bsdtar or GNU tar (in that order of preference)
46 - install(1) - GNU coreutils
47 - objcopy(1), objdump(1), strip(1): binutils
49 `xbps-src` requires [a utility to chroot](#chroot-methods) and bind mount existing directories
50 into a `masterdir` that is used as its main `chroot` directory. `xbps-src` supports
51 multiple utilities to accomplish this task.
53 > NOTE: `xbps-src` does not allow building as root anymore. Use one of the chroot
54 methods.
56 <a name="quick-start"></a>
57 ### Quick start
59 Clone the `void-packages` git repository and install the bootstrap packages:
61 ```
62 $ git clone https://github.com/void-linux/void-packages.git
63 $ cd void-packages
64 $ ./xbps-src binary-bootstrap
65 ```
67 Build a package by specifying the `pkg` target and the package name:
69 ```
70 $ ./xbps-src pkg <package_name>
71 ```
73 Use `./xbps-src -h` to list all available targets and options.
75 To build packages marked as 'restricted', modify `etc/conf`:
77 ```
78 $ echo XBPS_ALLOW_RESTRICTED=yes >> etc/conf
79 ```
81 Once built, the package will be available in `hostdir/binpkgs` or an appropriate subdirectory (e.g. `hostdir/binpkgs/nonfree`). To install the package:
83 ```
84 # xbps-install --repository hostdir/binpkgs <package_name>
85 ```
87 Alternatively, packages can be installed with the `xi` utility, from the `xtools` package. `xi` takes the repository of the current working directory into account.
89 ```
90 $ xi <package_name>
91 ```
93 <a name="chroot-methods"></a>
94 ### chroot methods
96 #### xbps-uunshare(1) (default)
98 XBPS utility that uses `user_namespaces(7)` (part of xbps, default without `-t` flag).
100 This utility requires these Linux kernel options:
102 - CONFIG\_NAMESPACES
103 - CONFIG\_IPC\_NS
104 - CONFIG\_UTS\_NS
105 - CONFIG\_USER\_NS
107 This is the default method, and if your system does not support any of the required kernel
108 options it will fail with `EINVAL (Invalid argument)`.
110 #### xbps-uchroot(1)
112 XBPS utility that uses `namespaces` and must be `setgid` (part of xbps).
114 > NOTE: This is the only method that implements functionality of `xbps-src -t`, therefore the
115 flag ignores the choice made in configuration files and enables `xbps-uchroot`.
117 This utility requires these Linux kernel options:
119 - CONFIG\_NAMESPACES
120 - CONFIG\_IPC\_NS
121 - CONFIG\_PID\_NS
122 - CONFIG\_UTS\_NS
124 Your user must be added to a special group to be able to use `xbps-uchroot(1)` and the
125 executable must be `setgid`:
127     # chown root:<group> xbps-uchroot
128     # chmod 4750 xbps-uchroot
129     # usermod -a -G <group> <user>
131 > NOTE: by default in void you shouldn't do this manually, your user must be a member of
132 the `xbuilder` group.
134 To enable it:
136     $ cd void-packages
137     $ echo XBPS_CHROOT_CMD=uchroot >> etc/conf
139 If for some reason it's erroring out as `ERROR clone (Operation not permitted)`, check that
140 your user is a member of the required `group` and that `xbps-uchroot(1)` utility has the
141 proper permissions and owner/group as explained above.
143 #### bwrap(1)
145 bubblewrap, sandboxing tool for unprivileged users that uses
146 user namespaces or setuid.
147 See <https://github.com/containers/bubblewrap>.
149 #### ethereal
151 Destroys host system it runs on. Only useful for one-shot containers, i.e docker (used with CI).
153 <a name="install-bootstrap"></a>
154 ### Install the bootstrap packages
156 There is a set of packages that makes up the initial build container, called the `bootstrap`.
157 These packages are installed into the `masterdir` in order to create the container.
159 The primary and recommended way to set up this container is using the `binary-bootstrap`
160 command. This will use pre-existing binary packages, either from remote `xbps` repositories
161 or from your local repository.
163 There is also the `bootstrap` command, which will build all necessary `bootstrap` packages from
164 scratch. This is usually not recommended, since those packages are built using your host system's
165 toolchain and are neither fully featured nor reproducible (your host system may influence the
166 build) and thus should only be used as a stage 0 for bootstrapping new Void systems.
168 If you still choose to use `bootstrap`, use the resulting stage 0 container to rebuild all
169 `bootstrap` packages again, then use `binary-bootstrap` (stage 1) and rebuild the `bootstrap`
170 packages once more (to gain stage 2, and then use `binary-bootstrap` again). Once you've done
171 that, you will have a `bootstrap` set equivalent to using `binary-bootstrap` in the first place.
173 Also keep in mind that a full source `bootstrap` is time consuming and will require having an
174 assortment of utilities installed in your host system, such as `binutils`, `gcc`, `perl`,
175 `texinfo` and others.
177 ### Configuration
179 The `etc/defaults.conf` file contains the possible settings that can be overridden
180 through the `etc/conf` configuration file for the `xbps-src` utility; if that file
181 does not exist, will try to read configuration settings from `$XDG_CONFIG_HOME/xbps-src.conf`, `~/.config/xbps-src.conf`, `~/.xbps-src.conf`.
183 If you want to customize default `CFLAGS`, `CXXFLAGS` and `LDFLAGS`, don't override
184 those defined in `etc/defaults.conf`, set them on `etc/conf` instead i.e:
186     $ echo 'XBPS_CFLAGS="your flags here"' >> etc/conf
187     $ echo 'XBPS_LDFLAGS="your flags here"' >> etc/conf
189 Native and cross compiler/linker flags are set per architecture in `common/build-profiles`
190 and `common/cross-profiles` respectively. Ideally those settings are good enough by default,
191 and there's no need to set your own unless you know what you are doing.
193 #### Virtual packages
195 The `etc/defaults.virtual` file contains the default replacements for virtual packages,
196 used as dependencies in the source packages tree.
198 If you want to customize those replacements, copy `etc/defaults.virtual` to `etc/virtual`
199 and edit it accordingly to your needs.
201 <a name="directory-hierarchy"></a>
202 ### Directory hierarchy
204 The following directory hierarchy is used with a default configuration file:
206          /void-packages
207             |- common
208             |- etc
209             |- srcpkgs
210             |  |- xbps
211             |     |- template
212             |
213             |- hostdir
214             |  |- binpkgs ...
215             |  |- ccache ...
216             |  |- distcc-<arch> ...
217             |  |- repocache ...
218             |  |- sources ...
219             |
220             |- masterdir-<arch>
221             |  |- builddir -> ...
222             |  |- destdir -> ...
223             |  |- host -> bind mounted from <hostdir>
224             |  |- void-packages -> bind mounted from <void-packages>
227 The description of these directories is as follows:
229  - `masterdir-<arch>`: master directory to be used as rootfs to build/install packages.
230  - `builddir`: to unpack package source tarballs and where packages are built.
231  - `destdir`: to install packages, aka **fake destdir**.
232  - `hostdir/ccache`: to store ccache data if the `XBPS_CCACHE` option is enabled.
233  - `hostdir/distcc-<arch>`: to store distcc data if the `XBPS_DISTCC` option is enabled.
234  - `hostdir/repocache`: to store binary packages from remote repositories.
235  - `hostdir/sources`: to store package sources.
236  - `hostdir/binpkgs`: local repository to store generated binary packages.
238 <a name="building-packages"></a>
239 ### Building packages
241 The simplest form of building package is accomplished by running the `pkg` target in `xbps-src`:
244 $ cd void-packages
245 $ ./xbps-src pkg <pkgname>
248 When the package and its required dependencies are built, the binary packages will be created
249 and registered in the default local repository at `hostdir/binpkgs`; the path to this local repository can be added to
250 any xbps configuration file (see xbps.d(5)) or by explicitly appending them via cmdline, i.e:
252     $ xbps-install --repository=hostdir/binpkgs ...
253     $ xbps-query --repository=hostdir/binpkgs ...
255 By default **xbps-src** will try to resolve package dependencies in this order:
257  - If a dependency exists in the local repository, use it (`hostdir/binpkgs`).
258  - If a dependency exists in a remote repository, use it.
259  - If a dependency exists in a source package, use it.
261 It is possible to avoid using remote repositories completely by using the `-N` flag.
263 > The default local repository may contain multiple *sub-repositories*: `debug`, `multilib`, etc.
265 <a name="build-options"></a>
266 ### Package build options
268 The supported build options for a source package can be shown with `xbps-src show-options`:
270     $ ./xbps-src show-options foo
272 Build options can be enabled with the `-o` flag of `xbps-src`:
274     $ ./xbps-src -o option,option1 pkg foo
276 Build options can be disabled by prefixing them with `~`:
278     $ ./xbps-src -o ~option,~option1 pkg foo
280 Both ways can be used together to enable and/or disable multiple options
281 at the same time with `xbps-src`:
283     $ ./xbps-src -o option,~option1,~option2 pkg foo
285 The build options can also be shown for binary packages via `xbps-query(1)`:
287     $ xbps-query -R --property=build-options foo
289 > NOTE: if you build a package with a custom option, and that package is available
290 in an official void repository, an update will ignore those options. Put that package
291 on `hold` mode via `xbps-pkgdb(1)`, i.e `xbps-pkgdb -m hold foo` to ignore updates
292 with `xbps-install -u`. Once the package is on `hold`, the only way to update it
293 is by declaring it explicitly: `xbps-install -u foo`.
295 Permanent global package build options can be set via `XBPS_PKG_OPTIONS` variable in the
296 `etc/conf` configuration file. Per package build options can be set via
297 `XBPS_PKG_OPTIONS_<pkgname>`.
299 > NOTE: if `pkgname` contains `dashes`, those should be replaced by `underscores`
300 i.e `XBPS_PKG_OPTIONS_xorg_server=opt`.
302 The list of supported package build options and its description is defined in the
303 `common/options.description` file or in the `template` file.
305 <a name="sharing-and-signing"></a>
306 ### Sharing and signing your local repositories
308 To share a local repository remotely it's mandatory to sign it and the binary packages
309 stored on it. This is accomplished with the `xbps-rindex(1)` utility.
311 First a RSA key must be created with `openssl(1)` or `ssh-keygen(1)`:
313         $ openssl genrsa -des3 -out privkey.pem 4096
317         $ ssh-keygen -t rsa -b 4096 -m PEM -f privkey.pem
319 > Only RSA keys in PEM format are currently accepted by xbps.
321 Once the RSA private key is ready you can use it to initialize the repository metadata:
323         $ xbps-rindex --sign --signedby "I'm Groot" --privkey privkey.pem $PWD/hostdir/binpkgs
325 And then make a signature per package:
327         $ xbps-rindex --sign-pkg --privkey privkey.pem $PWD/hostdir/binpkgs/*.xbps
329 > If --privkey is unset, it defaults to `~/.ssh/id_rsa`.
331 If the RSA key was protected with a passphrase you'll have to type it, or alternatively set
332 it via the `XBPS_PASSPHRASE` environment variable.
334 Once the binary packages have been signed, check if the repository contains the appropriate `hex fingerprint`:
336         $ xbps-query --repository=hostdir/binpkgs -vL
337         ...
339 Each time a binary package is created, a package signature must be created with `--sign-pkg`.
341 > It is not possible to sign a repository with multiple RSA keys.
343 If packages in `hostdir/binpkgs` are signed, the key in `.plist` format (as imported by xbps) can be placed
344 in `etc/repo-keys/` to prevent xbps-src from prompting to import that key.
346 <a name="rebuilding"></a>
347 ### Rebuilding and overwriting existing local packages
349 Packages are overwritten on every build to make getting package with changed build options easy.
350 To make xbps-src skip build and preserve first package build with given version and revision,
351 same as in official void repository, set `XBPS_PRESERVE_PKGS=yes` in `etc/conf` file.
353 Reinstalling a package in your target `rootdir` can be easily done too:
355     $ xbps-install --repository=/path/to/local/repo -yf xbps-0.25_1
357 Using `-f` flag twice will overwrite configuration files.
359 > Please note that the `package expression` must be properly defined to explicitly pick up
360 the package from the desired repository.
362 <a name="distcc"></a>
363 ### Enabling distcc for distributed compilation
365 Setup the workers (machines that will compile the code):
367     # xbps-install -Sy distcc
368     
369 Update distcc compiler whitelist
371     # update-distcc-symlinks
373 Modify the configuration to allow your local network machines to use distcc (e.g. `192.168.2.0/24`):
375     # echo "192.168.2.0/24" >> /etc/distcc/clients.allow
377 Enable and start the `distccd` service:
379     # ln -s /etc/sv/distccd /var/service
381 Install distcc on the host (machine that executes xbps-src) as well.
382 Unless you want to use the host as worker from other machines, there is no need
383 to modify the configuration.
385 On the host you can now enable distcc in the `void-packages/etc/conf` file:
387     XBPS_DISTCC=yes
388     XBPS_DISTCC_HOSTS="localhost/2 --localslots_cpp=24 192.168.2.101/9 192.168.2.102/2"
389     XBPS_MAKEJOBS=16
391 The example values assume a localhost CPU with 4 cores of which at most 2 are used for compiler jobs.
392 The number of slots for preprocessor jobs is set to 24 in order to have enough preprocessed data for other CPUs to compile.
393 The worker 192.168.2.101 has a CPU with 8 cores and the /9 for the number of jobs is a saturating choice.
394 The worker 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.
395 The XBPS_MAKEJOBS setting is increased to 16 to account for the possible parallelism (2 + 9 + 2 + some slack).
397 <a name="distfiles-mirrors"></a>
398 ### Distfiles mirror(s)
400 In etc/conf you may optionally define a mirror or a list of mirrors to search for distfiles.
402     $ echo 'XBPS_DISTFILES_MIRROR="ftp://192.168.100.5/gentoo/distfiles"' >> etc/conf
404 If more than one mirror is to be searched, you can either specify multiple URLs separated
405 with blanks, or add to the variable like this
407     $ echo 'XBPS_DISTFILES_MIRROR+=" https://sources.voidlinux.org/"' >> etc/conf
409 Make sure to put the blank after the first double quote in this case.
411 The mirrors are searched in order for the distfiles to build a package until the
412 checksum of the downloaded file matches the one specified in the template.
414 Ultimately, if no mirror carries the distfile, or in case all downloads failed the
415 checksum verification, the original download location is used.
417 If you use `uchroot` for your XBPS_CHROOT_CMD, you may also specify a local path
418 using the `file://` prefix or simply an absolute path on your build host (e.g. /mnt/distfiles).
419 Mirror locations specified this way are bind mounted inside the chroot environment
420 under $XBPS_MASTERDIR and searched for distfiles just the same as remote locations.
422 <a name="cross-compiling"></a>
423 ### Cross compiling packages for a target architecture
425 Currently `xbps-src` can cross build packages for some target architectures with a cross compiler.
426 The supported target is shown with `./xbps-src -h`.
428 If a source package has been adapted to be **cross buildable** `xbps-src` will automatically build the binary package(s) with a simple command:
430     $ ./xbps-src -a <target> pkg <pkgname>
432 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**.
434 <a name="foreign"></a>
435 ### Using xbps-src in a foreign Linux distribution
437 xbps-src can be used in any recent Linux distribution matching the CPU architecture.
439 To use xbps-src in your Linux distribution use the following instructions. Let's start downloading the xbps static binaries:
441     $ wget http://repo-default.voidlinux.org/static/xbps-static-latest.<arch>-musl.tar.xz
442     $ mkdir ~/XBPS
443     $ tar xvf xbps-static-latest.<arch>-musl.tar.xz -C ~/XBPS
444     $ export PATH=~/XBPS/usr/bin:$PATH
446 If `xbps-uunshare` does not work because of lack of `user_namespaces(7)` support,
447 try other [chroot methods](#chroot-methods).
449 Clone the `void-packages` git repository:
451     $ git clone https://github.com/void-linux/void-packages.git
453 and `xbps-src` should be fully functional; just start the `bootstrap` process, i.e:
455     $ ./xbps-src binary-bootstrap
457 The default masterdir is created in the current working directory, i.e. `void-packages/masterdir-<arch>`, where `<arch>` for the default masterdir is is the native xbps architecture.
459 <a name="remaking-masterdir"></a>
460 ### Remaking the masterdir
462 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):
464     $ ./xbps-src zap
465     $ ./xbps-src binary-bootstrap
467 <a name="updating-masterdir"></a>
468 ### Keeping your masterdir uptodate
470 Sometimes the bootstrap packages must be updated to the latest available version in repositories, this is accomplished with the `bootstrap-update` target:
472     $ ./xbps-src bootstrap-update
474 <a name="building-32bit"></a>
475 ### Building 32bit packages on x86_64
477 Two ways are available to build 32bit packages on x86\_64:
479  - native mode with a 32bit masterdir (recommended, used in official repository)
480  - cross compilation mode to i686 [target](#cross-compiling)
482 The canonical mode (native) needs a new x86 `masterdir`:
484     $ ./xbps-src -A i686 binary-bootstrap
485     $ ./xbps-src -A i686 ...
487 <a name="building-for-musl"></a>
488 ### Building packages natively for the musl C library
490 The canonical way of building packages for same architecture but different C library is through a dedicated masterdir by using the host architecture flag `-A`.
491 To build for x86_64-musl on glibc x86_64 system, prepare a new masterdir with the musl packages:
493     $ ./xbps-src -A x86_64-musl binary-bootstrap
495 This will create and bootstrap a new masterdir called `masterdir-x86_64-musl` that will be used when `-A x86_64-musl` is specified.
496 Your new masterdir is now ready to build packages natively for the musl C library:
498     $ ./xbps-src -A x86_64-musl pkg ...
500 <a name="building-base-system"></a>
501 ### Building void base-system from scratch
503 To rebuild all packages in `base-system` for your native architecture:
505     $ ./xbps-src -N pkg base-system
507 It's also possible to cross compile everything from scratch:
509     $ ./xbps-src -a <target> -N pkg base-system
511 Once the build has finished, you can specify the path to the local repository to `void-mklive`, i.e:
513     # cd void-mklive
514     # make
515     # ./mklive.sh ... -r /path/to/hostdir/binpkgs