From 3534b428629be185e096be99e3bd5fdfe32d5544 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Thu, 18 Sep 2014 18:55:44 +0000 Subject: initial commit with rc for skalibs-2.0.0.0 --- doc/flags.html | 313 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 313 insertions(+) create mode 100644 doc/flags.html (limited to 'doc/flags.html') 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 @@ + + + + + skalibs: configuration flags + + + + + + +

+skalibs
+Software
+skarnet.org +

+ +

skalibs configuration flags

+ +

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

+ +

--enable-slashpackage[=sproot]

+ +

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

+ +

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

+ +

--enable-libc-replacements

+ +

+ If this option is given, then the low-level components +of libstddjb, such as byte_copy(), +will be built using independent, failsafe implementations; skalibs will +avoid relying on the libc when possible. +

+ +

+ If this option is not given, then native libc primitives such as +memmove() +will be used for the low-levels components of libstddjb. This is the default. +

+ +

+ 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. +

+ +

--enable-tai-clock

+ +

+ To understand what this flag is about - and the next three flags too - you +should start by reading +this +page about Unix time, +which David Madore wrote after +a long and fairly complete discussion we had on the subject. You can also +read what DJB says about Unix time. +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. +

+ +

+ Basically, when you configure a Unix system, there are essentially two +ways to deal with your system clock. +

+ +

You can set your system clock to TAI-10, which is the "right", but +uncommon, thing to do: +
- ↑ The main advantage of this setup is that it makes your system clock +linear. In other words, +gettimeofday() +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 considerably, +and makes event loop handling (with functions such as +iopause()) trivial.
- ↑ skalibs uses TAI internally; setting your system clock to TAI-10 +saves a lot of conversions and makes time computations with skalibs more +efficient.
- → In order to display GMT or local time properly, you have to +use the right/ timezones from Arthur David Olson's timezone +library. If your libc does not support them, see the +next flag.
- ↓ This setup is arguably not SUSv4 conformant (a strict +interpretation of Single Unix requires the system clock to be set to UTC).
- ↓ This setup is not compatible with +ntpd. ntpd'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 +s6-networking +package provides alternate ways to synchronize your clock, though.)
+
You can set your system clock to UTC, which is the common, strictly +POSIX setup: +
- ↑ This is strictly SUSv4-compliant. Most Unix machines all over +the world are set up like this.
- ↑ This is compatible with ntpd.
- → You should not use Olson's time library in that case.
- ↓ skalibs time computations will take a bit more processing power.
- ↓ Most importantly, you forsake all linearity - and even monotonicity +- on your system clock, which can now only be used as a wall clock, +not as a stopwatch. skalibs will try its best to do accurate time +computations, but there's no way gettimeofday() can be relied on +when a leap second is nearby; you have to use CLOCK_MONOTONIC as a stopwatch +for accurate interval measurement.
+

+ +

+ USe --enable-tai-clock 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. +

+ +

+ 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. +

+ + +

--enable-right-tz

+ +

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

+ +

+ Normally, if you set --enable-tai-clock, you +should also set up your timezone to a "right/" one, and +set flag-tzisright. And if you don't use +--enable-tai-clock, you should also use a POSIX +timezone, and NOT use --enable-right-tz. Those two options +should always be used together. +

+ +

+ But some C libraries do not support the Olson time library's +timezone format, and just do not provide the "right/" timezones! For +instance, musl, +an alternative libc for Linux, only supports POSIX timezones. And you +might want to use such a libc, and still 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 +--enable-tai-clock option without the --enable-right-tz one. +

+ +

+ 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. +

+ +

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

+ +

--enable-clock

+ +

+ The Open Group Base Specifications, issue 7, describes gettimeofday() +as obsolescent, and recommends the use of +clock_gettime() +with the CLOCK_REALTIME option instead. However: +

+ +

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

+ +

+ If --enable-clock is set, the tain_now() +and tain_setnow() functions for getting and setting time will be based on +the clock_gettime() and clock_settime() functions. +

+ +

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

+ +

--enable-monotonic

+ +

+ Unless you have an accurate hardware system clock and 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 clock_gettime() +with the CLOCK_MONOTONIC option to do such measurements: a stopwatch, not +a wall clock. However: +

+ +

CLOCK_MONOTONIC is even less portable than CLOCK_REALTIME.
It's a bit tricky to emulate absolute time calculations based on +CLOCK_MONOTONIC.

+ +

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

+ +

+ Otherwise, tain_now() will +return a time based on the system clock, and not use CLOCK_MONOTONIC. +This is the default. +

+ +

--disable-ipv6

+ +

+ 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. +

+ +

+ 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. +

+ +

--enable-force-devr

+ +

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

+ +

+ Otherwise, /dev/random 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. +

+ +

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

+ +

--enable-egd=path

+ +

+ If you set this option, then the librandom functions +will assume the presence of an EGD daemon listening on path, +and use it to get random data. +

+ +

+ By default, skalibs will not include EGD support. +

+ +

--with-default-path=path

+ +

+ The execvep() 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 /usr/bin:/bin, which is usually safe. +

+ + + -- cgit v1.2.3