Bump S-nail v14.9.21 ("Tit escapes with a peanut"), 2021-01-21
[s-nail.git] / INSTALL
1 I n s t a l l i n g  S - n a i l / S - m a i l x
2 ================================================
3
4 1.0 Compilation
5 1.1 Configuration failed!
6 1.2 Building failed!
7 1.3 Tests failed!
8 1.4 How can i enable debugging?
9 2.0 Notes on building the latest release
10
11 1.0 Compilation
12 ---------------
13
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 The set of builtin MIME types could be adjusted in ./mime.types.
19 Experts could find it valuable to adjust C code in ./mx-config.h.
20
21 Without any adjustments all non-experimental features will be enabled,
22 except some which provide redundant functionality (e.g., OPT_SPAM_SPAMC
23 is disabled because the generic OPT_SPAM_FILTER can do the same).
24 None of the features are "require"d by default, so that configuration
25 will not fail shall any of them not be available or usable.
26 The generated configuration is tracked: changes will be recognized
27 and cause automatic cleanups and rebuilds as necessary.
28
29   $ make -j2 tangerine  # equals "$ make config build test install"
30   $ make citron         # equals "$ make config build install"
31   $ make distclean      # *Completely* cleanup working directory
32
33 With feature adjustments:
34
35   $ make OPT_POP3=no OPT_SMTP=require tangerine
36   $ make OPT_CROSS_BUILD=y VAL_PREFIX=/some/nasty/prefix citron
37
38 With utility program, build and feature adjustments:
39
40   $ make awk=/usr/bin/nawk VERBOSE=yes OBJDIR=/tmpfs/mx OPT_NET=no tangerine
41
42 If OPT_DOTLOCK has been enabled then the minimal privilege-separated
43 SETUID (to VAL_DOTLOCK_USER, default "root") helper program will be build
44 and installed, and therefore the installation process needs to have the
45 appropriate privileges.  In this case it may be useful to separate the
46 configuration / building and the installation tasks and give the last
47 step higher privileges via super(1), sudo(1), su(1) or a similar
48 mechanism, e.g.:
49
50   $ make VAL_PREFIX=/usr config && make -j4 &&
51     super make DESTDIR=./xy install
52
53 would create a "s-nail" binary and install a "s-nail" manual etc.  under
54 the prefix "/usr" but rooted under "[./]xy", i.e., the binary would be
55 installed as "[./]xy/usr/bin/s-nail".
56
57 Out-of-tree compilation is supported; to use it, create the target
58 directory of desire, change into it and run the make-emerge.sh script
59 shipped with S-nail, then proceed as with normal in-tree building.
60 Generated configuration files, objects and test output will be located
61 in the directory .obj/ (or what $OBJDIR defines), in- or off-tree.
62
63 The following make(1) targets exist, the default being `build':
64
65 - tangerine   Shorthand for "$ make config build test install": create
66               or check and update configuration, build, test, and install.
67               The variable $DESTDIR will be honoured (see make.rc),
68               but not be tracked in the configuration.
69 - citron      Shorthand for "$ make config build install".
70 - all         Shorthand for "$ make config build".
71
72 - config      Only create or check and update the configuration.
73 - build       Only build (using the existing configuration).
74 - install     Only install using the built files of the existing
75               configuration.
76               The variable $DESTDIR will be honoured (see make.rc),
77               but not be tracked in the configuration.
78
79               An uninstall script ${VAL_SID}${VAL_MAILX}-uninstall.sh
80               will be created but *not* be installed if $DESTDIR is set
81               non-empty -- within $DESTDIR, that is: it needs to be
82               copied manually from $OBJDIR into $DESTDIR as necessary.
83
84 - clean       Remove anything which can be rebuild.
85 - distclean   Remove anything which can be rebuild or reconfigured.
86
87 - test        Run mx-test.sh in --check mode on the built binary.
88               Tests to be skipped can be passed via SKIPTEST="t1 t2".
89 - testnj      Likewise, but add --no-jobs to avoid spawning multiple
90               tests in parallel.
91
92 Setting the make(1) variable $VERBOSE to an arbitrary value during
93 `config' time, as in "$ make VERBOSE=xy tangerine", will change the
94 output of the `all', `install' etc. targets to a more verbose one.
95
96 There are also some predefined configuration sets available.
97 It is possible to apply manual adjustments on top of those.
98
99 - CONFIG=NULL, CONFIG=NULLI
100   Anything that can be turned off is off.  MIME cannot.
101   The latter adds and "require"s iconv(3) and adds the user interface
102   strings.
103
104 - CONFIG=MINIMAL
105   Possibly what people want who need nothing but a MIME-capable mailx(1)
106   and do not regret improved usability for the rare interactive use
107   occasions.  Adds documentation strings, the built-in line editor (MLE)
108   with history support and key bindings, error tracking, basic colour
109   support and IDNA addresses, as well as generic spam filter support.
110
111   "Require"s iconv(3), regex(3) and the dotlock helper.
112
113 - CONFIG=NETSEND
114   Sending messages directly to the mail provider via the SMTP protocol,
115   instead of requiring a local mail-transfer-agent (MTA) who does.
116
117   Adds SSL/TLS, SMTP, GSSAPI and .netrc file parsing on top of MINIMAL.
118
119   "Require"s iconv(3), SSL/TLS, SMTP (sockets) and the dotlock helper.
120
121 - CONFIG=MAXIMAL
122   Like MINIMAL, but turns on all (other) options, also obsolete or
123   redundant ones, but none of them required.
124
125 If during configuration or building some libraries seem to be missing
126 that you know are installed on your system, or if other errors occur
127 due to missing files but which you know exist, please ensure that the
128 environment variable $C_INCLUDE_PATH includes the necessary "include/"
129 paths and the environment variable $LD_LIBRARY_PATH includes the
130 necessary "lib/"rary paths.
131
132 The build system will inspect these two environment variables and
133 automatically convert them to cc(1) (c99(1)) -I and -L options (since
134 these environment variables are, different to the command line options,
135 not part of the POSIX standard).
136 To set these environment variables, the following can be done in
137 a Bourne / Korn / POSIX compatible shell:
138
139   $ C_INCLUDE_PATH="${C_INCLUDE_PATH}:/usr/local/include"
140   $ LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib"
141   $ export C_INCLUDE_PATH LD_LIBRARY_PATH
142   $ make tangerine CONFIG=MINIMAL
143
144 Other than the standard paths /usr/{bin,include,lib} and /usr/local/[.]
145 should possibly be placed first instead, presuming that they are meant
146 to override things which usually exist in standard locations.
147 If all else fails you can also forcefully pass in include directives and
148 library paths via prefilled $INCS and $LIBS variables:
149
150   $ make INCS=-I/mypath/include LIBS="-L/mypath/lib -lmylib" tangerine
151
152 1.1 Configuration failed!
153 -------------------------
154
155 Please see the section "Notes on building the latest release" below
156 first, maybe it has an item for the failing platform, or even gives an
157 answer on how to proceed nonetheless.
158
159 The configuration process creates a directory ./.obj (or $OBJDIR, if
160 set) to store some files of interest (it is also here where the build
161 and the tests take place):
162
163 - mk-config.log  Any output generated during the configuration process.
164 - mk-config.h    C program header representing the configuration.
165 - mk-config.env  sh(1) environment representing the configuration.
166
167 Of special interest is mk-config.log since the error usually manifests
168 here in textual form.  Maybe that makes it obvious what can be done
169 (header files could not be found because of missing entries in
170 $C_INCLUDE_PATH, libraries could not be linked because of incomplete
171 $LD_LIBRARY_PATH, etc.).
172
173 If things went wrong so completely that even "$ make distclean" is not
174 possible, simply removing .obj ($OBJDIR) will do: "$ rm -rf ./.obj".
175 In any case it would be appreciated if you could report the problem,
176 so that problems can be fixed!
177
178 1.2 Building failed!
179 --------------------
180
181 Terrible!  This should not happen if configuration succeeded!
182 Again, it would be appreciated if you could report the problem, so that
183 problems can be fixed!
184
185 1.3 Tests failed!
186 -----------------
187
188 Please see the section "Notes on building the latest release" below
189 first: sometimes it is known that certain tests fail on a specific
190 target platform, and there is no applicable fix on application level.
191 For example, it is not uncommon that Unicode tests fail because the
192 platform uses old or incomplete character information.
193 These tests can be excluded by passing SKIPTEST="t1 t2 ..".
194
195 It could also be a miscompilation, caused by excessive optimization
196 and/or a compiler bug.  If OPT_AUTOCC had been used in conjunction with
197 a non-debug target (the defaults), an additional cc_maxopt=1 (or an
198 EXTRA_CFLAGS=-O1 etc.) on the command line and a successive
199 reconfiguration and -compilation could turn the green testing light on.
200
201 In order to inspect the error more thoroughly, the mx-test.sh script
202 can be used in --run-test mode to invoke the failing tests (testing
203 echoes the actual test names in brackets), for example
204
205   $ ./mx-test.sh --run-test ./s-nail localopts mbox
206
207 would run the tests "localopts" and "mbox".  If not an absolute path
208 the binary (./s-nail) is expected relative to $OBJDIR.  There also the
209 test output files, named like t.TESTNAME-XY, reside.
210 (If the build and test is done in a repository checkout, and if the
211 branch "test-out" exists, then in addition to the failing test output
212 the expected as well as -- optionally -- the file difference of these
213 two is generated automatically, too.  And these outputs are also
214 generated for normal "$ make test" runs, then.)
215
216 It might make sense to send the output files of the failing tests to
217 the mailing-list.  Because of ML message size restrictions, creating
218 a compressed tar(1) archive of the files would be appreciated:
219
220   $ rm -f .obj/t.*.old #.obj/t.*.diff # (In repository checkout only)
221   $ tar -cf - .obj/t.* | (xz/gzip/zstd -T0 -19) > tlogs.tar.(xz/gz/zst)
222
223 Thank you!
224
225 1.4 How can i enable debugging?
226 -------------------------------
227
228 Enable OPT_DEBUG=yes during compilation
229
230   $ make CONFIG=MAXIMAL OPT_DEBUG=yes
231
232 to gain compiler debug flags, memory bound canaries and Not-Yet-Dead
233 function graph listings in case of crashes etc.
234 For sanitizers plus special options exist, please read make.rc for more.
235
236 In case of errors using the -d (*debug*) and -v (*verbose*[=VALUE])
237 options (variables) is always good idea:
238
239   $ s-nail -dvv
240 or
241   $ s-nail -Sdebug -Sverbose=3
242
243 Should you really discover any problems with S-nail it would be very
244 useful for development if you would contact the mailing-list!
245 Thank you!
246
247 2.0 Notes on building the latest release
248 ----------------------------------------
249
250 - All systems:
251   * Running tests on a NFS filesystem may cause false negatives.
252     (Seen on the SunOS 5.11 OpenCSW machines, in [pipe_handlers]
253     failure due to hard link count mismatch since NFS also links the
254     file to some other name and that lingers too long, reproducibly).
255
256   * Various warnings for diverse compiler versions etc.  This is a race
257     which cannot be won, so i make the software compile and test under
258     each compiler version i get my fingers at, and of course i fix bugs
259     when i see them.
260     The warnings on unused returns from some I/O functions will vanish
261     after the large v15 I/O and MIME rewrite.
262
263 - All 32-bit systems:
264   * There _may_ be warnings about format strings, like, e.g.,
265       auxlily.c:1610:10: warning: format '%lu' expects type 'long
266       unsigned int', but argument 3 has type 'size_t'
267     The codebase is ISO C89 which has no %z printf(3) format.
268     However we try hard to detect the real type size and define the
269     "PRI[du]Z" macros which end up with the correct size, which is
270     also compile-time asserted (via "MCTA(sizeof(size_t) == XZ)").
271
272     By forcing ISO C99 mode these warnings vanish, for example gcc(1):
273     with OPT_AUTOCC pass "EXTRA_CFLAGS=-std=c99", otherwise ensure that
274     -std=c99 is defined in $CFLAGS.
275
276 - BSD make, AND FreeBSD-derived sh(1):
277   * bmake(1) cannot drive "make test" with sh(1)ells that use monitor
278     mode "set -m".  Please pass JOBMON=n ("make test JOBMON=n").
279
280 Development:
281
282 . CRUX Linux <https://www.crux.nu/> (x86-64: 3.6 (3.[56]).
283
284 Frequently:
285
286 . AlpineLinux <https://www.alpinelinux.org> (x86-64: edge).
287
288 . ArchLinux <https://www.archlinux.org/> (current).
289
290 . FreeBSD <https://www.freebsd.org/> (x86: 11.2,12.1; amd64: 12.2).
291   - v11. series test errors: see DragonFly.
292   - BSD make -j / sh(1) -m issue, as above.
293
294 . OpenBSD <https://www.openbsd.org/> (x86: latest (6.[4-8])).
295
296 Pre-release, and other landmarks:
297
298 . DragonFly BSD <https://www.dragonflybsd.org/> (5.{6.1,8.0}).
299   - The tests [iconv_mbyte_base64]-{4,8} fail because the C function
300     iswprint(3) falsely claims that U+FF08 and U+FF09 (FULLWIDTH
301     LEFT and RIGHT PARENTHESIS, respectively) are not printable,
302     causing replacements.  This is a known bug, see
303       <https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=225692>
304   - BSD make -j / sh(1) -m issue, as above.
305
306 . NetBSD <https://www.netbsd.org/> (amd64: 9.0).
307   - BSD make -j issue, as above.
308
309 . OSUKISS Linux <https://osukiss.safe.ca/> (boing-boom-tschak)
310   @ Thanks to Jean-Marc Pigeon for generously providing access to
311     a VZGOT on the most "beefy" machine i have ever worked on! ^_^
312
313 . Solaris <http://opencsw.org/>
314   @ First of all: thanks to OpenCSW.org for offering SSH access to
315     their Solaris build cluster!
316     (Sparc and x86 machines with SunOS 5.9, 5.10 and 5.11.)
317
318   * We yet favoured Sun's compiler, but now use the default algorithm
319     which goes for $CC/$CFLAGS if set, then searches open-source
320     compilers, only if that fails we go for traditional SUN.
321
322   * The original Sun roff (aka AT&T ditroff) is not capable to display
323     the manual.  We offer preformatted manual pages, please see the
324     release announcement for details.
325
326   * Some notes collected on earlier trials:
327     + We may forcefully disable stack protectors on SunOS/gcc because
328       of link errors seen in earlier tests.
329     + If you get the compiler / system header installation error
330         Undefined                       first referenced
331          symbol                             in file
332         __builtin_stdarg_start              auxlily.o
333       you have to overwrite the symbol with __builtin_va_start,
334        EXTRA_CFLAGS='-D__builtin_stdarg_start=__builtin_va_start'
335
336   - You may see failures in Unicode-related tests due to outdated or
337     false Unicode tables on elder releases (as in NetBSD).
338
339 .  SunOS schillix 5.11 schillix-on i86pc i386 i86pc
340    - reply-21 fails with iconv(3) error "Cannot convert from utf-8 to
341      646", which is an iconv(3) error (should just do it).
342
343 . Void Linux <https://www.voidlinux.org/> (x86)
344   - Still not have setup all my environment after having lost all,
345     so not tested recently.
346
347 # s-ts-mode
This page took 0.059288 seconds and 3 git commands to generate.