2014-04-01 12:13:59 +02:00
## The XBPS source packages collection
2012-12-23 11:18:30 +01:00
2014-04-01 11:29:21 +02:00
This repository contains the XBPS source packages collection to build binary packages
2014-03-22 13:09:30 +01:00
for the Void Linux distribution.
2012-12-23 11:18:30 +01:00
2014-11-22 17:19:25 +01:00
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
2015-06-04 11:38:49 +02:00
or queried through the `xbps-install(1)` and `xbps-query(1)` utilities, respectively.
2012-12-23 11:18:30 +01:00
2015-05-02 05:24:11 +02:00
### Requirements
- GNU bash
2015-07-12 10:05:39 +02:00
- xbps >= 0.46
2015-05-02 05:24:11 +02:00
2015-04-14 08:32:02 +02:00
`xbps-src` requires an utility to chroot and bind mount existing directories
2015-04-14 08:14:07 +02:00
into a `masterdir` that is used as its main `chroot` directory. `xbps-src` supports
multiple utilities to accomplish this task:
2015-06-04 11:38:49 +02:00
- `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).
2015-04-14 08:14:07 +02:00
- `proot(1)` - utility that implements chroot/bind mounts in user space, see http://proot.me.
2015-04-14 08:33:31 +02:00
> NOTE: you don't need to be `root` to use `xbps-src`, use your preferred chroot style as explained
below.
2015-04-14 08:14:07 +02:00
2015-06-04 11:38:49 +02:00
#### xbps-uunshare(1)
2015-04-14 08:14:07 +02:00
2015-06-28 11:01:36 +02:00
This utility requires these Linux kernel options:
2015-04-14 08:14:07 +02:00
- CONFIG\_NAMESPACES
- CONFIG\_IPC\_NS
- CONFIG\_UTS\_NS
- CONFIG\_USER\_NS
2015-04-14 08:38:07 +02:00
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)` .
2015-06-04 11:38:49 +02:00
#### xbps-uchroot(1)
2015-04-14 08:14:07 +02:00
2015-06-28 11:01:36 +02:00
This utility requires these Linux kernel options:
2015-04-14 08:14:07 +02:00
- CONFIG\_NAMESPACES
- CONFIG\_IPC\_NS
- CONFIG\_PID\_NS
- CONFIG\_UTS\_NS
2015-06-04 11:38:49 +02:00
Your user must be added to a special group to be able to use `xbps-uchroot(1)` and the
2015-04-14 08:14:07 +02:00
executable must be `setgid` :
2015-04-14 08:23:07 +02:00
# chown root:< group > xbps-uchroot
# chmod 4750 xbps-uchroot
2015-04-14 08:40:19 +02:00
# usermod -a -G < group > < user >
2015-04-14 08:23:07 +02:00
> NOTE: by default in void you shouldn't do this manually, your user must be a member of
the `xbuilder` group.
2014-11-22 17:19:25 +01:00
2015-04-14 08:32:02 +02:00
To enable it:
$ cd void-packages
$ echo XBPS_CHROOT_CMD=uchroot >> etc/conf
2015-06-28 11:01:36 +02:00
If for some reason it's erroring out as `ERROR clone (Operation not permitted)` , check that
2015-06-04 11:38:49 +02:00
your user is a member of the required `group` and that `xbps-uchroot(1)` utility has the
2015-04-14 08:38:07 +02:00
proper permissions and owner/group as explained above.
2015-04-14 08:32:02 +02:00
#### proot(1)
The `proot(1)` utility implements chroot and bind mounts support completely in user space,
2015-06-28 11:01:36 +02:00
and can be used if your Linux kernel does not have support for namespaces. See http://proot.me
2015-04-14 08:32:02 +02:00
for more information.
To enable it:
$ cd void-packages
$ echo XBPS_CHROOT_CMD=proot >> etc/conf
2014-11-22 17:19:25 +01:00
### Quick setup in Void
Clone the `void-packages` git repository, install the bootstrap packages:
```
$ git clone git://github.com/voidlinux/void-packages.git
$ cd void-packages
$ ./xbps-src binary-bootstrap
```
2014-09-06 12:37:09 +02:00
Type:
2014-03-22 13:09:30 +01:00
$ ./xbps-src -h
to see all available targets/options and start building any available package
in the `srcpkgs` directory.
2012-12-23 11:18:30 +01:00
2014-11-22 17:19:25 +01:00
### 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` :
2015-05-02 05:30:03 +02:00
- `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.
2014-11-22 17:19:25 +01:00
- `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` .
2014-09-06 12:37:09 +02:00
### Configuration
2015-06-28 11:01:36 +02:00
The `etc/defaults.conf` file contains the possible settings that can be overridden
2014-07-01 10:40:33 +02:00
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` .
2014-03-22 19:49:59 +01:00
2014-05-16 10:21:50 +02:00
If you want to customize default `CFLAGS` , `CXXFLAGS` and `LDFLAGS` , don't override
2015-03-04 15:42:40 +01:00
those defined in `etc/defaults.conf` , set them on `etc/conf` instead i.e:
2014-05-16 10:21:50 +02:00
2015-03-04 15:42:40 +01:00
$ echo 'XBPS_CFLAGS="your flags here"' >> etc/conf
$ echo 'XBPS_LDFLAGS="your flags here"' >> etc/conf
2014-05-16 10:21:50 +02:00
2015-04-06 16:35:20 +02:00
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.
2015-01-18 12:54:37 +01:00
### Virtual packages
2014-09-06 12:37:09 +02:00
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.
2015-07-12 10:05:39 +02:00
### Directory hierarchy
2014-11-22 17:19:25 +01:00
2015-07-12 10:05:39 +02:00
The following directory hierarchy is used with a default configuration file:
2014-11-22 17:19:25 +01:00
2014-11-22 17:47:24 +01:00
/void-packages
2014-11-22 17:19:25 +01:00
|- common
|- etc
|- srcpkgs
| |- xbps
| |- template
|
|- hostdir
| |- binpkgs ...
| |- ccache-< arch > ...
| |- 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** .
2015-07-12 10:05:39 +02:00
- `hostdir/ccache` : to store ccache data if the `XBPS_CCACHE` option is enabled.
2014-11-22 17:19:25 +01:00
- `hostdir/distcc-<arch>` : to store distcc data if the `XBPS_DISTCC` option is enabled.
2014-11-22 17:47:24 +01:00
- `hostdir/repocache` : to store binary packages from remote repositories.
- `hostdir/sources` : to store package sources.
2014-11-22 17:19:25 +01:00
- `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` :
```
$ cd void-packages
$ ./xbps-src pkg < pkgname >
```
2014-11-22 17:27:09 +01:00
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
2015-01-12 23:42:48 +01:00
any xbps configuration file (see xbps.d(5)) or by explicitly appending them via cmdline, i.e:
2014-11-22 17:27:09 +01:00
2015-04-06 16:35:20 +02:00
$ xbps-install --repository=hostdir/binpkgs ...
$ xbps-query --repository=hostdir/binpkgs ...
2015-01-12 23:42:48 +01:00
2014-11-22 17:19:25 +01:00
By default **xbps-src** will try to resolve package dependencies in this order:
- If dependency exists in the local repository, use it (`hostdir/binpkgs`).
- If dependency exists in a remote repository, use it.
- If dependency exists in a source package, use it.
It is possible to avoid using remote repositories completely by using the `-N` flag.
2015-01-13 00:16:41 +01:00
> The default local repository may contain multiple *sub-repositories*: `debug`, `multilib`, etc.
2014-11-22 17:27:09 +01:00
2015-01-22 07:40:25 +01:00
### Package build options
The supported build options for a source package can be shown with `xbps-src show-options` :
$ ./xbps-src show-options foo
Build options can be enabled with the `-o` flag of `xbps-src` :
$ ./xbps-src -o option,option1 pkg foo
Build options can be disabled by prefixing them with `~` :
$ ./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` :
$ ./xbps-src -o option,~option1,~option2 pkg foo
2015-06-04 11:38:49 +02:00
The build options can also be shown for binary packages via `xbps-query(1)` :
2015-01-22 07:40:25 +01:00
$ 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
2015-06-04 11:38:49 +02:00
on `hold` mode via `xbps-pkgdb(1)` , i.e `xbps-pkgdb -m hold foo` to ignore updates
2015-01-22 07:40:25 +01:00
with `xbps-install -u` . Once the package is on `hold` , the only way to update it
2015-06-28 11:01:36 +02:00
is by declaring it explicitly: `xbps-install -u foo` .
2015-01-22 07:40:25 +01:00
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` .
The list of supported package build options and its description is defined in the
`common/options.description` file or in the `template` file.
2015-01-12 23:50:01 +01:00
### Sharing and signing your local repositories
To share a local repository remotely it's mandatory to sign it and the binary packages
2015-06-04 11:38:49 +02:00
stored on it. This is accomplished with the `xbps-rindex(1)` utility.
2015-01-12 23:50:01 +01:00
2015-06-04 11:38:49 +02:00
First a RSA key must be created with `openssl(1)` or `ssh-keygen(1)` :
2015-01-12 23:50:01 +01:00
$ openssl genrsa -des3 -out privkey.pem 4096
or
$ ssh-keygen -t rsa -b 4096 -f privkey.pem
2015-01-13 00:16:41 +01:00
> Only RSA keys in PEM format are currently accepted by xbps.
2015-01-12 23:50:01 +01:00
2015-07-12 10:05:39 +02:00
Once the RSA private key is ready you can use it to initialize the repository metadata:
2015-01-12 23:50:01 +01:00
2015-01-13 00:03:01 +01:00
$ xbps-rindex --sign --signedby "I'm Groot" --privkey privkey.pem $PWD/hostdir/binpkgs
2015-07-12 10:05:39 +02:00
And then make a signature per package:
$ xbps-rindex --sign-pkg --privkey privkey.pem $PWD/hostdir/binpkgs/*.xbps
2015-01-13 00:16:41 +01:00
> If --privkey is unset, it defaults to `~/.ssh/id_rsa`.
2015-01-12 23:50:01 +01:00
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.
2015-06-28 11:01:36 +02:00
Once the binary packages have been signed, check the repository contains the appropriate `hex fingerprint` :
2015-01-12 23:50:01 +01:00
2015-07-12 10:05:39 +02:00
$ xbps-query --repository=hostdir/binpkgs -vL
2015-01-12 23:50:01 +01:00
...
2015-07-12 10:05:39 +02:00
Each time a binary package is created, a package signature must be created with `--sign-pkg` .
2015-01-13 00:16:41 +01:00
> It is not possible to sign a repository with multiple RSA keys.
2014-11-22 17:19:25 +01:00
### 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` :
$ ./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
> 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
Enable and start the `distccd` service:
# ln -s /etc/sv/distccd /var/service
In the host (machine that executes xbps-src) enable the following settings in the `void-packages/etc/conf` file:
XBPS_DISTCC=yes
XBPS_DISTCC_HOSTS="192.168.2.101 192.168.2.102"
2014-11-22 17:47:24 +01:00
### Cross compiling packages for a target architecture
2014-11-22 17:19:25 +01:00
2015-05-02 05:57:40 +02:00
Currently `xbps-src` can cross build packages for some target architectures with a cross compiler.
The supported target is shown with `./xbps-src -h` .
2014-11-22 17:19:25 +01:00
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 >
2014-11-22 17:47:24 +01:00
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** .
2014-11-22 17:19:25 +01:00
2015-06-28 11:01:36 +02:00
### Using xbps-src in a foreign Linux distribution
2014-11-22 17:19:25 +01:00
2015-06-28 11:01:36 +02:00
xbps-src can be used in any recent Linux distribution matching the CPU architecture.
2014-11-22 17:19:25 +01:00
2015-06-28 11:01:36 +02:00
To use xbps-src in your Linux distribution use the following instructions. Let's start downloading the xbps static binaries:
2014-11-22 17:19:25 +01:00
$ wget http://repo.voidlinux.eu/static/xbps-static-latest.< arch > -musl.tar.xz
$ mkdir ~/XBPS
$ tar xvf xbps-static-latest.< arch > .tar.xz -C ~/XBPS
2015-06-03 18:43:01 +02:00
$ export PATH=~/XBPS/usr/bin:$PATH
2015-04-14 08:14:07 +02:00
2015-03-10 09:34:34 +01:00
If your system does not support `user namespaces` , a privileged group is required to be able to use
2015-06-04 11:38:49 +02:00
`xbps-uchroot(1)` with xbps-src, by default it's set to the `xbuilder` group, change this to your desired group:
2014-11-22 17:19:25 +01:00
2015-06-03 18:43:01 +02:00
# chown root:< group > ~/XBPS/usr/bin/xbps-uchroot.static
# chmod 4750 ~/XBPS/usr/bin/xbps-uchroot.static
2014-11-22 17:19:25 +01:00
Clone the `void-packages` git repository:
$ git clone git://github.com/voidlinux/void-packages
and `xbps-src` should be fully functional; just start the `bootstrap` process, i.e:
$ ./xbps-src binary-bootstrap
The default masterdir is created in the current working directory, i.e `void-packages/masterdir` .
2015-04-14 08:14:07 +02:00
2014-11-22 17:19:25 +01:00
### 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):
$ ./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:
$ ./xbps-src bootstrap-update
2015-02-08 18:19:43 +01:00
### Building 32bit packages on x86_64
2014-11-22 17:19:25 +01:00
2015-02-08 18:16:27 +01:00
Two ways are available to build 32bit packages on x86\_64:
2014-11-22 17:19:25 +01:00
2015-02-08 18:16:27 +01:00
- cross compilation mode
- native mode with a 32bit masterdir
The first mode (cross compilation) is as easy as:
2014-11-22 17:19:25 +01:00
2015-02-08 18:16:27 +01:00
$ ./xbps-src -a i686 pkg ...
2014-11-22 17:19:25 +01:00
2015-02-08 18:18:10 +01:00
The second mode (native) needs a new x86 `masterdir` :
2015-02-08 18:16:27 +01:00
$ ./xbps-src -m masterdir-x86 binary-bootstrap i686
2014-11-22 17:19:25 +01:00
$ ./xbps-src -m masterdir-x86 ...
2015-01-18 12:54:37 +01:00
### Building packages natively for the musl C library
2014-11-22 17:19:25 +01:00
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
Now cross compile `base-chroot-musl` for your native architecture:
$ ./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:
$ ./xbps-src -m masterdir-x86_64-musl binary-bootstrap x86_64-musl
Your new masterdir is now ready to build natively packages for the musl C library. Try:
$ ./xbps-src -m masterdir-x86_64-musl chroot
$ ldd
To see if the musl C dynamic linker is working as expected.
2015-04-14 11:46:59 +02:00
### Building void base-system from scratch
To rebuild all packages in `base-system` for your native architecture:
$ ./xbps-src -N pkg base-system
It's also possible to cross compile everything from scratch:
$ ./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:
# cd void-mklive
# make
# ./mklive.sh ... -r /path/to/hostdir/binpkgs
2014-09-06 12:37:09 +02:00
### Contributing
2014-12-14 22:01:41 +01:00
See [Contributing ](https://github.com/voidlinux/xbps-packages/blob/master/CONTRIBUTING.md )
for a general overview of how to contribute and the
[Manual ](https://github.com/voidlinux/xbps-packages/blob/master/Manual.md )
for details of how to create source packages.