1 I n s t a l l i n g S - n a i l
2 ================================
5 1.1 What if configuration fails?
6 1.2 What if building fails?
7 1.3 How can i enable debugging?
8 2. Special notes for the latest release
9 3. Current codebase state
14 System specific notes can be found in the next section.
15 All (optional) features are documented (and adjustable) in "make.rc".
16 Adjustments may also take place, and are usually done, from the command
17 line, overriding those made in "make.rc" (if any).
18 Without any adjustments all possible features which are not in
19 experimental state will be enabled but not "require"d, so that
20 configuration won't fail shall any of them not be usable due to the
21 given system environment.
23 $ make tangerine # equals "$ make config build test install"
24 $ make distclean # *Completely* cleanup working directory
28 $ make WANT_POP3=no WANT_SMTP=require tangerine
29 $ make WANT_READLINE=true PREFIX=/some/nasty/prefix tangerine
31 With utility program and feature adjustments:
33 $ make awk=/usr/bin/nawk WANT_SOCKETS=no DESTDIR=./zzz tangerine
35 If WANT_DOTLOCK has been enabled then the minimal privilege-separated
36 SETUID (to PRIVSEP_USER, default "root") helper program will be build
37 and installed, and therefore the installation process needs to have the
38 appropriate privileges. In this case it may be useful to separate the
39 configuration / building and the installation tasks and give the last
40 step higher privileges via super(1), sudo(1), su(1) or a similar
43 $ make PREFIX=/usr config && make -j 4 &&
44 super make DESTDIR=./xy install
46 would create a "s-nail" binary and install a "s-nail" manual etc. under
47 the prefix "/usr" but rooted under "[./]xy", i.e., the binary would be
48 installed as "[./]xy/usr/bin/s-nail".
49 The following make(1) targets exists, the default being `build':
51 - tangerine Shorthand for "$ make config build test install":
52 create or check and update configuration, build, test and
54 The variable $DESTDIR will be honoured (see "make.rc"),
55 but not be tracked in the configuration.
56 In order to parallelize the `build' step pass a $MAILJOBS
57 variable, as shown below.
58 - all Shorthand for "$ make config build".
60 - config Only create or check and update the configuration.
61 - build Only build (using the existing configuration).
62 This can be parallelized, either by a corresponding make(1)
63 invocation when the target is run by itself, or by setting
64 the $MAILJOBS variable otherwise, e.g., "MAILJOBS='-j 4'".
65 $MAILJOBS is not tracked in the configuration.
66 - install Only install using the built files of the existing
68 The variable $DESTDIR will be honoured (see "make.rc"),
69 but not be tracked in the configuration.
71 - clean Remove anything which can be rebuild.
72 - distclean Remove anything which can be rebuild or reconfigured.
74 - test Run "cc-test.sh" in --check-only mode on the built binary.
76 Setting the make(1) variable $VERBOSE to an arbitrary value, as in
77 "$ make VERBOSE=xy tangerine", will change the output of the `all',
78 `install' etc. targets to a different, more verbose one.
79 If some libraries are missing that you know are installed on your
80 system, or if other errors occur due to missing files but which you know
81 exist, please ensure that the environment variable $C_INCLUDE_PATH
82 includes the necessary "include/" paths and the environment variable
83 $LD_LIBRARY_PATH includes the necessary "lib/"rary paths.
85 The S-nail make system will inspect these two environment variables and
86 *automatically* convert them to cc(1) (c99(1)) -I and -L options (since
87 these environment variables are, different to the command line options,
88 not part of the POSIX standard).
89 To set these environment variables, the following can be done in
90 a Bourne / Korn / POSIX compatible shell:
92 $ C_INCLUDE_PATH="${C_INCLUDE_PATH}:/usr/local/include"
93 $ LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib"
94 $ export C_INCLUDE_PATH LD_LIBRARY_PATH
97 The S-nail make system will also automatically integrate pkgsrc(7) paths
98 into this mechanism. (pkgsrc(7) is a portable package management system
99 that is used as a default on diverse operating systems.)
100 And if all else fails you can also forcefully pass in include directives
101 and library paths by passing prefilled $INCS and $LIBS variables:
103 $ make INCS=-I/mypath/lib LIBS=-l/mypath/iconv tangerine
105 Note there are also some predefined configuration sets available, ment
106 to be used instead of doing manual adjustments (in "make.rc" or) on the
107 command line (names are case-insensitive):
109 - CONFIG=NULL, CONFIG=NULLI
110 Anything that can be turned off is off. MIME can't.
111 The latter adds and "require"s iconv(3), though.
114 This is the most plain mailx(1)-alike mode, but with MIME support and
115 (if available) character set conversion and regular expressions
116 builtin. Dotlock files and the privileged separated dotlock helper.
118 "Require"s dotlocking and the privileged separated dotlock helper.
121 Possibly what people want who need nothing but a MIME-capable mailx(1)
122 and don't regret improved usability for the rare interactive use
125 Like MINIMAL, but with documentation strings, the builtin line editor
126 (MLE) with history support (if possible), error tracking, basic colour
127 support and IDNA addresses.
129 "Require"s iconv(3), dotlocking and the privileged separated dotlock
133 Sending messages directly to the mail provider via the SMTP protocol,
134 instead of requiring a local mail-transfer-agent (MTA) who does.
136 Adds SSL/TLS, GSSAPI and .netrc file parsing on top of MEDIUM, on the
137 other hand spam filter support is removed.
139 "Require"s iconv(3), SSL/TLS, SMTP (sockets), dotlocking and the
140 privileged separated dotlock helper.
143 Anything on, including experimental features.
144 S-nail(1) gains mail fetching capabilities and heads more towards
145 being a full-featured mail-user-agent (MUA) with this configuration.
147 "Require"s iconv(3), regex(3), the MLE as well as dotlocking and the
148 privileged separated dotlock helper.
150 1.1 What if configuration fails?
151 --------------------------------
153 The configuration process creates some files named "config":
155 - config.log output generated by the configuration compile tests.
156 - config.lst configuration (chosen option, programs, paths).
157 - config.h C program header produced according to "config.lst".
159 Of special interest is "config.log" since the error usually manifests
160 here in textual output. Maybe that makes it obvious what can be done
161 (header files could not be found because of missing entries in
162 $C_INCLUDE_PATH, libraries could not be linked because of incomplete
163 $LD_LIBRARY_PATH, etc.).
164 Otherwise it is getting complicated, and it would be appreciated if you
165 would contact s-nail-users@!
167 1.2 What if building fails?
168 ---------------------------
170 Even worse! This should not happen if configuration succeeded! It
171 would be very kind and highly appreciated if you would report this
174 1.3 How can i enable debugging?
175 -------------------------------
177 Please ensure WANT_DEBUG=yes is enabled during compilation, as in
179 $ make CONFIG=MAXIMAL WANT_DEBUG=yes
181 If $WANT_AUTOCC is enabled then the build system should automatically
182 adjust the compiler flags accordingly, please see "make.rc" for more.
183 There is also a `devel'opment target which does most of this by itself:
187 $WANT_DEBUG (`devel') will enable memory bound debug canaries and
188 Not-Yet-Dead function graph listings etc. Whereas the latter will try
189 to write its listing into a file named after your favourite MUA in
190 your $TMPDIR (or "/tmp" or "./", in order), falling back to STDERR shall
191 creation of the file not be possible (we won't overwrite an existing
192 file), the debug facilities in general make their appearance on the
193 standard error channel; because this can be a quite long output, then,
194 it is possibly a good idea to redirect it to a file:
196 $ s-nail -dvv 2> error.log
198 Should you really discover any problems with S-nail it would be very
199 useful for development if you would contact s-nail-users@!
202 2. Special notes for the latest release
203 ---------------------------------------
205 S-nail(1) has been or is used regulary on these systems ("uname -srm").
206 Unless otherwise noted the following applies to saying "$ make" and
207 "$ make devel" followed by "$ make test".
210 * I've turned off -Wstrict-overflow warnings unless WANT_DEVEL is
211 defined (talking about WANT_AUTOCC=yes here). With gcc 5.1 the
212 number of warnings exploded. With gcc 5.2 that went down again,
213 but just keep it like that nonetheless.
214 * You may see warnings on unused returns from write(2), ftruncate(2)
215 and a few other I/O functions. These will vanish after the large
216 I/O and MIME rewrite that comes next. They mostly refer to debug
217 dumping, truncating a(n open) file to zero size and freopen(3)ing
218 one of the standard channels. I refrained from adding abort(3)
219 calls as return value checks.
221 - All 32-bit systems:
222 * There _may_ be warnings about format strings, like, e.g.,
223 auxlily.c:1610:10: warning: format '%lu' expects type 'long
224 unsigned int', but argument 3 has type 'size_t'
225 The S-nail codebase is ISO C89, so we have no %z printf(3) format.
226 However, "nail.h" tries hard to detect the real type size and
227 defines the "PRI[du]Z" macros which end up with the correct size,
228 which is also compile-time asserted (see the "MCTA(sizeof(size_t) ==
229 XZ)" statements in "nail.h".
231 You can completely overcome this situation by forcing ISO C99 mode
232 when compiling, e.g., with gcc(1) and clang(1): if you use
233 $WANT_AUTOCC then also pass "ADDCFLAGS=-std=c99", otherwise ensure
234 -std=c99 is set in your $CFLAGS.
236 . ArchLinux <https://www.archlinux.org/>
237 Latest as of 2016-03-26, clang(1) and gcc(1).
239 . Void Linux <http://www.voidlinux.eu/>
240 Not tested for v14.8.8.
241 (My current working environment is restricted since i've lost
242 a machine in January.)
244 . CRUX Linux <http://www.crux.nu/>
245 CRUX 3.2 RC3, gcc(1).
247 - FreeBSD <https://www.freebsd.org/>
248 FreeBSD 10.2, clang(1) and gcc6(1).
249 Not tested for v14.8.8.
250 (My current working environment is restricted since i've lost
251 a machine in January.)
253 . OpenBSD <http://www.openbsd.org/>
254 Not tested for v14.8.8.
255 (My current working environment is restricted since i've lost
256 a machine in January.)
258 . DragonFly BSD <https://www.dragonflybsd.org/>
259 Not tested for v14.8.8.
260 (My current working environment is restricted since i've lost
261 a machine in January.)
263 - NetBSD <https://www.netbsd.org/>
266 - Solaris <http://opencsw.org/>
267 @ First of all: thanks to OpenCSW.org for offering SSH access to
268 their Solaris build cluster!
269 * According to standards(5) we require the /usr/xpg4 environment, and
270 will bail if we cannot find it.
271 * With $WANT_AUTOCC: we try to use Sun cc(1) whenever we find it.
272 If your gcc(1) installation is doing alright you have to turn
273 $WANT_AUTOCC off and use $CC, $CFLAGS and $LDFLAGS.
274 * I will never get iconv(3) right for Solaris it seems.
275 * In order to be able to run the tests you will need a cksum(1) that
276 supports CRC-32 (POSIX). We look into "/opt/csw/gnu/cksum", but if
277 that cannot be found you have to adjust the $cksum variable (see
278 above) to something that works. (A future version of S-nail will
279 use different testing, but until then: Sorry!)
280 - I couldn't get us going on SunOS 5.9 Sparc: the build system had to
281 be extended to check for UINTPTR_MAX being defined as the empty
282 string and similar very special things.
283 - The OpenCSW build cluster consists of SunOS 5.9 - 5.11 machines
284 under SPARC and i386, and it looked good on 2016-03-25.
286 + We may forcefully disable stack protectors on SunOS/gcc because of
287 linking errors seen on earlier tests:
288 Undefined first referenced
290 __stack_chk_fail accmacvar.o
291 __stack_chk_guard accmacvar.o
292 ld: fatal: symbol referencing errors
293 + If you get the compiler / system header installation error
294 Undefined first referenced
296 __builtin_stdarg_start auxlily.o
297 then you have to overwrite this symbol with __builtin_va_start,
298 e.g., in conjunction with $WANT_AUTOCC add this:
299 ADDCFLAGS='-D__builtin_stdarg_start=__builtin_va_start'
302 * Note: it is no longer possible to use the `install' rule, because
303 we use shell functions to ease the task of directory creation etc.
304 (especially useful due to $VERBOSE), and that won't work due to bugs
305 (in the system make(1) program i presume).
306 + Not tested for v14.8.[567], but never seen any problems but some
307 harmless and ignorable compile warnings.
309 3. Current codebase state
310 -------------------------
312 I claim that we have reached a stable state that should enable users
313 a neatless mode of operation when running 24/7 (except for growing
314 memory usage from the OpenSSL side of the road, when used).
315 I'll hope to be able to release S-nail v20 on 2020-03-25, the 42nd
316 anniversary of Berkeley Mail, as a good one. Also see "TODO".
318 For S-nail, v15.0 (not before 2017) is dedicated to a Send- and
319 MIME-layer rewrite that will bring the possibility to access each
320 message part individually. Because the Berkeley codebase and its nail
321 fork have design flaws in respect to mailbox handling and non-local code
322 jumps (due to / and signals), whereas the (MIME capable) NetBSD and
323 OpenBSD forks have instead addressed this problem, more or less
324 complete, in one or the other way, v15.0 will also have to address
325 signal handling, because only like that we have the possibility to ever
326 reach a clean state from which we can actually think about re-extending