diff options
Diffstat (limited to 'doc/flags.html')
| -rw-r--r-- | doc/flags.html | 313 |
1 files changed, 313 insertions, 0 deletions
diff --git a/doc/flags.html b/doc/flags.html new file mode 100644 index 0000000..2579d5a --- /dev/null +++ b/doc/flags.html @@ -0,0 +1,313 @@ +<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> +it 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> + +<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> ↑ 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> ↑ 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> → 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> ↓ This setup is arguably not SUSv4 conformant (a strict +interpretation of Single Unix requires the system clock to be set to UTC). </li> + <li> ↓ 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> ↑ This is strictly SUSv4-compliant. Most Unix machines all over +the world are set up like this. </li> + <li> ↑ This is compatible with ntpd. </li> + <li> → You should not use Olson's time library in that case. </li> + <li> ↓ skalibs time computations will take a bit more processing power. </li> + <li> ↓ 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 the target architecture supports it. +The safe option is to let this flag clear. +</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 let this flag +clear; it should only be set to speed up the compilation process in a +known environment and 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> |