INSTALL (7125B)
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 - If cross-compiling: you have to know the correct value for some 10 non-autodetectable sysdeps for your target architecture. See the 11 "Cross-compilation" section below. 12 13 This software will install on any operating system that implements 14 POSIX.1-2008, available at: 15 https://pubs.opengroup.org/onlinepubs/9699919799/ 16 17 18 * Standard usage 19 -------------- 20 21 ./configure && make && sudo make install 22 23 will work for most users. 24 It will install the static libraries in /usr/lib/skalibs, the shared 25 libraries in /lib, and the sysdeps in /usr/lib/skalibs/sysdeps. 26 27 Please note that static libraries in /usr/lib/skalibs *will not* 28 be found by a default linker invocation: you need -L/usr/lib/skalibs. 29 Other skarnet.org software automatically handles that case if the 30 default configuration is used, but if you change the configuration, 31 remember to use the appropriate --with-lib configure option. 32 33 You can strip the libraries of their extra symbols via "make strip" 34 before the "make install" phase. It will shave a few bytes off them. 35 36 37 * Customization 38 ------------- 39 40 You can customize the installation process via flags given to configure. 41 See ./configure --help for a list of all available configure options. 42 43 44 * Environment variables 45 --------------------- 46 47 Controlling a build process via environment variables is a big and 48 dangerous hammer. You should try and pass flags to configure instead; 49 nevertheless, a few standard environment variables are recognized. 50 51 If the CC environment variable is set, its value will override compiler 52 detection by configure. The --host=HOST option will still add a HOST- 53 prefix to the value of CC. 54 55 The values of CFLAGS, CPPFLAGS and LDFLAGS will be appended to the 56 default flags set by configure. To override those defaults instead 57 of appending to them, use the CPPFLAGS, CFLAGS and LDFLAGS 58 _make variables_ instead of environment variables. 59 60 61 * Make variables 62 -------------- 63 64 You can invoke make with a few variables for more configuration. 65 66 CC, CFLAGS, CPPFLAGS, LDFLAGS, LDLIBS, AR, RANLIB, STRIP, INSTALL and 67 CROSS_COMPILE can all be overridden on the make command line. This is 68 an even bigger hammer than running ./configure with environment 69 variables, so it is advised to only do this when it is the only way of 70 obtaining the behaviour you want. 71 72 DESTDIR can be given on the "make install" command line in order to 73 install to a staging directory. 74 75 76 * Shared libraries 77 ---------------- 78 79 Software from skarnet.org is small enough that shared libraries are 80 generally not worth using. Static linking is simpler and incurs less 81 runtime overhead and less points of failure: but since skalibs only 82 provides libraries, both versions are built by default. 83 Nevertheless, you can: 84 * avoid building shared libraries: --disable-shared 85 * avoid building static libraries: --disable-static 86 87 If you are using a GNU/Linux system, be aware that the GNU libc 88 behaves badly with static linking and produces huge executables, 89 so if you plan on making static executables, you should consider 90 using another libc, which you also need to use when compiling 91 skalibs. musl is recommended: http://musl-libc.org/ 92 93 94 * Cross-compilation 95 ----------------- 96 97 skarnet.org centralizes all the difficulty of cross-compilation 98 in skalibs. 99 The native skalibs build process runs some tests to gather "sysdeps", 100 i.e. system-dependent properties of the target, and stores those 101 into a sysdeps directory; software depending on skalibs is provided 102 the name of the sysdeps directory at build time, and can depend on 103 its contents - that's how skarnet.org packages are easily made 104 portable. 105 However, when the host differs from the target - the cross-compilation 106 case - some of those build-time tests, i.e. the ones that require 107 code execution on the target, are invalid. So you must manually 108 provide configure with appropriate values for the list of sysdeps that 109 cannot be autodetected. 110 For a sysdep named K with a value V, the correct option to give to 111 configure is: --with-sysdep-K=V 112 Most of the time, sysdeps have a boolean value, so the correct V is 113 "yes" or "no". 114 For instance, to say that the target has a working pseudorandom 115 number generator in /dev/urandom, you would give the following 116 option to configure: --with-sysdep-devurandom=yes 117 If there are additional arguments to the sysdep, such as linker 118 flags, give them separated by commas. Example: 119 --with-sysdep-posixspawn=yes,-lrt 120 121 ./configure --help lists all the sysdeps you need to manually 122 provide a value for when cross-compiling. 123 124 Note that you can provide manual sysdeps values at any time, 125 for any existing sysdep, to bypass autodetection - and you can 126 even do it when building natively. It's just not recommended 127 (you should let skalibs autodetect everything it can), and 128 and it's only mandatory for a small subset of sysdeps in the 129 cross-compilation case. 130 131 132 * The slashpackage convention 133 --------------------------- 134 135 The slashpackage convention (http://cr.yp.to/slashpackage.html) 136 is a package installation scheme that provides a few guarantees 137 over other conventions such as the FHS, for instance fixed 138 absolute pathnames. skarnet.org packages support it: use the 139 --enable-slashpackage option to configure, or 140 --enable-slashpackage=DIR for a prefixed DIR/package tree. 141 This option will activate slashpackage support during the build 142 and set slashpackage-compatible installation directories. If 143 $version is the current skalibs version number: 144 145 --bindir will be set to /package/prog/skalibs-$version/command 146 --includedir will be set to /package/prog/skalibs-$version/include 147 --libdir will be set to /package/prog/skalibs-$version/library 148 --dynlibdir will be set to /package/prog/skalibs-$version/library.so 149 --sysdepdir will be set to /package/prog/skalibs-$version/sysdeps 150 151 Note that --datadir will be unchanged, because the data exported 152 by skalibs, i.e. the leap second table, is system-wide. You should 153 manually specify --datadir=... if you want to deviate from the default. 154 155 --prefix is pretty much ignored when you use --enable-slashpackage: 156 it will only impact --datadir. You should probably not use both 157 --enable-slashpackage and --prefix. 158 159 When using slashpackage, two additional Makefile targets are 160 available after "make install": 161 - "make -L update" changes the default version of the software to the 162 freshly installed one. (This is useful when you have several installed 163 versions of the same software, which slashpackage supports.) 164 - "make -L global-links" adds links from DIR/command and DIR/library.so 165 to the default version of the binaries and shared libraries. 166 The "-L" option to make is necessary because targets are symbolic links, 167 and the default make behaviour is to check the pointed file's timestamp 168 and not the symlink's timestamp. 169 170 171 * Out-of-tree builds 172 ------------------ 173 174 skarnet.org packages do not support out-of-tree builds. They 175 are small, so it does not cost much to duplicate the entire 176 source tree if parallel builds are needed.