INSTALL

   1 I n s t a l l i n g  S - n a i l
   2 ================================
   3
   4 1.  Compilation
   5 1.1 How can i enable debugging?
   6 2.  Special notes for the latest release
   7 3.  Current codebase state
   8
   9 1. Compilation
  10 --------------
  11
  12 System specific notes can be found in the next section.
  13 Any (optional) feature is adjustable and documented in `make.rc'.
  14 Adjustments may also take place, and are usually done, from the command
  15 line, overriding those made in `make.rc' (if any):
  16
  17   $ [make &&] make install
  18   $ make uninstall          # Won't remove the system wide startup file!
  19   $ make distclean          # *Completely* cleanup working directory
  20
  21 With adjustments:
  22
  23   $ make WANT_IMAP=no WANT_SMTP=require install
  24   $ make WANT_NCL=false PREFIX=/some/nasty/prefix install
  25
  26 There are also some predefined restricted configuration sets available,
  27 which take precedence over anything else:
  28
  29 . CONFIG=MINIMAL
  30   This is the most plain mailx(1)-alike mode, but with MIME support and
  31   (if available) character set conversion builtin.  That's it.
  32
  33 . CONFIG=MEDIUM
  34   Like MINIMAL, but with documentation strings, and regular expression
  35   support as well as the builtin command line editor will be included if
  36   that is possible, the latter with history but without tabulator
  37   expansion support.
  38
  39   Possibly what people want who need nothing but a MIME-capable mailx(1)
  40   and don't regret improved usability for the rare interactive use
  41   occasions.
  42
  43 . CONFIG=NETSEND
  44   WANT_SMTP as a requirement.
  45   NETSEND also tries to add SSL/TLS, GSSAPI, IDNA, .netrc file parsing
  46   as well as external password *agent-lookup*.
  47
  48   Sending messages directly to the mail provider via the SMTP protocol,
  49   instead of requiring a local mail-transfer-agent (MTA) who does.
  50
  51 . CONFIG=MAXIMAL
  52   Anything on (though none of which as a requirement).
  53
  54   S-nail(1) gains mail fetching capabilities and heads more toward being
  55   a full-featured mail-user-agent (MUA) with this.
  56
  57 E.g.:
  58
  59   $ make CONFIG=MINIMAL DESTDIR=xtest install
  60
  61 would create a `s-nail' binary and install a `s-nail' manual etc.
  62 under the prefix `/usr/local' but rooted under [./]`xtest', i.e., the
  63 binary would be installed as `[./]xtest/usr/local/bin/s-nail'.
  64 The following make(1) target exists, and note that you can use
  65 a VERBOSE=true command line option to gain more (or a different kind of)
  66 verbosity:
  67
  68 . all         Create / check and update configuration, build.
  69 . install     Create / check and update configuration, build, install.
  70 . clean       Remove anything which can be rebuild.
  71 . distclean   Remove anything which can be rebuild or reconfigured.
  72 . uninstall   Uninstall (if configured).
  73
  74 . config      Only create or check and update the configuration.
  75 . build       Only build (using the existing configuration).
  76 . test        Run ./cc-test.sh in --check-only mode on the built binary.
  77 . packager-install
  78               Only install using the built files of the existing
  79               configuration.  It is possible to overwrite DESTDIR= when
  80               using this target nonetheless (a following `uninstall'
  81               won't know about that overwritten value, however).
  82
  83 If some libraries are missing that you know are installed on your
  84 system, or if other errors occur due to missing files but which you know
  85 exist, please ensure that the environment variable `C_INCLUDE_PATH'
  86 includes the necessary `include/' paths and the environment variable
  87 `LD_LIBRARY_PATH' includes the necessary `lib/'rary paths.
  88
  89 The S-nail make system will inspect these two environment variables and
  90 *automatically* convert them to cc(1) (c99(1)) -I and -L options (since
  91 these environment variables are, different to the command line options,
  92 not part of the POSIX standard).
  93 To set these environment variables, the following can be done in
  94 a Bourne/Korn/POSIX compatible shell:
  95
  96   $ C_INCLUDE_PATH="${C_INCLUDE_PATH}:/usr/local/include"
  97   $ LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib"
  98   $ export C_INCLUDE_PATH LD_LIBRARY_PATH
  99   $ make install
 100
 101 The S-nail make system will also automatically integrate pkgsrc(7) paths
 102 into this mechanism.  pkgsrc(7) is used to handle building (compilation),
 103 installation and removal of software packages on a lot of operating
 104 systems, including all BSD systems, Linux, Solaris ...
 105 And if all else fails you can also pass in prefilled $LIBS and $INCS:
 106
 107   $ INCS=-I/mypath/lib LIBS=-l/mypath/iconv make install
 108
 109 1.1 How can i enable debugging?
 110 -------------------------------
 111
 112 Please ensure WANT_DEBUG=yes is enabled during compilation, as in
 113
 114   $ make CONFIG=MAXIMAL WANT_DEBUG=yes
 115
 116 If WANT_AUTOCC is enabled then the build system should automatically
 117 adjust the compiler flags accordingly, please see `make.rc' for more.
 118 There is also a `devel'opment target which does most of this by itself:
 119
 120   $ make devel
 121
 122 WANT_DEBUG (`devel') will enable memory bound debug canaries and
 123 Not-Yet-Dead function graph listings etc., all of which would give their
 124 appearance on the standard error channel; because this can be a quite
 125 long output, then, it is possibly a good idea to redirect it to a file:
 126
 127   $ s-nail -vv 2> error.log
 128
 129 Should you really discover any problems with S-nail it would be very
 130 useful for development if you would contact s-nail-users@!
 131 Thank you!
 132
 133 2. Special notes for the latest release
 134 ---------------------------------------
 135
 136 S-nail(1) has been or is used regulary on these systems (`uname -srm').
 137 It is assumed that S-nail(1) should work practically everywhere.
 138
 139 . All 32-bit systems:
 140   - There _may_ be warnings about format strings, like, e.g.,
 141       auxlily.c:1610:10: warning: format '%lu' expects type 'long
 142       unsigned int', but argument 3 has type 'size_t'
 143     The S-nail codebase is ISO C89, so we have no %z printf(3) format.
 144     However, `nail.h' tries hard to detect the real type size and
 145     defines the `PRI[du]Z' macro which ends up with the correct size,
 146     which is also compile-time asserted via PRIxZ_FMT_CTA() in main.c.
 147
 148     You can completely overcome this situation by forcing ISO C99 mode
 149     when compiling, e.g., with gcc(1) and clang(1): if you use
 150     WANT_AUTOCC then also pass "ADDCFLAGS=-std=c99", otherwise ensure
 151     -std=c99 is set in your $CFLAGS.
 152
 153 . ArchLinux <https://www.archlinux.org/>
 154   Linux 3.16.3-1-ARCH x86_64
 155   - gcc (GCC) 4.9.1 20140903 (prerelease) [gcc-4.9.1-2-x86_64]
 156     + I think faulty message on longjmp() clobbering on a const variable?
 157     + The known -Wstrict-overflow warning(s) (this code is address of
 158       change in v14.8)
 159
 160 . CRUX Linux <http://www.crux.nu/>
 161   CRUX 3.1 (rc1) Linux 3.12.17 x86_64.
 162   - gcc (CRUX) 4.8.2.
 163     + :)
 164
 165 . Void Linux <http://www.voidlinux.eu/>
 166   Void GNU/Linux 3.14.15_2 i686
 167   - gcc (GCC) 4.9.1 [gcc-4.9.1_8]
 168     + Same notes as for ArchLinux (but with libressl-devel etc.)
 169
 170 . FreeBSD <https://www.freebsd.org/>
 171   FreeBSD 10.0-STABLE #0 r268038: Mon Jun 30 17:00:39 UTC 2014
 172   - FreeBSD clang version 3.4.1 (tags/RELEASE_34/dot1-final 208032) 20140512
 173     + :)
 174
 175 . OpenBSD <http://www.openbsd.org/>
 176   OpenBSD 5.6 GENERIC#337 (~2014-09-26) i386
 177   - gcc (GCC) 4.2.1 20070719.
 178     + Faulty message on longjmp() clobbering (on a const variable).
 179     + Wrong message on potentially uninitialized variable.
 180
 181 . DragonFly BSD <https://www.dragonflybsd.org/>
 182   DragonFly 3.6-RELEASE x86_64
 183   - gcc 4.7.3 [DragonFly] Release/2013-04-11.
 184     + One -Wstrict-overflow warning.
 185     + Warning on bad cast for iconv(3); yes, this is DragonFly.
 186
 187   DragonFly 3.4.1-RELEASE i386
 188   - gcc 4.7.2 [DragonFly] Release/2012-09-20
 189     + One -Wstrict-overflow warning.
 190
 191 . Mac OS X <https://www.apple.com/>
 192   (Snow Leopard) Darwin 10.8.0 i386
 193   - gcc-mp-4.8 (MacPorts gcc48 4.8.2_0) 4.8.2.
 194     + The known -Wstrict-overflow warnings (this code is address of
 195       change in v14.8)
 196   - clang version 3.4 (branches/release_34 197314)
 197     Target: x86_64-apple-darwin10.8.0
 198     Thread model: posix.
 199   - i686-apple-darwin10-gcc-4.2.1 (GCC) 4.2.1 (Apple Inc. build 5666)
 200     (dot 3).
 201   - Apple clang version 1.7 (tags/Apple/clang-77) (based on LLVM
 202     2.9svn).
 203
 204 . UnixWare 7.1.4.
 205   + Not tested with v14.7.7.
 206   + Note: it is no longer possible to use the `install' rule -- mk-mk.in
 207     uses shell functions to ease the task of directory creation etc.
 208     (especially useful due to VERBOSE=), and that won't work due to bugs
 209     (in the system make(1) program i presume).
 210   + You'll see some harmless and ignorable warnings (the problematic
 211     looking warning `"openssl.c", line 88: initialization type mismatch'
 212     refers to a cast from non-const to const, which shouldn't matter).
 213
 214 . NetBSD <https://www.netbsd.org/>
 215   NetBSD 6.99.40 i386 (201404092030Z)
 216   - gcc (NetBSD nb2 20140304) 4.8.3
 217     + S/MIME test verification fails (OpenSSL 1.0.1g 7 Apr 2014):
 218       the generated test mail is empty for unknown reason, resulting in
 219       "Error reading PKCS#7 object for message 1: error:0D0D40D1:asn1
 220       encoding routines:SMIME_read_ASN1:no content type".
 221     ++ It actually turns out this has to be a bug in the NetBSD StdIO
 222        library!!  I'll have to track this down...
 223
 224   NetBSD 6.99.24 amd64
 225   - gcc (NetBSD nb1 20120916) 4.5.4
 226     + I think faulty message on longjmp() clobbering on a const variable?
 227     + Wrong message on potentially uninitialized variable.
 228     + Same S/MIME issue!
 229
 230   NetBSD 6.0 i386
 231   - gcc (NetBSD nb2 20110806) 4.5.3
 232     + Same as 6.99.24 amd64.
 233     + Same S/MIME issue!
 234
 235 3. Current codebase state
 236 -------------------------
 237
 238 Since i've forked Heirloom mailx(1) (for real) as S-nail(1) on
 239 2012-09-18 i make my way through the codebase, and i'm getting more
 240 and more used to it as time goes by -- of course, i'm thinking object
 241 and thus this codebase and i are antipodes.
 242 I'll hope to be able to release S-nail v20 on 2018-03-25, the 40th
 243 anniversary of Berkeley Mail, as a good one.  Also see `TODO'.
 244
 245 For S-nail, v15.0 (not before 2016) is dedicated to a Send- and
 246 MIME-layer rewrite that will bring the possibility to access each
 247 message part individually. Because the Berkeley codebase and its nail
 248 fork have design flaws in respect to mailbox handling and non-local code
 249 jumps (due to / and signals), whereas the (MIME capable) NetBSD and
 250 OpenBSD forks have instead addressed this problem, more or less
 251 complete, in one or the other way, v15.0 will also have to address
 252 signal handling, because only like that we have the possibility to ever
 253 reach a clean state from which we can actually think about re-extending
 254 this MUA. It is not unlikely that IMAP support will be dropped
 255 temporarily, leaving only the plain mailx(1) plus Maildir, SMTP and POP3
 256 functionality. It has to move under the headline reduce to the max.
 257
 258 # s-ts-mode