INSTALL (7061B)
1 Build Instructions 2 ------------------ 3 4 * Requirements 5 ------------ 6 7 - A POSIX-compliant C development environment 8 - GNU make version 3.81 or later 9 - skalibs version 2.14.1.0 or later: https://skarnet.org/software/skalibs/ 10 - Recommended: execline version 2.9.4.0 or later: https://skarnet.org/software/execline/ 11 (You can disable this requirement at configure time, but will 12 lose some functionality.) 13 - Optional: nsss version 0.2.0.4 or later: https://skarnet.org/software/nsss/ 14 15 This software will run on any operating system that implements 16 POSIX.1-2008, available at: 17 https://pubs.opengroup.org/onlinepubs/9699919799/ 18 19 20 * Standard usage 21 -------------- 22 23 ./configure && make && sudo make install 24 25 will work for most users. 26 It will install the binaries in /bin and the static libraries in 27 /usr/lib/s6. 28 29 Please note that static libraries in /usr/lib/s6 *will not* 30 be found by a default linker invocation: you need -L/usr/lib/s6. 31 Other skarnet.org software automatically handles that case if the 32 default configuration is used, but if you change the configuration, 33 remember to use the appropriate --with-lib configure option. 34 35 You can strip the binaries and libraries of their extra symbols via 36 "make strip" before the "make install" phase. It will shave a few bytes 37 off them. 38 39 40 * Customization 41 ------------- 42 43 You can customize paths via flags given to configure. 44 See ./configure --help for a list of all available configure options. 45 The execline dependency can be removed with --disable-execline. 46 47 48 * Environment variables 49 --------------------- 50 51 Controlling a build process via environment variables is a big and 52 dangerous hammer. You should try and pass flags to configure instead; 53 nevertheless, a few standard environment variables are recognized. 54 55 If the CC environment variable is set, its value will override compiler 56 detection by configure. The --host=HOST option will still add a HOST- 57 prefix to the value of CC. 58 59 The values of CFLAGS, CPPFLAGS and LDFLAGS will be appended to flags 60 auto-detected by configure. To entirely override the flags set by 61 configure instead, use make variables. 62 63 64 * Make variables 65 -------------- 66 67 You can invoke make with a few variables for more configuration. 68 69 CC, CFLAGS, CPPFLAGS, LDFLAGS, LDLIBS, AR, RANLIB, STRIP, INSTALL and 70 CROSS_COMPILE can all be overridden on the make command line. This is 71 an even bigger hammer than running ./configure with environment 72 variables, so it is advised to only do this when it is the only way of 73 obtaining the behaviour you want. 74 75 DESTDIR can be given on the "make install" command line in order to 76 install to a staging directory. 77 78 79 * Shared libraries 80 ---------------- 81 82 Software from skarnet.org is small enough that shared libraries are 83 generally not worth using. Static linking is simpler and incurs less 84 runtime overhead and less points of failure: so by default, shared 85 libraries are not built and binaries are linked against the static 86 versions of the skarnet.org libraries. Nevertheless, you can: 87 * build shared libraries: --enable-shared 88 * link binaries against shared libraries: --disable-allstatic 89 90 91 * Static binaries 92 --------------- 93 94 By default, binaries are linked against static versions of all the 95 libraries they depend on, except for the libc. You can enforce 96 linking against the static libc with --enable-static-libc. 97 98 (If you are using a GNU/Linux system, be aware that the GNU libc 99 behaves badly with static linking and produces huge executables, 100 which is why it is not the default. Other libcs are better suited 101 to static linking, for instance musl: https://musl-libc.org/) 102 103 s6 includes software running at a very low level, including a 104 program that may run as process 1: to avoid run-time dependencies, 105 it is recommended that you link the executables statically if you 106 have a suitable libc. 107 108 109 * Cross-compilation 110 ----------------- 111 112 skarnet.org packages centralize all the difficulty of 113 cross-compilation in one place: skalibs. Once you have 114 cross-compiled skalibs, the rest is easy. 115 116 * Use the --host=HOST option to configure, HOST being the triplet 117 for your target. 118 * Make sure your cross-toolchain binaries (i.e. prefixed with HOST-) 119 are accessible via your PATH environment variable. 120 * Make sure to use the correct version of skalibs for your target, 121 and the correct sysdeps directory, making use of the 122 --with-include, --with-lib, --with-dynlib and --with-sysdeps 123 options as necessary. 124 125 126 * The slashpackage convention 127 --------------------------- 128 129 The slashpackage convention (http://cr.yp.to/slashpackage.html) 130 is a package installation scheme that provides a few guarantees 131 over other conventions such as the FHS, for instance fixed 132 absolute pathnames. skarnet.org packages support it: use the 133 --enable-slashpackage option to configure, or 134 --enable-slashpackage=DIR for a prefixed DIR/package tree. 135 This option will activate slashpackage support during the build 136 and set slashpackage-compatible installation directories. 137 If $package_home is the home of the package, defined as 138 DIR/package/$category/$package-$version with the variables 139 read from the package/info file, then: 140 141 --dynlibdir is set to $package_home/library.so 142 --bindir is set to $package_home/command 143 --sbindir is also set to $package_home/command (slashpackage 144 differentiates root-only binaries by their Unix rights, not their 145 location in the filesystem) 146 --libexecdir is also set to $package_home/command (slashpackage 147 does not need a specific directory for internal binaries) 148 --libdir is set to $package_home/library 149 --includedir is set to $package_home/include 150 151 --prefix is pretty much ignored when you use --enable-slashpackage. 152 You should probably not use both --enable-slashpackage and --prefix. 153 154 When using slashpackage, two additional Makefile targets are 155 available after "make install": 156 - "make update" changes the default version of the software to the 157 freshly installed one. (This is useful when you have several installed 158 versions of the same software, which slashpackage supports.) 159 - "make -L global-links" adds links from /command and /library.so to the 160 default version of the binaries and shared libraries. The "-L" option to 161 make is necessary because targets are symbolic links, and the default make 162 behaviour is to check the pointed file's timestamp and not the symlink's 163 timestamp. 164 165 166 * Absolute pathnames 167 ------------------ 168 169 You may want to use fixed absolute pathnames even if you're not 170 following the slashpackage convention: for instance, the Nix packaging 171 system prefers calling binaries with immutable paths rather than rely on 172 PATH resolution. If you are in that case, use the --enable-absolute-paths 173 option to configure. This will ensure that programs calling binaries from 174 this package will call them with their full installation path (in bindir) 175 without relying on a PATH search. 176 177 178 * Out-of-tree builds 179 ------------------ 180 181 skarnet.org packages do not support out-of-tree builds. They 182 are small, so it does not cost much to duplicate the entire 183 source tree if parallel builds are needed.