INSTALL

   1 I n s t a l l i n g  S - n a i l
   2 ================================
   3
   4 1. Compilation
   5 2. Notes for S-nail(1) v14.7*
   6 3. Current codebase state
   7
   8 1. Compilation
   9 --------------
  10
  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):
  15
  16   $ [make &&] make install
  17   $ make uninstall          # Won't remove the system wide startup file!
  18   $ make distclean          # *Completely* cleanup working directory
  19
  20 With adjustments:
  21
  22   $ make WANT_IMAP=0 install
  23   $ make WANT_NCL=0 PREFIX=/some/nasty/prefix install
  24
  25 There are also some predefined restricted configuration sets available,
  26 which take precedence over anything else:
  27
  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.
  32
  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.
  37
  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.
  42
  43 . CONFIG=MAXIMAL
  44   Anything on.
  45
  46 E.g.:
  47
  48   $ make CONFIG=MINIMAL DESTDIR=xtest install
  49
  50 would create a `s-nail' binary and install a `s-nail' manual etc.
  51 under the prefix `/usr/local' but rooted under [./]`xtest', i.e., the
  52 binary would be installed as `[./]xtest/usr/local/bin/s-nail'.
  53 The following make(1) target exists, and note that you can use
  54 a VERBOSE=1 command line option to gain more (or a different kind of)
  55 verbosity:
  56
  57 . all         Create / check and update configuration, build.
  58 . install     Create / check and update configuration, build, install.
  59 . clean       Remove anything which can be rebuild.
  60 . distclean   Remove anything which can be rebuild or reconfigured.
  61 . uninstall   Uninstall (if configured).
  62
  63 . config      Only create or check and update the configuration.
  64 . build       Only build (using the existing configuration).
  65 . test        Run ./cc-test.sh in --check-only mode on the built binary.
  66 . packager-install
  67               Only install using the built files of the existing
  68               configuration.  It is possible to overwrite DESTDIR= when
  69               using this target nonetheless (a following `uninstall'
  70               won't know about that overwritten value, however).
  71
  72 If some libraries are missing that you know are installed on your
  73 system, or if other errors occur due to missing files but which you know
  74 exist, please ensure that the environment variable `C_INCLUDE_PATH'
  75 includes the necessary `include/' paths and the environment variable
  76 `LD_LIBRARY_PATH' includes the necessary `lib/'rary paths.
  77
  78 The S-nail make system will inspect these two environment variables and
  79 *automatically* convert them to cc(1) (c99(1)) -I and -L options (since
  80 these environment variables are, different to the command line options,
  81 not part of the POSIX standard).
  82 To set these environment variables, the following can be done in
  83 a Bourne/Korn/POSIX compatible shell:
  84
  85   $ C_INCLUDE_PATH="${C_INCLUDE_PATH}:/usr/local/include"
  86   $ LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib"
  87   $ export C_INCLUDE_PATH LD_LIBRARY_PATH
  88   $ make install
  89
  90 The S-nail make system will also automatically integrate pkgsrc(7) paths
  91 into this mechanism.  pkgsrc(7) is used to handle building (compilation),
  92 installation and removal of software packages on a lot of operating
  93 systems, including all BSD systems, Linux, Solaris ...
  94
  95 2. Notes for S-nail(1) v14.7*
  96 -----------------------------
  97
  98 Note first that MAILSPOOL is by default `/var/mail' (see `conf.rc').
  99 Running `make test' should succeed always and everywhere.
 100
 101 S-nail(1) has been or is used regulary on these systems (`uname -srm').
 102 Also, i'm (compile) testing manually with WANT_AUTOCC=1, WANT_DEBUG=[01]
 103 and WANT_AMALGAMATION=[01] (and WANT_GSSAPI=1), which is what is
 104 reflected by the following statements.
 105
 106 . All with WANT_AMALGAMATION=1:
 107   - Dependent on the configuration you may see some warnings about
 108     unused functions.  This shouldn't happen for a any of the predefined
 109     CONFIG= urations, including the one that results from the default
 110     settings of `conf.rc', but it may temporarily happen as long as the
 111     codebase is in that heavy fluctuation state.  Reports are welcome to
 112     vanish them until v20.
 113
 114 . All 32-bit systems:
 115   - There _may_ be warnings about format strings, like, e.g.,
 116
 117       auxlily.c:1610:10: warning: format '%lu' expects type 'long
 118       unsigned int', but argument 3 has type 'size_t'
 119
 120     This is ugly, but it has been decided to keep the S-nail codebase
 121     ISO C89 compatible, so that there is no %z format string modifier.
 122     However, `nail.h' tries hard to detect the real type sizes and ends
 123     up in a way that should ensure that the actually expected datatype
 124     is of the same size in reality -- please see the definition of the
 125     `ZFMT' macro in `nail.h' to verify this statement is true.
 126     It is also compile-time asserted via __ZFMT_CTA(), in main.c.
 127
 128 . Mac OS X <https://www.apple.com/>
 129   (Snow Leopard) Darwin 10.8.0 i386
 130   - gcc-mp-4.8 (MacPorts gcc48 4.8.2_0) 4.8.2.
 131     + Two warnings on 'signed overflow': the '_match_at()' one is to be
 132       inspected (CONFIG=MINIMAL WANT_AMALGAMATION=1).
 133   - clang version 3.4 (branches/release_34 197314)
 134     Target: x86_64-apple-darwin10.8.0
 135     Thread model: posix.
 136   - i686-apple-darwin10-gcc-4.2.1 (GCC) 4.2.1 (Apple Inc. build 5666)
 137     (dot 3).
 138   - Apple clang version 1.7 (tags/Apple/clang-77) (based on LLVM
 139     2.9svn).
 140
 141 . ArchLinux <https://www.archlinux.org/>
 142   Linux 3.14.2-1-ARCH x86_64
 143   - gcc (GCC) 4.9.0
 144     + `devel'opment target: warnings on unused results, just ignore (for
 145       now).
 146     + I think faulty message on longjmp() clobbering on a const variable?
 147
 148 . CRUX Linux <http://www.crux.nu/>
 149   CRUX 3.1 (rc1) Linux 3.12.17 x86_64.
 150   - gcc (CRUX) 4.8.2.
 151     + Two warnings on 'signed overflow': the '_match_at()' one is to be
 152       inspected (CONFIG=MINIMAL WANT_AMALGAMATION=1).
 153     + `devel'opment target: warnings on unused results, just ignore
 154       (for now).
 155     + (The HOT BEVERAGE error doesn't occur, even today.)
 156
 157   Linux 3.6.11 #1 SMP Sun Sep 15 17:47:31 UTC 2013 x86_64.
 158   - gcc (CRUX-x86_64-multilib) 4.7.2.
 159     + For rememberance:
 160       In a very special test mailbox the character `☕' (U+2615 HOT
 161       BEVERAGE) is displayed as `[3m<98><95>' (`set PAGER='cat -vet''
 162       prints `M-bM-^XM-^U').  Because this is the only system i have
 163       seen this, and only in this single mailbox, i suspect a problem
 164       in the character conversion environment.  (I hope v14.888888888ngs
 165       sole usage of mbrtowc(3) instead of mbtowc(3) and per-message
 166       multibyte states.  Let's see if that fixes this problem.  I'll
 167       keep the VM around.)
 168
 169 . NetBSD <https://www.netbsd.org/>
 170   NetBSD 6.99.40 i386 (201404092030Z)
 171   - gcc (NetBSD nb2 20140304) 4.8.3
 172     + Warnings on format strings -- as above.
 173     + Faulty message on longjmp() clobbering (on a const variable).
 174
 175   NetBSD 6.99.24 NetBSD 6.99.24 (GENERIC) #0: Tue Oct 29 08:23:21 UTC
 176   2013 amd64.
 177   - gcc (NetBSD nb1 20120916) 4.5.4.
 178     + Faulty message on longjmp() clobbering (on a const variable).
 179
 180 . FreeBSD <https://www.freebsd.org/>
 181   FreeBSD 10.0-RELEASE amd64
 182   - FreeBSD clang version 3.3 (tags/RELEASE_33/final 183502) 20130610
 183     Target: x86_64-unknown-freebsd10.0
 184     Thread model: posix
 185
 186 . Void Linux <http://www.voidlinux.eu/>
 187   Linux 3.10.19_1 i686.
 188   - gcc (GCC) 4.7.3.
 189     + A single warning on 'signed overflow'.
 190     + `devel'opment target: warnings on unused results, just ignore (for
 191       now).
 192     + `devel'opment target: warnings on format strings -- as above.
 193
 194 . OpenBSD <http://www.openbsd.org/>
 195   OpenBSD 5.6 (current as of 2014-05-25) i386,
 196   OpenBSD 5.4 i386.
 197   - gcc (GCC) 4.2.1 20070719.
 198     + Faulty message on longjmp() clobbering (on a const variable).
 199     + Warning on usage of strcat(3) in smime_split() (to be addressed
 200       for real (i.e., without loosing S/MIME support) in next minor).
 201
 202 . DragonFly BSD <https://www.dragonflybsd.org/>
 203   DragonFly 3.6-RELEASE x86_64
 204   - gcc 4.7.3 [DragonFly] Release/2013-04-11.
 205     + A single warning on 'signed overflow'.
 206     + Harmless iconv(3) warning again (as if we didn't have had to
 207       treat it specially already).
 208
 209 . UnixWare 7.1.4.
 210   + Note: it is no longer possible to use the `install' rule -- mk-mk.in
 211     uses shell functions to ease the task of directory creation etc.
 212     (especially useful due to VERBOSE=), and that won't work due to bugs.
 213   + You'll see some harmless and ignorable warnings (the problematic
 214     looking warning `"openssl.c", line 88: initialization type mismatch'
 215     refers to a cast from non-const to const, which shouldn't matter).
 216
 217 I'm very interested in reports from other combinations.
 218 (It should work practically everywhere, generally speaking.)
 219
 220 3. Current codebase state
 221 -------------------------
 222
 223 Since i've forked Heirloom mailx(1) (for real) as S-nail(1) on
 224 2012-09-18 i make my way through the codebase, and i'm getting more
 225 and more used to it as time goes by -- of course, i'm thinking object
 226 and thus this codebase and i are antipodes.
 227 The following modules have not yet been looked at and/or have known
 228 design flaws or bugs:
 229
 230   IMAP, (IMAP-) Caching
 231   GSS-API (Tarqi Kazan reported with LOG that GSS-API still works)
 232
 233 I'll hope to be able to release S-nail v20 on 2018-03-25, the 40th
 234 anniversary of Mail, as a good one, then.  Also see `TODO'.
 235
 236 In general, S-nail versions before v14.6.4 should not be used.
 237 Furthermore, for now (see below) i mostly care about the core POSIX
 238 mailx(1) functionality, everything else has to wait until some later
 239 time, mostly because the Berkeley codebase and its nail fork have design
 240 flaws in respect to mailbox handling and non-local code jumps (due to
 241 / and signals). The (MIME capable) NetBSD and OpenBSD forks have instead
 242 addressed this problem, more or less complete, in one or the other way.
 243
 244 For S-nail, v15.0 (not before 2016) is dedicated to a Send- and
 245 MIME-layer rewrite that will bring the possibility to access each
 246 message part individually. Because the Berkeley codebase and its nail
 247 fork have design flaws in respect to mailbox handling and non-local code
 248 jumps (due to / and signals), whereas the (MIME capable) NetBSD and
 249 OpenBSD forks have instead addressed this problem, more or less
 250 complete, in one or the other way, v15.0 will also have to address
 251 signal handling, because only like that we have the possibility to ever
 252 reach a clean state from which we can actually think about re-extending
 253 this MUA. It is not unlikely that IMAP support will be dropped
 254 temporarily, leaving only the plain mailx(1) plus Maildir, SMTP and POP3
 255 functionality. It has to move under the headline reduce to the max.
 256
 257 After this massive change S-nail will hopefully see new features on top
 258 of a straight, object-based, and thus truly extensible interface.
 259 I hope for IMAP, would like to see News, a SQLite-based folder
 260 backend...
 261
 262 vim:set fenc=utf-8:s-ts-mode