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 command line
63 editor (NCL) with history support (if possible), error tracking, basic
64 colour support and IDNA addresses. Also adds in generic spam filter
67 Possibly what people want who need nothing but a MIME-capable mailx(1)
68 and don't regret improved usability for the rare interactive use
71 "Require"s iconv(3), dotlocking and the privileged separated dotlock
75 NETSEND also tries to add SSL/TLS, GSSAPI, .netrc file parsing as well
76 as external password *agent-lookup* on top of MEDIUM, on the other
77 hand spam filter support is removed.
79 Sending messages directly to the mail provider via the SMTP protocol,
80 instead of requiring a local mail-transfer-agent (MTA) who does.
82 "Require"s iconv(3), SSL/TLS, SMTP (sockets), dotlocking and the
83 privileged separated dotlock helper.
86 Anything on, including experimental features.
87 "Require"s iconv(3), regex(3), the NCL as well as dotlocking and the
88 privileged separated dotlock helper.
90 S-nail(1) gains mail fetching capabilities and heads more toward being
91 a full-featured mail-user-agent (MUA) with this.
95 $ make CONFIG=MAXIMAL DESTDIR=./xtest install
97 would create a "s-nail" binary and install a "s-nail" manual etc.
98 under the prefix "/usr/local" but rooted under "[./]xtest", i.e., the
99 binary would be installed as "[./]xtest/usr/local/bin/s-nail".
100 The following make(1) target exists:
102 . all Create / check and update configuration, build.
103 . install Create / check and update configuration, build, install.
104 . clean Remove anything which can be rebuild.
105 . distclean Remove anything which can be rebuild or reconfigured.
106 . uninstall Uninstall (if configured).
108 . config Only create or check and update the configuration.
109 . build Only build (using the existing configuration).
110 . test Run "cc-test.sh" in --check-only mode on the built binary.
111 . doinstall or packager-install
112 Only install using the built files of the existing
113 configuration. It is possible to overwrite DESTDIR= when
114 using this target nonetheless (a following `uninstall'
115 won't know about that overwritten value, however).
117 Setting the make(1) variable $VERBOSE to an arbitrary value, as in
118 "$ make VERBOSE=xy install", will change the output of the `build',
119 `install' etc. targets to a different, more verbose one.
120 If some libraries are missing that you know are installed on your
121 system, or if other errors occur due to missing files but which you know
122 exist, please ensure that the environment variable $C_INCLUDE_PATH
123 includes the necessary "include/" paths and the environment variable
124 $LD_LIBRARY_PATH includes the necessary "lib/"rary paths.
126 The S-nail make system will inspect these two environment variables and
127 *automatically* convert them to cc(1) (c99(1)) -I and -L options (since
128 these environment variables are, different to the command line options,
129 not part of the POSIX standard).
130 To set these environment variables, the following can be done in
131 a Bourne / Korn / POSIX compatible shell:
133 $ C_INCLUDE_PATH="${C_INCLUDE_PATH}:/usr/local/include"
134 $ LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib"
135 $ export C_INCLUDE_PATH LD_LIBRARY_PATH
138 The S-nail make system will also automatically integrate pkgsrc(7) paths
139 into this mechanism. pkgsrc(7) is used to handle building (compilation),
140 installation and removal of software packages on a lot of operating
141 systems, including all BSD systems, Linux, Solaris etc.
142 And if all else fails you can also forcefully pass in include directives
143 and library paths by passing prefilled $INCS and $LIBS variables:
145 $ make INCS=-I/mypath/lib LIBS=-l/mypath/iconv install
147 1.1 What if configuration fails?
148 --------------------------------
150 The configuration process creates some files named "config":
152 . config.log output generated by the configuration compile tests.
153 . config.lst configuration (chosen option, programs, paths).
154 . config.h C program header produced according to "config.lst".
156 Of special interest is "config.log" since the error usually manifests
157 here in textual output. Maybe that makes it obvious what can be done
158 (header files could not be found because of missing entries in
159 $C_INCLUDE_PATH, libraries could not be linked because of incomplete
161 Otherwise it is getting complicated, and it would be appreciated if you
162 would contact s-nail-users@!
164 1.2 What if building fails?
165 ---------------------------
167 Even worse! This should not happen if configuration succeeded! It
168 would be very kind and highly appreciated if you would report this
171 1.3 How can i enable debugging?
172 -------------------------------
174 Please ensure WANT_DEBUG=yes is enabled during compilation, as in
176 $ make CONFIG=MAXIMAL WANT_DEBUG=yes
178 If $WANT_AUTOCC is enabled then the build system should automatically
179 adjust the compiler flags accordingly, please see "make.rc" for more.
180 There is also a `devel'opment target which does most of this by itself:
184 $WANT_DEBUG (`devel') will enable memory bound debug canaries and
185 Not-Yet-Dead function graph listings etc. Whereas the latter will try
186 to write its listing into a file named after your favourite MUA in
187 your $TMPDIR (or "/tmp" or "./", in order), falling back to STDERR shall
188 creation of the file not be possible (we won't overwrite an existing
189 file), the debug facilities in general make their appearance on the
190 standard error channel; because this can be a quite long output, then,
191 it is possibly a good idea to redirect it to a file:
193 $ s-nail -dvv 2> error.log
195 Should you really discover any problems with S-nail it would be very
196 useful for development if you would contact s-nail-users@!
199 2. Special notes for the latest release
200 ---------------------------------------
202 S-nail(1) has been or is used regulary on these systems ("uname -srm").
203 Unless otherwise noted the following applies to saying "$ make" and
204 "$ make devel" followed by "$ make test".
207 - I've turned off -Wstrict-overflow warnings unless WANT_DEVEL is
208 defined (talking about WANT_AUTOCC=yes here). With gcc 5.1 the
209 number of warnings exploded. With gcc 5.2 that went down again,
210 but just keep it like that nonetheless.
211 - You may see warnings on unused returns from write(2), ftruncate(2)
212 and a few other I/O functions. These will vanish after the large
213 I/O and MIME rewrite that comes next. They mostly refer to debug
214 dumping, truncating a(n open) file to zero size and freopen(3)ing
215 one of the standard channels. I refrained from adding abort(3)
216 calls as return value checks.
218 . All 32-bit systems:
219 - There _may_ be warnings about format strings, like, e.g.,
220 auxlily.c:1610:10: warning: format '%lu' expects type 'long
221 unsigned int', but argument 3 has type 'size_t'
222 The S-nail codebase is ISO C89, so we have no %z printf(3) format.
223 However, "nail.h" tries hard to detect the real type size and
224 defines the "PRI[du]Z" macros which end up with the correct size,
225 which is also compile-time asserted (see the "MCTA(sizeof(size_t) ==
226 XZ)" statements in "nail.h".
228 You can completely overcome this situation by forcing ISO C99 mode
229 when compiling, e.g., with gcc(1) and clang(1): if you use
230 $WANT_AUTOCC then also pass "ADDCFLAGS=-std=c99", otherwise ensure
231 -std=c99 is set in your $CFLAGS.
233 . ArchLinux <https://www.archlinux.org/>
234 Latest as of 2015-12-28, tcc(1), clang(1) and gcc(1).
236 + False warning on "'gl.gl_group' may be used uninitialized".
237 I had explicitly committed "Clarify condition (hopefully fix
238 -Wmaybe-uninit, too), 2015-04-28" on [topic/gcc51], but it didn't
240 Ditto, 'gl.gl_slot' and 'gl.gl_htable'.
242 . Void Linux <http://www.voidlinux.eu/>
245 . CRUX Linux <http://www.crux.nu/>
246 CRUX 3.2 RC3, gcc(1).
248 + (Faulty) Warnings on unused 'gl.gl_htable', 'gl.gl_slot' and
252 . FreeBSD <https://www.freebsd.org/>
253 FreeBSD 10.2, clang(1) and gcc6(1).
255 . OpenBSD <http://www.openbsd.org/>
256 OpenBSD 5.8-beta, gcc(1)
258 + Faulty message on longjmp() clobbering (of a const variable).
259 And such. Just ignore that.
260 + (Faulty) Warnings on unused 'gl.gl_htable', 'gl.gl_slot' and
263 . DragonFly BSD <https://www.dragonflybsd.org/>
264 DragonFly 4.2-RELEASE DragonFly v4.2.1-RELEASE, gcc(1)
265 + I will never get iconv(3) right for DragonFly it seems.
267 . NetBSD <https://www.netbsd.org/>
270 . Solaris <http://opencsw.org/>
271 * First of all: thanks to OpenCSW.org for offering SSH access to
272 their Solaris build cluster!
273 - According to standards(5) we require the /usr/xpg4 environment, and
274 will bail if we cannot find it.
275 - With $WANT_AUTOCC: we try to use Sun cc(1) whenever we find it.
276 If your gcc(1) installation is doing alright you have to turn
277 $WANT_AUTOCC off and use $CC, $CFLAGS and $LDFLAGS.
278 - I will never get iconv(3) right for Solaris it seems.
279 - In order to be able to run the tests you will need a cksum(1) that
280 supports CRC-32 (POSIX). We look into "/opt/csw/gnu/cksum", but if
281 that cannot be found you have to adjust the $cksum variable (see
282 above) to something that works. (A future version of S-nail will
283 use different testing, but until then: Sorry!)
284 - I couldn't get us going on SunOS 5.9 Sparc: the build system had to
285 be extended to check for UINTPTR_MAX being defined as the empty
286 string and similar very special things.
287 - The OpenCSW build cluster consists of SunOS 5.9 - 5.11 machines
288 under SPARC and i386, and it looked good on 2015-12-28.
290 + We may forcefully disable stack protectors on SunOS/gcc because of
291 linking errors seen on earlier tests:
292 Undefined first referenced
294 __stack_chk_fail accmacvar.o
295 __stack_chk_guard accmacvar.o
296 ld: fatal: symbol referencing errors
297 + If you get the compiler / system header installation error
298 Undefined first referenced
300 __builtin_stdarg_start auxlily.o
301 then you have to overwrite this symbol with __builtin_va_start,
302 e.g., in conjunction with $WANT_AUTOCC add this:
303 ADDCFLAGS='-D__builtin_stdarg_start=__builtin_va_start'
306 + Note: it is no longer possible to use the `install' rule, because
307 we use shell functions to ease the task of directory creation etc.
308 (especially useful due to $VERBOSE), and that won't work due to bugs
309 (in the system make(1) program i presume).
310 + Not tested for v14.8.[56], but never seen any problems but some
311 harmless and ignorable compile warnings.
313 3. Current codebase state
314 -------------------------
316 I claim that we have reached a stable state that should enable users
317 a neatless mode of operation when running 24/7 (except for growing
318 memory usage from the OpenSSL side of the road, when used).
319 I'll hope to be able to release S-nail v20 on 2020-03-25, the 42th
320 anniversary of Berkeley Mail, as a good one. Also see "TODO".
322 For S-nail, v15.0 (not before 2017) is dedicated to a Send- and
323 MIME-layer rewrite that will bring the possibility to access each
324 message part individually. Because the Berkeley codebase and its nail
325 fork have design flaws in respect to mailbox handling and non-local code
326 jumps (due to / and signals), whereas the (MIME capable) NetBSD and
327 OpenBSD forks have instead addressed this problem, more or less
328 complete, in one or the other way, v15.0 will also have to address
329 signal handling, because only like that we have the possibility to ever
330 reach a clean state from which we can actually think about re-extending
331 this MUA. It is not unlikely that IMAP support will be dropped
332 temporarily, leaving only the plain mailx(1) plus Maildir, SMTP and POP3
333 functionality. It has to move under the headline reduce to the max.