summaryrefslogtreecommitdiff
path: root/doc/flags.html
blob: a7bdab867edfb9b32d6f1f02fcd55776ce7c4cca (plain)
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
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <meta http-equiv="Content-Language" content="en" />
    <title>skalibs: configuration flags</title>
    <meta name="Description" content="skalibs: configuration flags" />
    <meta name="Keywords" content="skalibs build compilation configuration flags options" />
    <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
  </head>
<body>

<p>
<a href="index.html">skalibs</a><br />
<a href="http://skarnet.org/software/">Software</a><br />
<a href="http://skarnet.org/">skarnet.org</a>
</p>

<h1> skalibs configuration flags </h1>

<p>
 The skalibs <tt>./configure</tt> script comes with a few
uncommon options; this page explains what they are for.
</p>

<a name="slashpackage"><h3> --enable-slashpackage[=<em>sproot</em>] </h3></a>

<p>
 This flag tells configure that you want to install skalibs according to
the <a href="http://cr.yp.to/slashpackage.html">slashpackage convention</a>.
If you enable it, and $v is the version of skalibs you're compiling,
<tt>make install</tt> will install the skalibs header files in
<tt>/package/prog/skalibs-$v/include</tt>, the static libraries in
<tt>/package/prog/skalibs-$v/library</tt>, the dynamic libraries in
<tt>/package/prog/skalibs-$v/library.so</tt> and the data files in
<tt>/package/prog/skalibs-$v/etc</tt>, all prefixed by <em>sproot</em>
if present. It will also add two more "make" targets:
</p>

<ul>
 <li> <tt>make update</tt> will update the <tt>/package/prog/skalibs</tt>
symbolic link to point to <tt>skalibs-$v</tt> </li>
 <li> <tt>make -L global-links </tt> will make links from <tt>/library.so</tt>
to the installed skalibs shared libraries. </li>
</ul>

<p>
 If this option is not given, no slashpackage support will be provided.
</p>

<a name="replace-libc"><h3> --enable-libc-replacements </h3></a>

<p>
 If this option is given, then the low-level components
of <a href="libstddjb/">libstddjb</a>, such as <tt>byte_copy()</tt>,
will be built using independent, failsafe implementations; skalibs will
avoid relying on the libc when possible.
</p>

<p>
 If this option is not given, then native libc primitives such as
<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/memmove.html">memmove()</a>
will be used for the low-levels components of libstddjb. This is the default.
</p>

<p>
 This flag should be set if your libc has known bugs or you are uncertain
of it for some reason. Standard libcs on modern systems have been thoroughly
tested, so it's usually safe, and faster, to stick to the default.
</p>

<a name="clockistai"><h3> --enable-tai-clock </h3></a>

<p>
 To understand what this flag is about - and the next three flags too - you
should start by reading
<a href="http://www.madore.org/~david/computers/unix-leap-seconds.html">this
page about Unix time</a>,
which <a href="http://www.madore.org/~david/">David Madore</a> wrote after
a long and fairly complete discussion we had on the subject. You can also
read <a href="http://cr.yp.to/proto/utctai.html">what DJB says about Unix time</a>.
Unfortunately, when he says "the POSIX rules are so outrageously dumb (...)
that no self-respecting engineer would obey them", DJB is wrong: a lot of
people follow the POSIX rules. Or maybe he's right... and there are very,
very few self-respecting engineers.
</p>

<p>
 Basically, when you configure a Unix system, there are essentially two
ways to deal with your system clock.
</p>

<ol>
 <li> You can set your system clock to TAI-10, which is the "right", but
uncommon, thing to do:
  <ul>
   <li> &uarr; The main advantage of this setup is that it makes your system clock
<em>linear</em>. In other words,
<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/gettimeofday.html">gettimeofday()</a>
becomes suitable for both timestamping (which needs absolute time) and timeout
computations (which need reliable interval measurements); if your clock is
accurate enough, it can function as both a wall clock and a stopwatch.
This simplifies keeping track of the current time <strong>considerably</strong>,
and makes event loop handling (with functions such as
<a href="libstddjb/iopause.html">iopause()</a>) trivial. </li>
   <li> &uarr; skalibs uses TAI internally; setting your system clock to TAI-10
saves a lot of conversions and makes time computations with skalibs more
efficient. </li>
   <li> &rarr; In order to display GMT or local time properly, you have to
use the <tt>right/</tt> timezones from Arthur David Olson's timezone
library. If your libc does not support them, see the
<a href="#tzisright">next flag</a>. </li>
   <li> &darr; This setup is arguably not SUSv4 conformant (a strict
interpretation of Single Unix requires the system clock to be set to UTC). </li>
   <li> &darr; This setup is <em>not</em> compatible with
<a href="http://en.wikipedia.org/wiki/Ntpd">ntpd</a>. <tt>ntpd</tt>'s design
is flawed: it makes the mistake of setting the system clock itself - instead
of simply making the computed time available to other programs, one of which
could set the system clock - and it always sets it to UTC. (The
<a href="http://www.skarnet.org/software/s6-networking/">s6-networking</a>
package provides alternate ways to synchronize your clock, though.) </li>
  </ul>
 </li>
 <li> You can set your system clock to UTC, which is the common, strictly
POSIX setup:
  <ul>
   <li> &uarr; This is strictly SUSv4-compliant. Most Unix machines all over
the world are set up like this. </li>
   <li> &uarr; This is compatible with ntpd. </li>
   <li> &rarr; You should not use Olson's time library in that case. </li>
   <li> &darr; skalibs time computations will take a bit more processing power. </li>
   <li> &darr; Most importantly, you forsake all linearity - and even monotonicity
- on your system clock, which can now only be used as a wall clock,
<em>not</em> as a stopwatch. skalibs will try its best to do accurate time
computations, but there's no way <tt>gettimeofday()</tt> can be relied on
when a leap second is nearby; you have to use CLOCK_MONOTONIC as a stopwatch
for accurate interval measurement. </li>
  </ul>
 </li>
</ol>

<p>
 Use <tt>--enable-tai-clock</tt> if your system clock is set to TAI-10.
I generally recommend this setup
for computers you have full control on, on which you install and tweak
the software your way, like manually administered servers or embedded
boxes. If you do not run ntpd and do not mind breaking POSIX, it is the
sensible choice.
</p>

<p>
 Do not use this option if your system clock is set to UTC, i.e. if
you're in none of the above cases: you are a
POSIX freak, or your Unix distribution is running ntpd for you, or
other software is assuming you're on UTC. This is the default.
</p>


<a name="tzisright"><h3> --enable-right-tz </h3>

<p>
 This option instructs skalibs that you're using Olson's time
library, i.e. "right/" timezones.
</p>

<p>
 Normally, if you set <a href="#clockistai">--enable-tai-clock</a>, you
<em>should</em> also set up your timezone to a "right/" one, and
set <tt>flag-tzisright</tt>. And if you don't use
<a href="#clockistai">--enable-tai-clock</a>, you should also use a POSIX
timezone, and NOT use <tt>--enable-right-tz</tt>. Those two options
should always be used together.
</p>

<p>
 <em>But</em> some C libraries do not support the Olson time library's
timezone format, and just do not provide the "right/" timezones! For
instance, <a href="http://musl-libc.org/">musl</a>,
an alternative libc for Linux, only supports POSIX timezones. And you
might want to use such a libc, and <em>still</em> set up your clock to
TAI-10, for instance in embedded environments where accurate timekeeping
is important. In such cases, you'll set up a POSIX timezone, and use the
<tt>--enable-tai-clock</tt> option without the <tt>--enable-right-tz</tt> one.
</p>

<p>
 Be aware that setting your system clock to TAI-10 without having a
"right/" timezone will cause non-skalibs-using software to display
local time incorrectly; in such a setup, only skalibs-using software
will understand what is going on and do the proper computations to
display the correct local time. Keep your settings as consistent as
possible.
</p>

<p>
 By default, skalibs will consider you are using POSIX timezones (as well
as a UTC system clock).
</p>

<a name="usert"><h3> --enable-clock </h3></a>

<p>
 The Open Group Base Specifications, issue 7, describes <tt>gettimeofday()</tt>
as obsolescent, and recommends the use of
<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_gettime.html">clock_gettime()</a>
with the CLOCK_REALTIME option instead. However:
</p>

<ul>
 <li> <tt>clock_gettime()</tt> is not as portable; for instance, Darwin does not have it. </li>
 <li> On most systems, using the <tt>clock_</tt> functions requires linking with <tt>librt</tt>,
which is slightly inconvenient - and silly if all you want is timestamping.
</ul>

<p>
 If <tt>--enable-clock</tt> is set, the <a href="libstddjb/tai.html">tain_now()
and tain_setnow()</a> functions for getting and setting time will be based on
the <tt>clock_gettime()</tt> and <tt>clock_settime()</tt> functions.
</p>

<p>
 Otherwise, the old-school <tt>gettimeofday()</tt>
and <tt>settimeofday()</tt> interfaces will be used. This is the default,
and it's usually safe.
</p>

<a name="usemon"><h3> --enable-monotonic </h3></a>

<p>
 Unless you have an accurate hardware system clock <em>and</em> you set it
on a linear time scale such as TAI-10 instead of UTC (see above), it is
generally a bad idea to trust the system clock for precise time interval
measurements. Single Unix recommends the use of <tt>clock_gettime()</tt>
with the CLOCK_MONOTONIC option to do such measurements: a stopwatch, not
a wall clock. However:
</p>

<ul>
 <li> CLOCK_MONOTONIC is even less portable than CLOCK_REALTIME. </li>
 <li> It's a bit tricky to emulate absolute time calculations based on
CLOCK_MONOTONIC. </li>
</ul>

<p>
 If <tt>--enable-monotonic</tt> is set, then the absolute time given by the
<tt>tain_now()</tt> call will be computed with CLOCK_MONOTONIC. This
will ensure precise time arithmetic but may drift away from the system
clock.
</p>

<p>
 Otherwise, <tt>tain_now()</tt> will
return a time based on the system clock, and not use CLOCK_MONOTONIC.
This is the default.
</p>

<a name="noipv6"><h3> --disable-ipv6 </h3></a>

<p>
 If you set this option, then skalibs will be compiled without IPv6 support,
even if your target architecture supports it. This can significantly
reduce the size of your networking applications if they don't need IPv6
support.
</p>

<p>
 If you don't set this option, then skalibs will include IPv6 support in the
relevant networking functions if and only if the target architecture supports it.
This is the default, and it is safe.
</p>

<a name="forcedevr"><h3> --enable-force-devr </h3></a>

<p>
 If this option is set, then the automatic sysdeps tests will assume the
target architecture has a working <tt>/dev/random</tt> and will skip
its autodetection.
</p>

<p>
 Otherwise, <tt>/dev/random</tt> will be autodetected
and tested; if entropy generation is low on the host, the compilation
process might hang for several minutes. It is safe to leave this flag
clear; it should only be set to speed up the compilation process in a
known environment or for testing purposes.
</p>

<p>
 If skalibs is being cross-compiled, this flag obviously has no effect:
the presence of a working <tt>/dev/random</tt> is read from the user-provided
sysdeps.
</p>

<a name="forcedevr"><h3> --enable-egd=<em>path</em> </h3></a>

<p>
 If you set this option, then the <a href="librandom/">librandom</a> functions
will assume the presence of an EGD daemon listening on <em>path</em>,
and use it to get random data.
</p>

<p>
 By default, skalibs will not include EGD support.
</p>

<a name="defaultpath"><h3> --with-default-path=<em>path</em> </h3></a>

<p>
 The <a href="libstddjb/djbunix.html">execvep()</a> function uses
the value of the PATH environment variable as its executable search path.
Specifying this option to configure tells execvep() what executable
search path to use when PATH is undefined (which should not happen
often anyway).
 The default is <tt>/usr/bin:/bin</tt>, which is usually safe.
</p>

</body>
</html>