D 2020-03-04T23:09:10.810
L build
N text/x-markdown
P ac38dbce48470464c31572e6f10d4fa18b45bba9e2dce004896addb177d3c003
U lexi
W 8402
# building and packaging
libk can be built manually from source, but this is mostly only useful for development work and debugging. most users will want to use a script for their distro's build system to automatically download, verify (for releases), and package libk for installation. if your distro is not currently supported, you will need to package it manually.
## automatic packaging
libk provides two kinds of tarball: release tarballs and "live" tarballs. the live tarball is simply the current state of the "trunk" branch, and can be downloaded at the [libk download page](/download). however, you will most likely want to package libk, rather than installing it directly to your system. below are direct links to the official live and release packaging scripts for the distributions whose build systems we currently support. the packaging scripts for the live build are bundled in the [dist/](/dir?ci=tip&name=dist) directory of the repository, and are used as the basis for the release build scripts, which are uploaded separately elsewhere. if you would like to add support for another distribution, we welcome your merge requests, and urge you to join the maintenance effort for your distro to help us ensure stable releases.
please note that the live package script does not and cannot verify checksums or signatures on the source package! if you need such guarantees, you should use the most recent release available for your distro instead.
<table>
<tr style="background:#881142">
<th style="width:30%">distro</th>
<th style="text-align:center; width: 15%">live build</th>
<th style="text-align:left">release builds</th>
</tr>
<tr>
<td style="text-align:right;font-weight:bold"><a href="https://archlinux.org">Arch Linux</a></td>
<td style="text-align:center"><a href="doc/tip/dist/PKGBUILD">PKGBUILD</a></td>
<td><em>(no releases)</em></td>
</tr>
<tr>
<td style="text-align:right;font-weight:bold"><a href="https://nixos.org">NixOS</a></td>
<td style="text-align:center"><a href="doc/tip/dist/libk.nix">libk.nix</a>*</td>
<td><em>(no releases)</em></td>
</tr>
</table>
<small>scripts marked with * must be run from within the tarball. all others will download the necessary source files automatically.</small>
at this time, libk does not provide any official project binaries. however, in the future, we plan to make use of the OpenSUSE Open Build System service to provide binary packages for a wide variety of distributions and architectures, for both the live build and most recent release.
## manual packaging
libk is designed to be as easy to package as possible. a packaging script only needs to perform five tasks:
1. **download sources**. the script should fetch the appropriate source tarball (`https://c.comint.su/libk/tarball/trunk/libk.tar.gz` for the live package; an official release tarball and its accompanying signature otherwise). it should not clone the libk fossil repository; fossil should not be a libk makedepend. release tarballs will always end in `.txz`; the name of the signature file will be the stem of the tarball it certifies followed by the `.sig` suffix.
2. *(release tarball only)* **verify sources**. before extracting the sources, the script should use PGP to verify the tarball signature against the [project keyring](/wiki?name=keyring). for instance, the command `$ gpgv --keyring libk.asc libk-1.0.sig libk-1.0.txz` might be used to verify the 1.0 release tarball of libk against its signature file. if at all possible, the fingerprints of the keys in the keyring should be included as part of the build script rather than downloaded on demand from the live copy of the keyring, unless your build system offers a more secure verification method. if you do download the keyring on demand, make sure to verify it against the maintainer key.
3. **extract sources**. the release tarballs are compressed with `xz`; due to technical limitations inherent in fossil, the live tarballs use gzip instead.
4. **build libk**. the script should set the appropriate environment variables, chdir to the newly extracted source directory, and invoke `./build.sh`. if the `cmark` utility is not available on the system at the time of the build, the `$doc` environment variable should be set to `no` to suppress documentation generation. the variables controlling the build target should be set (or auto-detected, if necessary) at this point. see **building from source** for a full explanation of this step.
5. **install libk into the package root**. libk comes with an `install.sh` script to automate installation. normally, this can be invoked as simply as `env prefix=$pkgdir/usr ./install.sh`, but you may need to set a number of other variables depending on the nature of the build system and distribution you are building for. see **building from source** for a full explanation of how to invoke `install.sh`.
if you have written a build script for a distro we do not currently support, and are willing to be responsible for maintaining it, please send a merge request to incorporate the build script into the libk source tree.
## building from source
if you intend to build libk by hand, it may be helpful to install fossil and clone the repository directly, so that you can update and rebuild the software without re-downloading tarballs. however, if you want to use a stable release, you should first download the [project keyring](/wiki?name=keyring) and cache the keys in a local PGP keyring. (at some point, we will provide tooling to perform authenticated updates for the local copies of the project keyring and maintainer key, but for now, this step needs to be done manually.) this way, whenever you download a release, you can verify that it has been signed by the appropriate personnel.
once you've downloaded and extracted the package, you can begin compilation. libk does not use make, meson, or any other standalone build system; it comes with a bash script `build.sh` that performs all tasks necessary to compile the project. all you need to do is set the parameters of the build, so that `build.sh` knows what platform to build for. the [libk manifesto](/doc/tip/libk.md) explains this step in full, but for example, to build both the static and shared libk libraries on x86-64 Linux without compiling the documentation, one would execute the command:
$ env os=lin arch=x86 bits=64 doc=no library=both ./build.sh
assuming your build is successful, you will then need to use the `install.sh` script to copy all files into their appropriate place on your system. `install.sh` recognizes the following environment variables:
- `$prefix`: the base directory of the install
- `$build`: the path to the directory containing the files built during the compilation step. you will always need to set this if you are not chdir'ing to the directory that contains `install.sh` first (default: `./out`)
- `$bindir`: the directory executable binaries will be installed into (default: `$prefix/bin`) - `$libdir`: the directory static and shared libraries will be installed into (default: `$prefix/lib`)
- `$sharedir`: the directory that share files, such as manpages and pdf documentation, will be installed into (default: `$prefix/share`)
- `$incdir`: the directory that header files for software that builds against libk will be installed into (default: `$prefix/include/k`)
so to install system-wide (not recommended; you should build a package for this instead) on a modern linux system, you could use the command
# env prefix=/usr ./install.sh
alternatively, if you just want to link your own personal projects statically against libk without installing it systemwide, you might do something the following:
$ libkdir=$HOME/dev/libs/libk
$ env bindir=$libkdir libdir=$libkdir sharedir=$libkdir incdir=$libkdir/k ./install.sh
$ export MANPATH=$(manpath):$libkdir/man #makes it possible to look up libk modules with the man(1) command
$ cc -I$libkdir my-proj.c $libkdir/libk.a #allows compiling with the standard #include <k/mod.h> directive
or a systemwide package-specific namespace:
# env prefix=/opt/libk ./install.sh
libk does not hardcode any paths to any file contained in the package, so once built or installed, it can be moved about at will without recompiling anything.
Z 01517ccb71655f5248d0e17a2f84eac7