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   This is the most plain mailx(1)-alike mode, but with MIME support and
  34   (if available) character set conversion builtin.
  35
  36 . CONFIG=MEDIUM
  37   Like MINIMAL, but with documentation strings, and regular expression
  38   support as well as the builtin command line editor will be included if
  39   that is possible.
  40
  41   Possibly what people want who need nothing but a MIME-capable mailx(1)
  42   and don't regret improved usability for the rare interactive use
  43   occasions.
  44
  45 . CONFIG=NETSEND
  46   WANT_SMTP and WANT_SSL settings are enabled, internationalized domain
  47   names will be supported if the necessary libraries are available,
  48   otherwise identical to MEDIUM.
  49
  50   Sending messages directly to the mail provider via the SMTP protocol,
  51   instead of requiring a local mail-transfer-agent (MTA) who does.
  52
  53 . CONFIG=MAXIMAL
  54   Anything on.
  55
  56   S-nail(1) gains mail fetching capabilities and heads more toward being
  57   a full-featured mail-user-agent (MUA) with this.
  58
  59 E.g.:
  60
  61   $ make CONFIG=MINIMAL DESTDIR=xtest install
  62
  63 would create a `s-nail' binary and install a `s-nail' manual etc.
  64 under the prefix `/usr/local' but rooted under [./]`xtest', i.e., the
  65 binary would be installed as `[./]xtest/usr/local/bin/s-nail'.
  66 The following make(1) target exists, and note that you can use
  67 a VERBOSE=1 command line option to gain more (or a different kind of)
  68 verbosity:
  69
  70 . all         Create / check and update configuration, build.
  71 . install     Create / check and update configuration, build, install.
  72 . clean       Remove anything which can be rebuild.
  73 . distclean   Remove anything which can be rebuild or reconfigured.
  74 . uninstall   Uninstall (if configured).
  75
  76 . config      Only create or check and update the configuration.
  77 . build       Only build (using the existing configuration).
  78 . test        Run ./cc-test.sh in --check-only mode on the built binary.
  79 . packager-install
  80               Only install using the built files of the existing
  81               configuration.  It is possible to overwrite DESTDIR= when
  82               using this target nonetheless (a following `uninstall'
  83               won't know about that overwritten value, however).
  84
  85 If some libraries are missing that you know are installed on your
  86 system, or if other errors occur due to missing files but which you know
  87 exist, please ensure that the environment variable `C_INCLUDE_PATH'
  88 includes the necessary `include/' paths and the environment variable
  89 `LD_LIBRARY_PATH' includes the necessary `lib/'rary paths.
  90
  91 The S-nail make system will inspect these two environment variables and
  92 *automatically* convert them to cc(1) (c99(1)) -I and -L options (since
  93 these environment variables are, different to the command line options,
  94 not part of the POSIX standard).
  95 To set these environment variables, the following can be done in
  96 a Bourne/Korn/POSIX compatible shell:
  97
  98   $ C_INCLUDE_PATH="${C_INCLUDE_PATH}:/usr/local/include"
  99   $ LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib"
 100   $ export C_INCLUDE_PATH LD_LIBRARY_PATH
 101   $ make install
 102
 103 The S-nail make system will also automatically integrate pkgsrc(7) paths
 104 into this mechanism.  pkgsrc(7) is used to handle building (compilation),
 105 installation and removal of software packages on a lot of operating
 106 systems, including all BSD systems, Linux, Solaris ...
 107
 108 2. Notes for S-nail(1) v14.7*
 109 -----------------------------
 110
 111 S-nail(1) has been or is used regulary on these systems (`uname -srm').
 112 It is assumed that S-nail(1) should work practically everywhere.
 113
 114 . All 32-bit systems:
 115   - There _may_ be warnings about format strings, like, e.g.,
 116       auxlily.c:1610:10: warning: format '%lu' expects type 'long
 117       unsigned int', but argument 3 has type 'size_t'
 118     The S-nail codebase is ISO C89, so we have no %z printf(3) format.
 119     However, `nail.h' tries hard to detect the real type size and
 120     defines the `ZFMT' macro which ends up with the correct real size,
 121     which is compile-time asserted via __ZFMT_CTA() in main.c.
 122
 123 . Mac OS X <https://www.apple.com/>
 124   (Snow Leopard) Darwin 10.8.0 i386
 125   - gcc-mp-4.8 (MacPorts gcc48 4.8.2_0) 4.8.2.
 126     + The known -Wstrict-overflow warnings (this code is address of
 127       change in v14.8)
 128   - clang version 3.4 (branches/release_34 197314)
 129     Target: x86_64-apple-darwin10.8.0
 130     Thread model: posix.
 131   - i686-apple-darwin10-gcc-4.2.1 (GCC) 4.2.1 (Apple Inc. build 5666)
 132     (dot 3).
 133   - Apple clang version 1.7 (tags/Apple/clang-77) (based on LLVM
 134     2.9svn).
 135
 136 . ArchLinux <https://www.archlinux.org/>
 137   Linux 3.15.5-1-ARCH x86_64
 138   - gcc (GCC) 4.9.0 20140604 (prerelease) [gcc 4.9.0-5]
 139     + I think faulty message on longjmp() clobbering on a const variable?
 140     + The known -Wstrict-overflow warnings (this code is address of
 141       change in v14.8)
 142
 143 . CRUX Linux <http://www.crux.nu/>
 144   CRUX 3.1 (rc1) Linux 3.12.17 x86_64.
 145   - gcc (CRUX) 4.8.2.
 146     + The known -Wstrict-overflow warnings (this code is address of
 147       change in v14.8)
 148     + (The HOT BEVERAGE error doesn't occur, even today.)
 149
 150   CRUX 3.0 Linux 3.6.11 #1 SMP Sun Sep 15 17:47:31 UTC 2013 x86_64.
 151   - gcc (CRUX-x86_64-multilib) 4.7.2.
 152     + For rememberance:
 153       In a very special test mailbox the character `☕' (U+2615 HOT
 154       BEVERAGE) is displayed as `[3m<98><95>' (`set PAGER='cat -vet''
 155       prints `M-bM-^XM-^U').  Because this is the only system i have
 156       seen this, and only in this single mailbox, i suspect a problem
 157       in the character conversion environment.  (I hope v14.888888888ngs
 158       sole usage of mbrtowc(3) instead of mbtowc(3) and per-message
 159       multibyte states.  Let's see if that fixes this problem.  I'll
 160       keep the VM around.)
 161
 162 . Void Linux <http://www.voidlinux.eu/>
 163   Linux 3.10.19_1 i686.
 164   - gcc (GCC) 4.7.3.
 165     + A single warning on 'signed overflow'.
 166     + `devel'opment target: warnings on format strings -- as above.
 167
 168 . NetBSD <https://www.netbsd.org/>
 169   NetBSD 6.99.40 i386 (201404092030Z)
 170   - gcc (NetBSD nb2 20140304) 4.8.3
 171     + Warnings on format strings -- as above.
 172     + Faulty message on longjmp() clobbering (on a const variable).
 173
 174   NetBSD 6.99.24 NetBSD 6.99.24 (GENERIC) #0: Tue Oct 29 08:23:21 UTC
 175   2013 amd64.
 176   - gcc (NetBSD nb1 20120916) 4.5.4.
 177     + Faulty message on longjmp() clobbering (on a const variable).
 178
 179   NetBSD 6.?
 180   - Ok.
 181
 182 . FreeBSD <https://www.freebsd.org/>
 183   FreeBSD 10.0-STABLE #0 r268038: Mon Jun 30 17:00:39 UTC 2014
 184   - FreeBSD clang version 3.4.1 (tags/RELEASE_34/dot1-final 208032) 20140512
 185
 186 . DragonFly BSD <https://www.dragonflybsd.org/>
 187   DragonFly 3.6-RELEASE x86_64
 188   - gcc 4.7.3 [DragonFly] Release/2013-04-11.
 189     + A single warning on 'signed overflow'.
 190     + Harmless iconv(3) warning again (as if we didn't have had to
 191       treat it specially already).
 192
 193 . OpenBSD <http://www.openbsd.org/>
 194   OpenBSD 5.6 (current as of 2014-05-25) i386,
 195   OpenBSD 5.4 i386.
 196   - gcc (GCC) 4.2.1 20070719.
 197     + Faulty message on longjmp() clobbering (on a const variable).
 198
 199 . UnixWare 7.1.4.
 200   + Note: it is no longer possible to use the `install' rule -- mk-mk.in
 201     uses shell functions to ease the task of directory creation etc.
 202     (especially useful due to VERBOSE=), and that won't work due to bugs.
 203   + You'll see some harmless and ignorable warnings (the problematic
 204     looking warning `"openssl.c", line 88: initialization type mismatch'
 205     refers to a cast from non-const to const, which shouldn't matter).
 206
 207 3. Current codebase state
 208 -------------------------
 209
 210 Since i've forked Heirloom mailx(1) (for real) as S-nail(1) on
 211 2012-09-18 i make my way through the codebase, and i'm getting more
 212 and more used to it as time goes by -- of course, i'm thinking object
 213 and thus this codebase and i are antipodes.
 214 I'll hope to be able to release S-nail v20 on 2018-03-25, the 40th
 215 anniversary of Berkeley Mail, as a good one.  Also see `TODO'.
 216
 217 For S-nail, v15.0 (not before 2016) is dedicated to a Send- and
 218 MIME-layer rewrite that will bring the possibility to access each
 219 message part individually. Because the Berkeley codebase and its nail
 220 fork have design flaws in respect to mailbox handling and non-local code
 221 jumps (due to / and signals), whereas the (MIME capable) NetBSD and
 222 OpenBSD forks have instead addressed this problem, more or less
 223 complete, in one or the other way, v15.0 will also have to address
 224 signal handling, because only like that we have the possibility to ever
 225 reach a clean state from which we can actually think about re-extending
 226 this MUA. It is not unlikely that IMAP support will be dropped
 227 temporarily, leaving only the plain mailx(1) plus Maildir, SMTP and POP3
 228 functionality. It has to move under the headline reduce to the max.
 229
 230 # s-ts-mode