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 With utility program and feature adjustments:
  27
  28   $ awk=/usr/bin/nawk make WANT_SOCKETS=no DESTDIR=./zzz install
  29
  30 There are also some predefined restricted configuration sets available,
  31 which take precedence over anything else:
  32
  33 . CONFIG=MINIMAL
  34   This is the most plain mailx(1)-alike mode, but with MIME support and
  35   (if available) character set conversion and regular expressions
  36   builtin (here mostly ment for mailing list matching).  That's it.
  37
  38 . CONFIG=MEDIUM
  39   Like MINIMAL, but with documentation strings, the builtin command line
  40   editor with history support (if possible), basic colour support and
  41   IDNA addresses.  Also adds in generic spam filter support.
  42
  43   Possibly what people want who need nothing but a MIME-capable mailx(1)
  44   and don't regret improved usability for the rare interactive use
  45   occasions.
  46
  47 . CONFIG=NETSEND
  48   WANT_SMTP as a requirement.
  49   NETSEND also tries to add SSL/TLS, GSSAPI, .netrc file parsing as well
  50   as external password *agent-lookup* on top of MEDIUM, on the other
  51   hand spam filter support is removed.
  52
  53   Sending messages directly to the mail provider via the SMTP protocol,
  54   instead of requiring a local mail-transfer-agent (MTA) who does.
  55
  56 . CONFIG=MAXIMAL
  57   Anything on (though none of which as a requirement).
  58
  59   S-nail(1) gains mail fetching capabilities and heads more toward being
  60   a full-featured mail-user-agent (MUA) with this.
  61
  62 E.g.:
  63
  64   $ make CONFIG=MINIMAL DESTDIR=./xtest install
  65
  66 would create a `s-nail' binary and install a `s-nail' manual etc.
  67 under the prefix `/usr/local' but rooted under [./]`xtest', i.e., the
  68 binary would be installed as `[./]xtest/usr/local/bin/s-nail'.
  69 The following make(1) target exists:
  70
  71 . all         Create / check and update configuration, build.
  72 . install     Create / check and update configuration, build, install.
  73 . clean       Remove anything which can be rebuild.
  74 . distclean   Remove anything which can be rebuild or reconfigured.
  75 . uninstall   Uninstall (if configured).
  76
  77 . config      Only create or check and update the configuration.
  78 . build       Only build (using the existing configuration).
  79 . test        Run ./cc-test.sh in --check-only mode on the built binary.
  80 . packager-install
  81               Only install using the built files of the existing
  82               configuration.  It is possible to overwrite DESTDIR= when
  83               using this target nonetheless (a following `uninstall'
  84               won't know about that overwritten value, however).
  85
  86 Setting the make(1) variable `VERBOSE' to an arbitrary value, as in
  87 "$ make VERBOSE=xy install", will change the output of the build,
  88 install etc. processes to a different, more verbose one.
  89 If some libraries are missing that you know are installed on your
  90 system, or if other errors occur due to missing files but which you know
  91 exist, please ensure that the environment variable `C_INCLUDE_PATH'
  92 includes the necessary `include/' paths and the environment variable
  93 `LD_LIBRARY_PATH' includes the necessary `lib/'rary paths.
  94
  95 The S-nail make system will inspect these two environment variables and
  96 *automatically* convert them to cc(1) (c99(1)) -I and -L options (since
  97 these environment variables are, different to the command line options,
  98 not part of the POSIX standard).
  99 To set these environment variables, the following can be done in
 100 a Bourne/Korn/POSIX compatible shell:
 101
 102   $ C_INCLUDE_PATH="${C_INCLUDE_PATH}:/usr/local/include"
 103   $ LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib"
 104   $ export C_INCLUDE_PATH LD_LIBRARY_PATH
 105   $ make install
 106
 107 The S-nail make system will also automatically integrate pkgsrc(7) paths
 108 into this mechanism.  pkgsrc(7) is used to handle building (compilation),
 109 installation and removal of software packages on a lot of operating
 110 systems, including all BSD systems, Linux, Solaris ...
 111 And if all else fails you can also pass in prefilled $LIBS and $INCS:
 112
 113   $ INCS=-I/mypath/lib LIBS=-l/mypath/iconv make install
 114
 115 1.1 How can i enable debugging?
 116 -------------------------------
 117
 118 Please ensure WANT_DEBUG=yes is enabled during compilation, as in
 119
 120   $ make CONFIG=MAXIMAL WANT_DEBUG=yes
 121
 122 If WANT_AUTOCC is enabled then the build system should automatically
 123 adjust the compiler flags accordingly, please see `make.rc' for more.
 124 There is also a `devel'opment target which does most of this by itself:
 125
 126   $ make devel
 127
 128 WANT_DEBUG (`devel') will enable memory bound debug canaries and
 129 Not-Yet-Dead function graph listings etc.  Whereas the latter will try
 130 to write its listing into a file named after your favourite MUA in your
 131 $TMPDIR, only falling back to STDERR shall such a file already exist,
 132 the debug facilities in general make their appearance on the standard
 133 error channel; because this can be a quite long output, then, it is
 134 possibly a good idea to redirect it to a file:
 135
 136   $ s-nail -dvv 2> error.log
 137
 138 Should you really discover any problems with S-nail it would be very
 139 useful for development if you would contact s-nail-users@!
 140 Thank you!
 141
 142 2. Special notes for the latest release
 143 ---------------------------------------
 144
 145 S-nail(1) has been or is used regulary on these systems (`uname -srm').
 146 Unless otherwise noted the following applies to saying "$ make" and
 147 "$ make devel" followed by "$ make test".
 148
 149 . All systems:
 150   - I've turned off -Wstrict-overflow warnings unless WANT_DEVEL is
 151     defined (talking about WANT_AUTOCC=yes here).  With gcc 5.1 the
 152     number of warnings exploded (for no user benefit).
 153   - You may see warnings on unused returns from write(2), ftruncate(2)
 154     and a few other I/O functions.  These will vanish after the large
 155     I/O and MIME rewrite that comes next.  They mostly refer to debug
 156     dumping, truncating a(n open) file to zero size and freopen(3)ing
 157     one of the standard channels.  I refrained from adding abort(3)
 158     calls as return value checks.
 159
 160 . All 32-bit systems:
 161   - There _may_ be warnings about format strings, like, e.g.,
 162       auxlily.c:1610:10: warning: format '%lu' expects type 'long
 163       unsigned int', but argument 3 has type 'size_t'
 164     The S-nail codebase is ISO C89, so we have no %z printf(3) format.
 165     However, `nail.h' tries hard to detect the real type size and
 166     defines the `PRI[du]Z' macros which end up with the correct size,
 167     which is compile-time asserted via PRIxZ_FMT_CTA() in `main.c'.
 168
 169     You can completely overcome this situation by forcing ISO C99 mode
 170     when compiling, e.g., with gcc(1) and clang(1): if you use
 171     WANT_AUTOCC then also pass "ADDCFLAGS=-std=c99", otherwise ensure
 172     -std=c99 is set in your $CFLAGS.
 173
 174 . ArchLinux <https://www.archlinux.org/>
 175   Linux 3.17.6-1-ARCH x86_64
 176   - gcc 5.1.0 [gcc 5.1.0-4]
 177     + False warning on "'gl.gl_group' may be used uninitialized".
 178       I had explicitly committed "Clarify condition (hopefully fix
 179       -Wmaybe-uninit, too), 2015-04-28" on [topic/gcc51], but it didn't
 180       help.
 181   - clang version 3.6.1 (tags/RELEASE_361/final) [clang-3.6.1-1]
 182     + :)
 183
 184 . Void Linux <http://www.voidlinux.eu/>
 185   Void GNU/Linux 3.19.3_1 i686
 186   - gcc (GCC) 4.9.2 [gcc-4.9.2_2]
 187     + Faulty message on longjmp() clobbering (of a const variable).
 188
 189 . CRUX Linux <http://www.crux.nu/>
 190   CRUX 3.1 (rc1) Linux 3.12.17 x86_64.
 191   - gcc (CRUX) 4.8.2.
 192     + :)
 193
 194 . FreeBSD <https://www.freebsd.org/>
 195   FreeBSD 10.1-RELEASE amd64
 196   - FreeBSD clang version 3.4.1 (tags/RELEASE_34/dot1-final 208032) 20140512
 197     + :)
 198
 199 . OpenBSD <http://www.openbsd.org/>
 200   OpenBSD 5.7-current (GENERIC) #753: Thu Mar 26 14:56:52 MDT 2015
 201   - gcc (GCC) 4.2.1 20070719.
 202     + Faulty message on longjmp() clobbering (of a const variable).
 203
 204 . DragonFly BSD <https://www.dragonflybsd.org/>
 205   DragonFly 4.0-RELEASE x86_64 [4.0.5]
 206   - gcc 4.7.4 [DragonFly] Release/2014-06-12
 207     + I will never get iconv(3) right for DragonFly it seems.
 208
 209 . NetBSD <https://www.netbsd.org/>
 210   + Show work.
 211
 212 . Mac OS X <https://www.apple.com/>
 213   (Snow Leopard) Darwin 10.8.0 i386
 214   + Worked a thousand hours.
 215   - gcc-mp-4.8 (MacPorts gcc48 4.8.2_0) 4.8.2.
 216   - clang version 3.4 (branches/release_34 197314)
 217     Target: x86_64-apple-darwin10.8.0
 218     Thread model: posix.
 219   - i686-apple-darwin10-gcc-4.2.1 (GCC) 4.2.1 (Apple Inc. build 5666)
 220     (dot 3).
 221   - Apple clang version 1.7 (tags/Apple/clang-77) (based on LLVM
 222     2.9svn).
 223
 224 . Solaris <http://opencsw.org/>
 225   * First of all: thanks to OpenCSW.org for offering SSH access to
 226     their Solaris build cluster!
 227   - According to standards(5) we require the /usr/xpg4 environment, and
 228     will bail if we cannot find it.
 229   - I couldn't get us going on SunOS 5.9: the build system had to be
 230     extended to check for UINTPTR_MAX being defined as the empty string
 231     and similar very special things.
 232   - With WANT_AUTOCC: we try to use Sun cc(1) whenever we find it.
 233     If your gcc(1) installation is doing alright you have to turn
 234     WANT_AUTOCC off and use $CC, $CFLAGS and $LDFLAGS.
 235   - I will never get iconv(3) right for Solaris it seems.
 236   - In order to be able to run the tests you will need a cksum that
 237     supports CRC-32 (POSIX).  We look into /opt/csw/gnu/cksum, but if
 238     that cannot be found you have to adjust the $cksum variable (see
 239     above) to something that works.  (A future version of S-nail will
 240     use different testing, but until then: Sorry!)
 241   SunOS 5.10 Generic_150400-17 sun4v sparc SUNW,SPARC-Enterprise-T5220
 242   - gcc (GCC) 3.4.3 (csl-sol210-3_4-branch+sol_rpath)
 243     + A lot of warnings on longjmp() clobbering.
 244     + S/MIME tests fail with "OpenSSL 1.0.1j 15 Oct 2014 (Library:
 245       OpenSSL 1.0.1m 19 Mar 2015)":
 246         behave:s/mime:sign/verify:
 247         Error creating the PKCS#7 signing object: \
 248           error:21083097:lib(33):func(131):reason(151)
 249   SunOS 5.10 Generic_150400-17 sun4v sparc SUNW,SPARC-Enterprise-T5220
 250   - cc: Sun C 5.9 SunOS_sparc Patch 124867-16 2010/08/11
 251     + Some harmless warnings.
 252     + S/MIME tests fail with "OpenSSL 1.0.1m 19 Mar 2015":
 253         behave:s/mime:sign/verify:
 254         Error creating the PKCS#7 signing object: \
 255           error:21083097:lib(33):func(131):reason(151)
 256   SunOS 5.10 Generic_147441-19 i86pc i386 i86pc
 257   - cc: Sun C 5.9 SunOS_i386 Patch 124868-15 2010/08/11
 258     + Some harmless warnings.
 259   SunOS 5.11 11.2 sun4u sparc SUNW,SPARC-Enterprise
 260   - (GCC) 4.9.2
 261     + We forcefully disable stack protectors on SunOS/gcc because of
 262       linking errors:
 263         Undefined                       first referenced
 264          symbol                             in file
 265         __stack_chk_fail                    accmacvar.o
 266         __stack_chk_guard                   accmacvar.o
 267         ld: fatal: symbol referencing errors
 268     + Quite some (false) warnings on maybe-uninitialized.
 269   SunOS 5.11 11.0 i86pc i386 i86pc
 270   - gcc (GCC) 4.9.2
 271     + If you get the compiler / system header installation error
 272         Undefined                       first referenced
 273          symbol                             in file
 274         __builtin_stdarg_start              auxlily.o
 275       then you have to overwrite this symbol with __builtin_va_start,
 276       e.g., in conjunction with WANT_AUTOCC add this:
 277        ADDCFLAGS='-D__builtin_stdarg_start=__builtin_va_start'
 278
 279 . UnixWare 7.1.4.
 280   + Note: it is no longer possible to use the `install' rule -- mk-mk.in
 281     uses shell functions to ease the task of directory creation etc.
 282     (especially useful due to VERBOSE=), and that won't work due to bugs
 283     (in the system make(1) program i presume).
 284   + You'll see some harmless and ignorable warnings.
 285
 286 3. Current codebase state
 287 -------------------------
 288
 289 Since i've forked Heirloom mailx(1) (the former "nail" for real) as
 290 S-nail(1) on 2012-09-18 i make my way through the codebase, and i'm
 291 getting more and more used to it as time goes by -- of course, i'm
 292 thinking object and thus this codebase and i are antipodes.
 293 I'll hope to be able to release S-nail v20 on 2018-03-25, the 40th
 294 anniversary of Berkeley Mail, as a good one.  Also see `TODO'.
 295
 296 For S-nail, v15.0 (not before 2017) is dedicated to a Send- and
 297 MIME-layer rewrite that will bring the possibility to access each
 298 message part individually. Because the Berkeley codebase and its nail
 299 fork have design flaws in respect to mailbox handling and non-local code
 300 jumps (due to / and signals), whereas the (MIME capable) NetBSD and
 301 OpenBSD forks have instead addressed this problem, more or less
 302 complete, in one or the other way, v15.0 will also have to address
 303 signal handling, because only like that we have the possibility to ever
 304 reach a clean state from which we can actually think about re-extending
 305 this MUA. It is not unlikely that IMAP support will be dropped
 306 temporarily, leaving only the plain mailx(1) plus Maildir, SMTP and POP3
 307 functionality. It has to move under the headline reduce to the max.
 308
 309 # s-ts-mode