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.6*
   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 E.g.:
  44
  45   $ make CONFIG=MINIMAL DESTDIR=xtest install
  46
  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:
  53
  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).
  59
  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).
  68
  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.
  74
  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:
  81
  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
  86
  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 ...
  91
  92 2. Notes for S-nail(1) v14.6*
  93 -----------------------------
  94
  95 Note first that MAILSPOOL is by default `/var/mail' (see `conf.rc').
  96 Running `make test' should succeed always and everywhere.
  97
  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.
 102
 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.
 110
 111 . All 32-bit systems:
 112   - There _may_ be warnings about format strings, like, e.g.,
 113
 114       auxlily.c:1610:10: warning: format '%lu' expects type 'long
 115       unsigned int', but argument 3 has type 'size_t'
 116
 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.
 123     It is also compile-time asserted via __ZFMT_CTA(), in main.c.
 124
 125 . Mac OS X <https://www.apple.com/>
 126   (Snow Leopard) Darwin 10.8.0 i386
 127   - gcc-mp-4.8 (MacPorts gcc48 4.8.2_0) 4.8.2.
 128     + Two warnings on 'signed overflow': the '_match_at()' one is to be
 129       inspected
 130   - clang version 3.4 (branches/release_34 197314)
 131     Target: x86_64-apple-darwin10.8.0
 132     Thread model: posix.
 133   - i686-apple-darwin10-gcc-4.2.1 (GCC) 4.2.1 (Apple Inc. build 5666)
 134     (dot 3).
 135   - Apple clang version 1.7 (tags/Apple/clang-77) (based on LLVM
 136     2.9svn).
 137
 138 . ArchLinux <https://www.archlinux.org/>
 139   Linux 3.13.8-1-ARCH x86_64
 140   - gcc (GCC) 4.8.2 20140206 (prerelease)
 141     + `devel'opment target: warnings on unused results, just ignore (for
 142       now).
 143     + Two warnings on 'signed overflow': the '_match_at()' one is to be
 144       inspected
 145
 146 . CRUX Linux <http://www.crux.nu/>
 147   Linux 3.6.11 #1 SMP Sun Sep 15 17:47:31 UTC 2013 x86_64.
 148   - gcc (CRUX-x86_64-multilib) 4.7.2.
 149     + A single warning on 'signed overflow'.
 150     + `devel'opment target: warnings on unused results, just ignore
 151       (for now).
 152     + In a very special test mailbox the character `☕' (U+2615 HOT
 153       BEVERAGE) is displayed as `[3m<98><95>' (`set PAGER='cat -vet''
 154       prints `M-bM-^XM-^U').  Because this is the only system i have
 155       seen this, and only in this single mailbox, i suspect a problem
 156       in the character conversion environment.  (I hope v14.7 brings
 157       sole usage of mbrtowc(3) instead of mbtowc(3) and per-message
 158       multibyte states.  Let's see if that fixes this problem.  I'll
 159       keep the VM around.)
 160
 161 . NetBSD <https://www.netbsd.org/>
 162   NetBSD 6.99.28 NetBSD 6.99.28 (GENERIC) #0: Fri Jan  3 05:24:46 UTC
 163   2014 i386
 164   - gcc (NetBSD nb1 20120916) 4.5.4
 165     + Warnings on format strings -- as above.
 166     + Faulty message on longjmp() clobbering (on a const variable).
 167
 168   NetBSD 6.99.24 NetBSD 6.99.24 (GENERIC) #0: Tue Oct 29 08:23:21 UTC
 169   2013 amd64.
 170   - gcc (NetBSD nb1 20120916) 4.5.4.
 171     + Faulty message on longjmp() clobbering (on a const variable).
 172
 173 . FreeBSD <https://www.freebsd.org/>
 174   FreeBSD 10.0-RELEASE amd64
 175   - FreeBSD clang version 3.3 (tags/RELEASE_33/final 183502) 20130610
 176     Target: x86_64-unknown-freebsd10.0
 177     Thread model: posix
 178
 179 . Void Linux <http://www.voidlinux.eu/>
 180   Linux 3.10.19_1 i686.
 181   - gcc (GCC) 4.7.3.
 182     + A single warning on 'signed overflow'.
 183     + `devel'opment target: warnings on unused results, just ignore (for
 184       now).
 185     + `devel'opment target: warnings on format strings -- as above.
 186
 187 . OpenBSD <http://www.openbsd.org/>
 188   OpenBSD 5.4 i386.
 189   - gcc (GCC) 4.2.1 20070719.
 190     + Faulty message on longjmp() clobbering (on a const variable).
 191     + Warning on usage of strcat(3) in smime_split() (to be addressed
 192       for real (i.e., without loosing S/MIME support) in next minor).
 193
 194 . DragonFly BSD <https://www.dragonflybsd.org/>
 195   DragonFly 3.6-RELEASE x86_64
 196   - gcc 4.7.3 [DragonFly] Release/2013-04-11.
 197     + A single warning on 'signed overflow'.
 198     + Harmless iconv(3) warning again (as if we didn't have had to
 199       treat it specially already).
 200
 201 . UnixWare 7.1.4.
 202   + Note: this make(1) requires the -e option to pass values to make(1)
 203     subprocesses, so, if you want to overwrite DESTDIR= when doing
 204     `packager-install', you better say '$ make -e DESTDIR=xy ...'.
 205   + You'll see some harmless and ignorable warnings (the problematic
 206     looking warning `"openssl.c", line 88: initialization type mismatch'
 207     refers to a cast from non-const to const, which shouldn't matter).
 208
 209 I'm very interested in reports from other combinations.
 210 (It should work practically everywhere, generally speaking.)
 211
 212 3. Current codebase state
 213 -------------------------
 214
 215 Since i've forked Heirloom mailx(1) (for real) as S-nail(1) on
 216 2012-09-18 i make my way through the codebase, and i'm getting more
 217 and more used to it as time goes by -- of course, i'm thinking object
 218 and thus this codebase and i are antipodes.
 219 The following modules have not yet been looked at and/or have known
 220 design flaws or bugs:
 221
 222   IMAP, (IMAP-) Caching
 223   GSS-API (Tarqi Kazan reported with LOG that GSS-API still works)
 224
 225 I'll hope to be able to release S-nail v20 on 2018-03-25, the 40th
 226 anniversary of Mail, as a good one, then.  Also see `TODO'.
 227
 228 In general, S-nail versions before v14.5.2 (old-style codebase, when
 229 used with the four published patches (on Sourceforge or the [patches]
 230 branch)) and v14.6.2 (new-style codebase, after the NYD rewrite) should
 231 not be used. Furthermore, for now (see below) i mostly care about the
 232 core POSIX mailx(1) functionality, everything else has to wait until
 233 some later time, mostly because the Berkeley codebase and its nail fork
 234 have design flaws in respect to mailbox handling and non-local code
 235 jumps (due to / and signals). The (MIME capable) NetBSD and OpenBSD
 236 forks have instead addressed this problem, more or less complete, in one
 237 or the other way.
 238
 239 For S-nail, v15.0 (not before 2016) is dedicated to a Send- and
 240 MIME-layer rewrite that will bring the possibility to access each
 241 message part individually.
 242 It will have to address signal handling and thus the jumps, because only
 243 like that we have the possibility to ever reach a clean state from which
 244 we can actually think about re-extending this MUA.
 245 We need to change string / buffer handling in order to reduce the
 246 overall resource usage and also minimize the duplication of
 247 functionality that internally exists.
 248 It is not unlikely that IMAP support will be dropped temporarily,
 249 leaving only the plain mailx(1) plus Maildir, SMTP and POP3
 250 functionality.  It has to move under the headline reduce to the max.
 251
 252 After this massive change S-nail will hopefully see new features on top
 253 of a straight, object-based, and thus truly extensible interface.
 254 I hope for IMAP, would like to see News, a SQLite-based folder
 255 backend...
 256
 257 vim:set fenc=utf-8:s-ts-mode