-
Notifications
You must be signed in to change notification settings - Fork 5
/
INSTALL
227 lines (174 loc) · 9.13 KB
/
INSTALL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
Build Instructions
------------------
* Requirements
------------
- A POSIX-compliant C development environment
- GNU make version 3.81 or later
- skalibs version 2.14.3.0 or later: https://skarnet.org/software/skalibs/
- Optional (but recommended): execline version 2.9.6.1 or later: https://skarnet.org/software/execline/
- s6 version 2.13.1.0 or later: https://skarnet.org/software/s6/
- s6-dns version 2.4.0.0 or later: https://skarnet.org/software/s6-dns/
- Depending on whether you build the SSL tools,
bearssl version 0.6 or later: https://bearssl.org/
or libressl version 3.9.2 or later: https://libressl.org/
or openssl version 3.3.1 or later: https://openssl.org/ *in addition to*
libretls version 3.8.1 or later: https://git.causal.agency/libretls/about/
This software will run on any operating system that implements
POSIX.1-2008, available at:
https://pubs.opengroup.org/onlinepubs/9699919799/
* Standard usage
--------------
./configure && make && sudo make install
will work for most users.
It will install the binaries in /bin and the static libraries in /usr/lib.
You can strip the binaries and libraries of their extra symbols via
"make strip" before the "make install" phase. It will shave a few bytes
off them.
* Customization
-------------
You can customize paths via flags given to configure.
See ./configure --help for a list of all available configure options.
* Environment variables
---------------------
Controlling a build process via environment variables is a big and
dangerous hammer. You should try and pass flags to configure instead;
nevertheless, a few standard environment variables are recognized.
If the CC environment variable is set, its value will override compiler
detection by configure. The --host=HOST option will still add a HOST-
prefix to the value of CC.
The values of CFLAGS, CPPFLAGS and LDFLAGS will be appended to flags
auto-detected by configure. To entirely override the flags set by
configure instead, use make variables.
* Make variables
--------------
You can invoke make with a few variables for more configuration.
CC, CFLAGS, CPPFLAGS, LDFLAGS, LDLIBS, AR, RANLIB, STRIP, INSTALL and
CROSS_COMPILE can all be overridden on the make command line. This is
an even bigger hammer than running ./configure with environment
variables, so it is advised to only do this when it is the only way of
obtaining the behaviour you want.
DESTDIR can be given on the "make install" command line in order to
install to a staging directory.
* Shared libraries
----------------
Software from skarnet.org is small enough that shared libraries are
generally not worth using. Static linking is simpler and incurs less
runtime overhead and less points of failure: so by default, shared
libraries are not built and binaries are linked against the static
versions of the skarnet.org libraries. Nevertheless, you can:
* build shared libraries: --enable-shared
* link binaries against shared libraries: --disable-allstatic
* Static binaries
---------------
By default, binaries are linked against static versions of all the
libraries they depend on, except for the libc. You can enforce
linking against the static libc with --enable-static-libc.
(If you are using a GNU/Linux system, be aware that the GNU libc
behaves badly with static linking and produces huge executables,
which is why it is not the default. Other libcs are better suited
to static linking, for instance musl: https://musl-libc.org/)
* Cross-compilation
-----------------
skarnet.org packages centralize all the difficulty of
cross-compilation in one place: skalibs. Once you have
cross-compiled skalibs, the rest is easy.
* Use the --host=HOST option to configure, HOST being the triplet
for your target.
* Make sure your cross-toolchain binaries (i.e. prefixed with HOST-)
are accessible via your PATH environment variable.
* Make sure to use the correct version of skalibs for your target,
and the correct sysdeps directory, making use of the
--with-include, --with-lib, --with-dynlib and --with-sysdeps
options as necessary.
* The slashpackage convention
---------------------------
The slashpackage convention (http://cr.yp.to/slashpackage.html)
is a package installation scheme that provides a few guarantees
over other conventions such as the FHS, for instance fixed
absolute pathnames. skarnet.org packages support it: use the
--enable-slashpackage option to configure, or
--enable-slashpackage=DIR for a prefixed DIR/package tree.
This option will activate slashpackage support during the build
and set slashpackage-compatible installation directories.
If $package_home is the home of the package, defined as
DIR/package/$category/$package-$version with the variables
read from the package/info file, then:
--dynlibdir is set to $package_home/library.so
--bindir is set to $package_home/command
--sbindir is also set to $package_home/command (slashpackage
differentiates root-only binaries by their Unix rights, not their
location in the filesystem)
--libexecdir is also set to $package_home/command (slashpackage
does not need a specific directory for internal binaries)
--libdir is set to $package_home/library
--includedir is set to $package_home/include
--prefix is pretty much ignored when you use --enable-slashpackage.
You should probably not use both --enable-slashpackage and --prefix.
When using slashpackage, two additional Makefile targets are
available after "make install":
- "make update" changes the default version of the software to the
freshly installed one. (This is useful when you have several installed
versions of the same software, which slashpackage supports.)
- "make -L global-links" adds links from /command and /library.so to the
default version of the binaries and shared libraries. The "-L" option to
make is necessary because targets are symbolic links, and the default make
behaviour is to check the pointed file's timestamp and not the symlink's
timestamp.
* Absolute pathnames
------------------
You may want to use fixed absolute pathnames even if you're not
following the slashpackage convention: for instance, the Nix packaging
system prefers calling binaries with immutable paths rather than rely on
PATH resolution. If you are in that case, use the --enable-absolute-paths
option to configure. This will ensure that programs calling binaries from
this package will call them with their full installation path (in bindir)
without relying on a PATH search.
* Out-of-tree builds
------------------
skarnet.org packages do not support out-of-tree builds. They
are small, so it does not cost much to duplicate the entire
source tree if parallel builds are needed.
* SSL support
-----------
s6-networking implements UCSPI tools for SSL/TLS connections: see the
doc/tls-overview.html page for a listing of these tools and what they do.
The TLS tools are built if you give the --enable-ssl=<implementation>
flag to configure. There are two supported values for <implementation>:
bearssl and libtls. You should install the relevant header and library
files for your chosen implementation before building a SSL-enabled
s6-networking.
"bearssl" uses the BearSSL API, of which there's only one implementation,
from bearssl.org.
"libtls" uses the libtls API, which has two possible implementations:
- The original one, from libressl.org, bundled with LibreSSL
- An alternative one, from causal.agency, that is used on top of
OpenSSL.
For compatibility, "libressl" is accepted as <implementation> and is
an alias to libtls.
If your SSL headers and library files are not installed in /usr/include
and /usr/lib, you can use the --with-ssl-path=DIR configure option:
headers will be searched in DIR/include and libraries will be searched in
DIR/lib. For more complex setups, use the generic --with-include and
--with-dir configure options.
If you choose --enable-ssl=bearssl, then s6-networking will build a
"libsbearssl" support library, which s6-tlsc-io and s6-tlsd-io will be
linked against. This support library depends on libbearssl interfaces.
If you choose --enable-ssl=libtls, then s6-networking will build a
"libstls" support library, which s6-tlsc-io and s6-tlsd-io will be
linked against. This support library depends on libtls interfaces, but
not on libssl or libcrypto interfaces, so it is possible to use other
alternative implementations of the libtls API. There is one such
implementation: libtls-bearssl, implementing libtls on top of bearssl,
but using it with s6-networking is a waste since s6-networking supports
bearssl natively.
If your SSL implementation library needs nonstandard -l options to link
against it, you can override the CRYPTO_LIB make variable.
By default, CRYPTO_LIB is "-lbearssl" when building against bearssl,
and "-ltls -lssl -lcrypto" when building against libtls.
As of 2020-11-30, please note that BearSSL is considered beta quality
by its author, so use with caution. Nevertheless, it's an incredibly
good beta, with high-quality interfaces and implementation, and no
known serious bugs.
When statically linked against BearSSL, the s6-tlsc-io and s6-tlsd-io
binaries are 1/10th the size of what they are when statically linked
against libressl/openssl, with a much smaller RAM footprint too.