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