INSTALL

   1 I n s t a l l i n g  S - n a i l / S - m a i l x
   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.  Notes on building the latest release
   9
  10 1. Compilation
  11 --------------
  12
  13 System specific notes can be found in the next section.
  14 All (optional) features are documented (and adjustable) in make.rc.
  15 Adjustments may also take place, and are usually done, from the command
  16 line, overriding those made in make.rc (if any).
  17 Without any adjustments all non-experimental features will be enabled,
  18 except some which provide redundant functionality (e.g., OPT_SPAMC is
  19 disabled because the generic OPT_SPAM_FILTER can do the same).
  20 None of the features are "require"d by default, so that configuration
  21 won't fail shall any of them not be available or usable.
  22
  23   $ make tangerine  # equals "$ make config build test install"
  24   $ make distclean  # *Completely* cleanup working directory
  25
  26 With adjustments:
  27
  28   $ make OPT_POP3=no OPT_SMTP=require tangerine
  29   $ make OPT_CROSS_BUILD=y VAL_PREFIX=/some/nasty/prefix tangerine
  30
  31 With utility program and feature adjustments:
  32
  33   $ make awk=/usr/bin/nawk OPT_SOCKETS=no DESTDIR=./zzz tangerine
  34
  35 If OPT_DOTLOCK has been enabled then the minimal privilege-separated
  36 SETUID (to VAL_PRIVSEP_USER, default "root") helper program will be build
  37 and installed, and therefore the installation process needs to have the
  38 appropriate privileges.  In this case it may be useful to separate the
  39 configuration / building and the installation tasks and give the last
  40 step higher privileges via super(1), sudo(1), su(1) or a similar
  41 mechanism, e.g.:
  42
  43   $ make VAL_PREFIX=/usr config && make MAILJOBS='-j 4' &&
  44     super make DESTDIR=./xy install
  45
  46 would create a "s-nail" binary and install a "s-nail" manual etc.  under
  47 the prefix "/usr" but rooted under "[./]xy", i.e., the binary would be
  48 installed as "[./]xy/usr/bin/s-nail".
  49 The following make(1) targets exists, the default being `build':
  50
  51 - tangerine   Shorthand for "$ make config build test install":
  52               create or check and update configuration, build, test and
  53               install.
  54               The variable $DESTDIR will be honoured (see make.rc),
  55               but not be tracked in the configuration.
  56               In order to parallelize the `build' step pass a $MAILJOBS
  57               variable, as shown below.
  58 - all         Shorthand for "$ make config build".
  59               In order to parallelize the `build' step pass a $MAILJOBS
  60               variable, as shown below.
  61
  62 - config      Only create or check and update the configuration.
  63 - build       Only build (using the existing configuration).
  64               This can be parallelized, either by a corresponding make(1)
  65               invocation when the target is run by itself, or by setting
  66               the $MAILJOBS variable otherwise, e.g., "MAILJOBS='-j 4'".
  67               $MAILJOBS is not tracked in the configuration.
  68 - install     Only install using the built files of the existing
  69               configuration.
  70               The variable $DESTDIR will be honoured (see make.rc),
  71               but not be tracked in the configuration.
  72
  73 - clean       Remove anything which can be rebuild.
  74 - distclean   Remove anything which can be rebuild or reconfigured.
  75
  76 - test        Run cc-test.sh in --check-only mode on the built binary.
  77
  78 Setting the make(1) variable $VERBOSE to an arbitrary value during
  79 `config' time, as in "$ make VERBOSE=xy tangerine", will change the
  80 output of the `all', `install' etc. targets to a more verbose one.
  81 If some libraries are missing that you know are installed on your
  82 system, or if other errors occur due to missing files but which you know
  83 exist, please ensure that the environment variable $C_INCLUDE_PATH
  84 includes the necessary "include/" paths and the environment variable
  85 $LD_LIBRARY_PATH includes the necessary "lib/"rary paths.
  86
  87 The S-nail make system will inspect these two environment variables and
  88 *automatically* convert them to cc(1) (c99(1)) -I and -L options (since
  89 these environment variables are, different to the command line options,
  90 not part of the POSIX standard).
  91 To set these environment variables, the following can be done in
  92 a Bourne / Korn / POSIX compatible shell:
  93
  94   $ C_INCLUDE_PATH="${C_INCLUDE_PATH}:/usr/local/include"
  95   $ LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib"
  96   $ export C_INCLUDE_PATH LD_LIBRARY_PATH
  97   $ make tangerine
  98
  99 The S-nail make system will also automatically integrate pkgsrc(7) paths
 100 into this mechanism.  (pkgsrc(7) is a portable package management system
 101 that is used as a default on diverse operating systems.)
 102 And if all else fails you can also forcefully pass in include directives
 103 and library paths by passing prefilled $INCS and $LIBS variables:
 104
 105   $ make INCS=-I/mypath/lib LIBS=-l/mypath/iconv tangerine
 106
 107 Note there are also some predefined configuration sets available, ment
 108 to be used instead of doing manual adjustments (in make.rc or) on the
 109 command line (names are case-insensitive):
 110
 111 - CONFIG=NULL, CONFIG=NULLI
 112   Anything that can be turned off is off.  MIME can't.
 113   The latter adds and "require"s iconv(3), though.
 114
 115 - CONFIG=MINIMAL
 116   This is the most plain mailx(1)-alike mode, but with MIME support and
 117   (if available) character set conversion and regular expressions
 118   builtin.  Dotlock files and the privileged separated dotlock helper.
 119
 120   "Require"s dotlocking and the privileged separated dotlock helper.
 121
 122 - CONFIG=MEDIUM
 123   Possibly what people want who need nothing but a MIME-capable mailx(1)
 124   and don't regret improved usability for the rare interactive use
 125   occasions.
 126
 127   Like MINIMAL, but with documentation strings, the builtin line editor
 128   (MLE) with history support and key bindings, error tracking, basic
 129   colour support and IDNA addresses.
 130
 131   "Require"s iconv(3), dotlocking and the privileged separated dotlock
 132   helper.
 133
 134 - CONFIG=NETSEND
 135   Sending messages directly to the mail provider via the SMTP protocol,
 136   instead of requiring a local mail-transfer-agent (MTA) who does.
 137
 138   Adds SSL/TLS, GSSAPI and .netrc file parsing on top of MEDIUM, on the
 139   other hand spam filter support is removed.
 140
 141   "Require"s iconv(3), SSL/TLS, SMTP (sockets), dotlocking and the
 142   privileged separated dotlock helper.
 143
 144 - CONFIG=MAXIMAL
 145   Anything on, including experimental features.
 146   S-nail(1) gains mail fetching capabilities and heads more towards
 147   being a full-featured mail-user-agent (MUA) with this configuration.
 148
 149   "Require"s iconv(3), regex(3), the MLE as well as dotlocking and the
 150   privileged separated dotlock helper.
 151
 152 1.1 What if configuration fails?
 153 --------------------------------
 154
 155 The configuration process creates some files named "config":
 156
 157 - config.log  output generated by the configuration compile tests.
 158 - config.lst  configuration (chosen option, programs, paths).
 159               (Removing this file reenables configuration even after
 160               a screwed up configuration, e.g., due to power failure.)
 161 - config.h    C program header produced according to config.lst.
 162 - config.ev   A set of sh(1) variable for reproducable compile runs.
 163 - config.inc  List of C header include paths, as compiler directives.
 164 - config.lib  List of used library information, as compiler directives.
 165
 166 Of special interest is config.log since the error usually manifests here
 167 in textual output.  Maybe that makes it obvious what can be done (header
 168 files could not be found because of missing entries in $C_INCLUDE_PATH,
 169 libraries could not be linked because of incomplete $LD_LIBRARY_PATH,
 170 etc.).
 171 Otherwise it is getting complicated, and it would be appreciated if you
 172 would contact the mailing-list!
 173
 174 1.2 What if building fails?
 175 ---------------------------
 176
 177 Even worse!  This should not happen if configuration succeeded!  It
 178 would be very kind and highly appreciated if you would report this
 179 to the mailing-list.
 180
 181 1.3 How can i enable debugging?
 182 -------------------------------
 183
 184 Please ensure OPT_DEBUG=yes is enabled during compilation, as in
 185
 186   $ make CONFIG=MAXIMAL OPT_DEBUG=yes
 187
 188 If $OPT_AUTOCC is enabled then the build system should automatically
 189 adjust the compiler flags accordingly, please see make.rc for more.
 190 There is also a `devel'opment target which does most of this by itself:
 191
 192   $ make devel
 193
 194 $OPT_DEBUG (`devel') will enable memory bound debug canaries and
 195 Not-Yet-Dead function graph listings etc.  Whereas the latter will try
 196 to write its listing into a file named after your favourite MUA in
 197 your $TMPDIR (or "/tmp" or "./", in order), falling back to STDERR shall
 198 creation of the file not be possible (we won't overwrite an existing
 199 file), the debug facilities in general make their appearance on the
 200 standard error channel; because this can be a quite long output, then,
 201 it is possibly a good idea to redirect it to a file:
 202
 203   $ s-nail -dvv 2> error.log
 204
 205 Should you really discover any problems with S-nail it would be very
 206 useful for development if you would contact the mailing-list!
 207 Thank you!
 208
 209 2. Notes on building the latest release
 210 ---------------------------------------
 211
 212 This software has been in use or is used on a regulary basis on FreeBSD
 213 and Linux.  Occasional tests happens on the remains of the following.
 214 Unless otherwise noted the following applies to saying
 215 "$ make tangerine; make devel && make test".
 216 In alphabetical order:
 217
 218 - All systems:
 219   * I've turned off -Wstrict-overflow warnings unless we're debug
 220     enabled (talking about OPT_AUTOCC=yes here).
 221   * You will likely see warnings on unused returns from write(2),
 222     ftruncate(2) and a few other I/O functions.  These will vanish after
 223     the large I/O and MIME rewrite that comes with v15.
 224   * I am using the latest gcc(1) and clang(1) compilers, and am doing
 225     scan-build(1) and Coverity.com inspection before major releases.
 226     Some "XYZ may be used uninitialized" warnings are logically false.
 227
 228 - All 32-bit systems:
 229   * There _may_ be warnings about format strings, like, e.g.,
 230       auxlily.c:1610:10: warning: format '%lu' expects type 'long
 231       unsigned int', but argument 3 has type 'size_t'
 232     The codebase is ISO C89, so we have no %z printf(3) format.
 233     However we try hard to detect the real type size and define the
 234     "PRI[du]Z" macros which end up with the correct size, which is
 235     also compile-time asserted (see the "MCTA(sizeof(size_t) == XZ)"
 236     statements in nail.h).
 237
 238     You can completely overcome this situation by forcing ISO C99 mode
 239     when compiling, e.g., with gcc(1) and clang(1): if you use
 240     $OPT_AUTOCC then also pass "EXTRA_CFLAGS=-std=c99", otherwise
 241     ensure -std=c99 is set in your $CFLAGS.
 242
 243 . AlpineLinux <https://www.alpinelinux.org/>
 244   AlpineLinux 3.4.3, gcc(1).
 245
 246 . ArchLinux <https://www.archlinux.org/>
 247   Latest as of 2016-09-16, clang(1) and gcc(1).
 248
 249 . CRUX Linux <https://www.crux.nu/>
 250   CRUX 3.2 RC3, gcc(1).
 251
 252 . DragonFly BSD <https://www.dragonflybsd.org/>
 253   DragonFly 4.6.0, gcc(1).
 254   * I will never get iconv(3) right for Solaris it seems.
 255
 256 - FreeBSD <https://www.freebsd.org/>
 257   FreeBSD 10.3, clang(1).
 258
 259 - NetBSD <https://www.netbsd.org/>
 260   Not tested.
 261
 262 . OpenBSD <https://www.openbsd.org/>
 263   OpenBSD 5.9.
 264
 265 - Solaris <http://opencsw.org/>
 266   @ First of all: thanks to OpenCSW.org for offering SSH access to
 267     their Solaris build cluster!
 268   * In order to be able to run the tests you will need a cksum(1) that
 269     supports CRC-32 (POSIX).  We look into /opt/csw/gnu/cksum, but if
 270     that cannot be found you have to adjust the $cksum variable (see
 271     above) to something that works.
 272     (v15 will use a different test suite.)
 273   * With $OPT_AUTOCC: we try to use Sun cc(1) whenever we find it.
 274     If your gcc(1) installation is doing alright you have to turn
 275     $OPT_AUTOCC off and use $CC, $CFLAGS and $LDFLAGS.
 276   * I will never get iconv(3) right for Solaris it seems.
 277   * Some notes collected on earlier trials:
 278     + We may forcefully disable stack protectors on SunOS/gcc because of
 279       linking errors seen in earlier tests.
 280     + If you get the compiler / system header installation error
 281         Undefined                       first referenced
 282          symbol                             in file
 283         __builtin_stdarg_start              auxlily.o
 284       then you have to overwrite this symbol with __builtin_va_start,
 285       e.g., in conjunction with $OPT_AUTOCC add this:
 286        EXTRA_CFLAGS='-D__builtin_stdarg_start=__builtin_va_start'
 287     + I couldn't get us going on SunOS 5.9 Sparc: the build system had
 288       to be extended to check for UINTPTR_MAX being defined as the empty
 289       string and similar very special things.
 290   - The OpenCSW build cluster consists of SunOS 5.9 - 5.11 machines
 291     under SPARC and i386.
 292     It looked good on 2016-09-16.
 293
 294 - UnixWare 7.1.4.
 295   * Note: it is no longer possible to use the `install' rule, because
 296     we use shell functions to ease the task of directory creation etc.
 297     (especially useful due to $VERBOSE), and that won't work due to bugs
 298     (in the system make(1) program i presume).
 299   + Not tested after v14.8.4, just fine before that.
 300
 301 . Void Linux <http://www.voidlinux.eu/>
 302   Not yet tested for v14.9.0.
 303   (My current working environment is restricted since i've lost
 304   my main development machine.)
 305
 306 # s-ts-mode