TODO: howto overcome our signal no-go dead-end situation
[s-mailx.git] / INSTALL
blob3e874e8fa7fc566684c33660bdecce7d0f2294ef
1 I n s t a l l i n g  S - n a i l
2 ================================
4 1. Compilation
5 2. Notes for S-nail(1) v14.6*
6 3. Current codebase state
8 1. Compilation
9 --------------
11 System specific notes can be found in the next section.
12 Any (optional) feature is adjustable and documented in `conf.rc'.
13 Adjustments may also take place, and are usually done, from the command
14 line, overriding those made in `conf.rc' (if any):
16   $ [make &&] make install
17   $ make uninstall          # Won't remove the system wide startup file!
18   $ make distclean          # *Completely* cleanup working directory
20 With adjustments:
22   $ make WANT_IMAP=0 install
23   $ make WANT_NCL=0 PREFIX=/some/nasty/prefix install
25 There are also some predefined restricted configuration sets available,
26 which take precedence over anything else:
28 . CONFIG=MINIMAL
29   little is left but some air to breathe; no internet connectivity, no
30   internationalized domain names, no IMAP-searches, no regular
31   expression searches, no command line editor, no documentation strings.
33 . CONFIG=MEDIUM
34   Like MINIMAL, but with documentation strings, and the regular
35   expression searches as well as the builtin command line editor will be
36   included if that is possible.
38 . CONFIG=NETSEND
39   WANT_SMTP and WANT_SSL settings are enabled, internationalized domain
40   names will be supported if the necessary libraries are available,
41   otherwise identical to MEDIUM.
43 E.g.:
45   $ make CONFIG=MINIMAL DESTDIR=xtest install
47 would create a `s-nail' binary and install a `s-nail' manual etc.
48 under the prefix `/usr/local' but rooted under [./]`xtest', i.e., the
49 binary would be installed as `[./]xtest/usr/local/bin/s-nail'.
50 The following make(1) target exists, and note that you can use
51 a VERBOSE=1 command line option to gain more (or a different kind of)
52 verbosity:
54 . all         Create / check and update configuration, build.
55 . install     Create / check and update configuration, build, install.
56 . clean       Remove anything which can be rebuild.
57 . distclean   Remove anything which can be rebuild or reconfigured.
58 . uninstall   Uninstall (if configured).
60 . config      Only create or check and update the configuration.
61 . build       Only build (using the existing configuration).
62 . test        Run ./cc-test.sh in --check-only mode on the built binary.
63 . packager-install
64               Only install using the built files of the existing
65               configuration.  It is possible to overwrite DESTDIR= when
66               using this target nonetheless (a following `uninstall'
67               won't know about that overwritten value, however).
69 If some libraries are missing that you know are installed on your
70 system, or if other errors occur due to missing files but which you know
71 exist, please ensure that the environment variable `C_INCLUDE_PATH'
72 includes the necessary `include/' paths and the environment variable
73 `LD_LIBRARY_PATH' includes the necessary `lib/'rary paths.
75 The S-nail make system will inspect these two environment variables and
76 *automatically* convert them to cc(1) (c99(1)) -I and -L options (since
77 these environment variables are, different to the command line options,
78 not part of the POSIX standard).
79 To set these environment variables, the following can be done in
80 a Bourne/Korn/POSIX compatible shell:
82   $ C_INCLUDE_PATH="${C_INCLUDE_PATH}:/usr/local/include"
83   $ LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib"
84   $ export C_INCLUDE_PATH LD_LIBRARY_PATH
85   $ make install
87 The S-nail make system will also automatically integrate pkgsrc(7) paths
88 into this mechanism.  pkgsrc(7) is used to handle building (compilation),
89 installation and removal of software packages on a lot of operating
90 systems, including all BSD systems, Linux, Solaris ...
92 2. Notes for S-nail(1) v14.6*
93 -----------------------------
95 Note first that MAILSPOOL is by default `/var/mail' (see `conf.rc').
96 Running `make test' should succeed always and everywhere.
98 S-nail(1) has been or is used regulary on these systems (`uname -srm').
99 Also, i'm (compile) testing manually with WANT_AUTOCC=1, WANT_DEBUG=[01]
100 and WANT_AMALGAMATION=[01] (and WANT_GSSAPI=1), which is what is
101 reflected by the following statements.
103 . All with WANT_AMALGAMATION=1:
104   - Dependent on the configuration you may see some warnings about
105     unused functions.  This shouldn't happen for a any of the predefined
106     CONFIG= urations, including the one that results from the default
107     settings of `conf.rc'.  It may temporarily happen for other
108     individual configurations as long as the codebase is in that heavy
109     fluctuation state.  Reports are welcome to vanish them until v20.
111 . All 32-bit systems:
112   - There _may_ be warnings about format strings, like, e.g.,
114       auxlily.c:1610:10: warning: format '%lu' expects type 'long
115       unsigned int', but argument 3 has type 'size_t'
117     This is ugly, but it has been decided to keep the S-nail codebase
118     ISO C89 compatible, so that there is no %z format string modifier.
119     However, `nail.h' tries hard to detect the real type sizes and ends
120     up in a way that should ensure that the actually expected datatype
121     is of the same size in reality -- please see the definition of the
122     `ZFMT' macro in `nail.h' to verify this statement is true.
124 . Mac OS X <https://www.apple.com/>
125   (Snow Leopard) Darwin 10.8.0 i386
126   - gcc-mp-4.8 (MacPorts gcc48 4.8.2_0) 4.8.2.
127     + Two warnings on 'signed overflow': the '_match_at()' one is to be
128       inspected
129   - clang version 3.4 (branches/release_34 197314)
130     Target: x86_64-apple-darwin10.8.0
131     Thread model: posix.
132   - i686-apple-darwin10-gcc-4.2.1 (GCC) 4.2.1 (Apple Inc. build 5666)
133     (dot 3).
134   - Apple clang version 1.7 (tags/Apple/clang-77) (based on LLVM
135     2.9svn).
137 . ArchLinux <https://www.archlinux.org/>
138   Linux 3.13.4-1-ARCH x86_64
139   - gcc (GCC) 4.8.2 20140206 (prerelease)
140     + `devel'opment target: warnings on unused results, just ignore (for
141       now).
142     + Two warnings on 'signed overflow': the '_match_at()' one is to be
143       inspected
145 . CRUX Linux <http://www.crux.nu/>
146   Linux 3.6.11 #1 SMP Sun Sep 15 17:47:31 UTC 2013 x86_64.
147   - gcc (CRUX-x86_64-multilib) 4.7.2.
148     + A single warning on 'signed overflow'.
149     + `devel'opment target: warnings on unused results, just ignore
150       (for now).
151     + In a very special test mailbox the character `☕' (U+2615 HOT
152       BEVERAGE) is displayed as `[3m<98><95>' (`set PAGER='cat -vet''
153       prints `M-bM-^XM-^U').  Because this is the only system i have
154       seen this, and only in this single mailbox, i suspect a problem
155       in the character conversion environment.  (I hope v14.7 brings
156       sole usage of mbrtowc(3) instead of mbtowc(3) and per-message
157       multibyte states.  Let's see if that fixes this problem.  I'll
158       keep the VM around.)
160 . NetBSD <https://www.netbsd.org/>
161   NetBSD 6.99.28 NetBSD 6.99.28 (GENERIC) #0: Fri Jan  3 05:24:46 UTC
162   2014 i386
163   - gcc (NetBSD nb1 20120916) 4.5.4
164     + Warnings on format strings -- as above.
165     + Faulty message on longjmp() clobbering (on a const variable).
167   NetBSD 6.99.24 NetBSD 6.99.24 (GENERIC) #0: Tue Oct 29 08:23:21 UTC
168   2013 amd64.
169   - gcc (NetBSD nb1 20120916) 4.5.4.
170     + Faulty message on longjmp() clobbering (on a const variable).
172 . FreeBSD <https://www.freebsd.org/>
173   FreeBSD 10.0-RELEASE amd64
174   - FreeBSD clang version 3.3 (tags/RELEASE_33/final 183502) 20130610
175     Target: x86_64-unknown-freebsd10.0
176     Thread model: posix
178 . Void Linux <http://www.voidlinux.eu/>
179   Linux 3.10.19_1 i686.
180   - gcc (GCC) 4.7.3.
181     + A single warning on 'signed overflow'.
182     + `devel'opment target: warnings on unused results, just ignore (for
183       now).
184     + `devel'opment target: warnings on format strings -- as above.
186 . OpenBSD <http://www.openbsd.org/>
187   OpenBSD 5.4 i386.
188   - gcc (GCC) 4.2.1 20070719.
189     + Faulty message on longjmp() clobbering (on a const variable).
190     + Warning on usage of strcat(3) in smime_split() (to be addressed
191       for real (i.e., without loosing S/MIME support) in next minor).
193 . DragonFly BSD <https://www.dragonflybsd.org/>
194   DragonFly 3.6-RELEASE x86_64
195   - gcc 4.7.3 [DragonFly] Release/2013-04-11.
196     + A single warning on 'signed overflow'.
197     + Harmless iconv(3) warning again (as if we didn't have had to
198       treat it specially already).
200 . UnixWare 7.1.4.
201   + Note: this make(1) requires the -e option to pass values to make(1)
202     subprocesses, so, if you want to overwrite DESTDIR= when doing
203     `packager-install', you better say '$ make -e DESTDIR=xy ...'.
204   + You'll see some harmless and ignorable warnings (the problematic
205     looking warning `"openssl.c", line 88: initialization type mismatch'
206     refers to a cast from non-const to const, which shouldn't matter).
208 I'm very interested in reports from other combinations.
209 (It should work practically everywhere, generally speaking.)
211 3. Current codebase state
212 -------------------------
214 Since i've forked Heirloom mailx(1) (for real) as S-nail(1) on
215 2012-09-18 i make my way through the codebase, and i'm getting more
216 and more used to it as time goes by -- of course, i'm thinking object
217 and thus this codebase and i are antipodes.
218 The following modules have not yet been looked at and/or have known
219 design flaws or bugs:
221   IMAP, (IMAP-) GSSAPI, (IMAP-) Caching
223 I'll hope to be able to release S-nail v20 on 2018-03-25, the 40th
224 anniversary of Mail, as a good one, then.  Also see `TODO'.
226 In general, S-nail versions before v14.5.2 (old-style codebase, when
227 used with the four published patches (on Sourceforge or the [patches]
228 branch)) and v14.6.1 (new-style codebase, after the NYD rewrite) should
229 not be used. Furthermore, for now (see below) i mostly care about the
230 core POSIX mailx(1) functionality, everything else has to wait until
231 some later time, mostly because the Berkeley codebase and its nail fork
232 have design flaws in respect to mailbox handling and non-local code
233 jumps (due to / and signals). The (MIME capable) NetBSD and OpenBSD
234 forks have instead addressed this problem, more or less complete, in one
235 or the other way.
237 For S-nail, v15.0 (not before 2015) is dedicated to a send and MIME
238 layer rewrite that will bring the possibility to access each message
239 part individually, and will also address some of the jump-related
240 problems (at least as far as the send, mail-collection and MIME layer is
241 affected), which unfortunately include memory leaks and, also, may
242 include crashes. Just let it run run run until anything is fixed. I'm
243 afraid that many jump related problems will remain even in v15.0.
245 v16.0 (not before 2016) will have to address signal handling and thus
246 the jumps, because only like that we have the possibility to ever reach
247 a clean state from which we can actually think about re-extending this
248 MUA. We need to change string / buffer handling in order to reduce the
249 overall resource usage and also minimize the duplication of
250 functionality that internally exists. It is likely that IMAP support is
251 temporarily dropped for the entire v16 cycle, leaving only the plain
252 mailx(1) plus Maildir, SMTP and POP3 functionality. v16.0 has to move
253 under the headline reduce to the max.
255 v17 and above will then hopefully see new features on top of a straight
256 object-based, and thus truly extensible interface. I hope for IMAP,
257 would like to see News, a SQLite-based folder backend...
259 vim:set fenc=utf-8:s-ts-mode