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