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 The generated configuration is tracked: changes will be recognized
  23 and cause automatic cleanups and rebuilds as necessary.
  24
  25   $ make tangerine  # equals "$ make config build test install"
  26   $ make distclean  # *Completely* cleanup working directory
  27
  28 With adjustments:
  29
  30   $ make OPT_POP3=no OPT_SMTP=require tangerine
  31   $ make OPT_CROSS_BUILD=y VAL_PREFIX=/some/nasty/prefix tangerine
  32
  33 With utility program and feature adjustments:
  34
  35   $ make awk=/usr/bin/nawk OPT_SOCKETS=no DESTDIR=./zzz tangerine
  36
  37 If OPT_DOTLOCK has been enabled then the minimal privilege-separated
  38 SETUID (to VAL_PRIVSEP_USER, default "root") helper program will be build
  39 and installed, and therefore the installation process needs to have the
  40 appropriate privileges.  In this case it may be useful to separate the
  41 configuration / building and the installation tasks and give the last
  42 step higher privileges via super(1), sudo(1), su(1) or a similar
  43 mechanism, e.g.:
  44
  45   $ make VAL_PREFIX=/usr config && make MAKEJOBS='-j 4' &&
  46     super make DESTDIR=./xy install
  47
  48 would create a "s-nail" binary and install a "s-nail" manual etc.  under
  49 the prefix "/usr" but rooted under "[./]xy", i.e., the binary would be
  50 installed as "[./]xy/usr/bin/s-nail".
  51 The following make(1) targets exists, the default being `build':
  52
  53 - tangerine   Shorthand for "$ make config build test install":
  54               create or check and update configuration, build, test and
  55               install.
  56               The variable $DESTDIR will be honoured (see make.rc),
  57               but not be tracked in the configuration.
  58               In order to parallelize the `build' step pass a $MAKEJOBS
  59               variable, as shown below.
  60 - all         Shorthand for "$ make config build".
  61               In order to parallelize the `build' step pass a $MAKEJOBS
  62               variable, as shown below.
  63
  64 - config      Only create or check and update the configuration.
  65 - build       Only build (using the existing configuration).
  66               This can be parallelized, either by a corresponding make(1)
  67               invocation when the target is run by itself, or by setting
  68               the $MAKEJOBS variable otherwise, e.g., "MAKEJOBS='-j 4'".
  69               $MAKEJOBS is not tracked in the configuration.
  70 - install     Only install using the built files of the existing
  71               configuration.
  72               The variable $DESTDIR will be honoured (see make.rc),
  73               but not be tracked in the configuration.
  74
  75               S-nail will create an uninstall shell script
  76               (VAL_UAGENT-uninstall.sh), but which will *not* be installed
  77               if $DESTDIR is set non-empty -- within $DESTDIR, that is.
  78               Copy or move it manually from the S-nail root directory ./
  79               into $DESTDIR as necessary.
  80
  81 - clean       Remove anything which can be rebuild.
  82 - distclean   Remove anything which can be rebuild or reconfigured.
  83
  84 - test        Run cc-test.sh in --check-only mode on the built binary.
  85
  86 Setting the make(1) variable $VERBOSE to an arbitrary value during
  87 `config' time, as in "$ make VERBOSE=xy tangerine", will change the
  88 output of the `all', `install' etc. targets to a 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 tangerine
 106
 107 The S-nail make system will also automatically integrate pkgsrc(7) paths
 108 into this mechanism.  (pkgsrc(7) is a portable package management system
 109 that is used as a default on diverse operating systems.)
 110 And if all else fails you can also forcefully pass in include directives
 111 and library paths by passing prefilled $INCS and $LIBS variables:
 112
 113   $ make INCS=-I/mypath/lib LIBS=-l/mypath/iconv tangerine
 114
 115 Experts may find it valuable to adjust some settings in config.h.
 116 Note there are also some predefined configuration sets available, ment
 117 to be used instead of doing manual adjustments (in make.rc or) on the
 118 command line (names are case-insensitive):
 119
 120 - CONFIG=NULL, CONFIG=NULLI
 121   Anything that can be turned off is off.  MIME can't.
 122   The latter adds and "require"s iconv(3), though.
 123
 124 - CONFIG=MINIMAL
 125   This is the most plain mailx(1)-alike mode, but with MIME support and
 126   (if available) character set conversion and regular expressions
 127   built-in.  Dotlock files and the privileged separated dotlock helper.
 128
 129   "Require"s dotlocking and the privileged separated dotlock helper.
 130
 131 - CONFIG=MEDIUM
 132   Possibly what people want who need nothing but a MIME-capable mailx(1)
 133   and don't regret improved usability for the rare interactive use
 134   occasions.
 135
 136   Like MINIMAL, but with documentation strings, the built-in line editor
 137   (MLE) with history support and key bindings, error tracking, basic
 138   colour support and IDNA addresses.
 139
 140   "Require"s iconv(3), dotlocking and the privileged separated dotlock
 141   helper.
 142
 143 - CONFIG=NETSEND
 144   Sending messages directly to the mail provider via the SMTP protocol,
 145   instead of requiring a local mail-transfer-agent (MTA) who does.
 146
 147   Adds SSL/TLS, GSSAPI and .netrc file parsing on top of MEDIUM, on the
 148   other hand spam filter support is removed.
 149
 150   "Require"s iconv(3), SSL/TLS, SMTP (sockets), dotlocking and the
 151   privileged separated dotlock helper.
 152
 153 - CONFIG=MAXIMAL
 154   Anything on, including experimental features.
 155   S-nail(1) gains mail fetching capabilities and heads more towards
 156   being a full-featured mail-user-agent (MUA) with this configuration.
 157
 158   "Require"s iconv(3), regex(3), the MLE as well as dotlocking and the
 159   privileged separated dotlock helper.
 160
 161 1.1 What if configuration fails?
 162 --------------------------------
 163
 164 The configuration process creates some files named "mk-config.*":
 165
 166 - mk-config.log  output generated by the configuration compile tests.
 167 - mk-config.lst  configuration (chosen option, programs, paths).
 168                  (Removing this file reenables configuration even after
 169                  a screwed up configuration, e.g., due to power failure.)
 170 - mk-config.h    C program header produced according to mk-config.lst.
 171 - mk-config.ev   A set of sh(1) variable for reproducible compile runs.
 172 - mk-config.inc  List of C header include paths, as compiler directives.
 173 - mk-config.lib  List of used library information, as compiler directives.
 174
 175 Of special interest is mk-config.log since the error usually manifests
 176 here in textual output.  Maybe that makes it obvious what can be done
 177 (header files could not be found because of missing entries in
 178 $C_INCLUDE_PATH, libraries could not be linked because of incomplete
 179 $LD_LIBRARY_PATH, etc.).
 180
 181 Otherwise it is getting complicated, and it would be appreciated if you
 182 would contact the mailing-list!
 183
 184 If you hit an actual bug in the configuration system, and "make
 185 distclean" will not help you out, please "reset" the state by doing
 186 a simple "$ rm mk-*".
 187
 188 1.2 What if building fails?
 189 ---------------------------
 190
 191 Even worse!  This should not happen if configuration succeeded!  It
 192 would be very kind and highly appreciated if you would report this
 193 to the mailing-list.
 194
 195 1.3 How can i enable debugging?
 196 -------------------------------
 197
 198 Please ensure OPT_DEBUG=yes is enabled during compilation, as in
 199
 200   $ make CONFIG=MAXIMAL OPT_DEBUG=yes
 201
 202 If $OPT_AUTOCC is enabled then the build system should automatically
 203 adjust the compiler flags accordingly, please see make.rc for more.
 204 There is also a `devel'opment target which does most of this by itself:
 205
 206   $ make devel
 207
 208 $OPT_DEBUG (`devel') will enable memory bound debug canaries and
 209 Not-Yet-Dead function graph listings etc.  Whereas the latter will try
 210 to write its listing into a file named after your favourite MUA in
 211 your $TMPDIR (or "/tmp" or "./", in order), falling back to STDERR shall
 212 creation of the file not be possible (we won't overwrite an existing
 213 file), the debug facilities in general make their appearance on the
 214 standard error channel; because this can be a quite long output, then,
 215 it is possibly a good idea to redirect it to a file:
 216
 217   $ s-nail -dvv 2> error.log
 218
 219 Should you really discover any problems with S-nail it would be very
 220 useful for development if you would contact the mailing-list!
 221 Thank you!
 222
 223 2. Notes on building the latest release
 224 ---------------------------------------
 225
 226 - All systems:
 227   * I have turned off -Wstrict-overflow warnings unless we are debug
 228     enabled (talking about OPT_AUTOCC=yes here).
 229   * There are warnings on unused returns from some I/O functions.
 230     These will vanish after the large v15 I/O and MIME rewrite.
 231   * Some "XYZ may be used uninitialized" warnings are logically false.
 232
 233 - All 32-bit systems:
 234   * There _may_ be warnings about format strings, like, e.g.,
 235       auxlily.c:1610:10: warning: format '%lu' expects type 'long
 236       unsigned int', but argument 3 has type 'size_t'
 237     The codebase is ISO C89 which has no %z printf(3) format.
 238     However we try hard to detect the real type size and define the
 239     "PRI[du]Z" macros which end up with the correct size, which is
 240     also compile-time asserted (see the "MCTA(sizeof(size_t) == XZ)"
 241     statements in nail.h).
 242
 243     By forcing ISO C99 mode when compiling these warnings vanish, e.g.,
 244     with gcc(1) and clang(1): with $OPT_AUTOCC pass
 245     "EXTRA_CFLAGS=-std=c99", otherwise ensure -std=c99 is set in $CFLAGS.
 246
 247 Development and/or regular tests:
 248
 249 . AlpineLinux <https://www.alpinelinux.org/> (3.6; x86-64).
 250 . ArchLinux <https://www.archlinux.org/> (weekly updated; x86-64).
 251 . CRUX Linux <https://www.crux.nu/> (3.3; x86-64).
 252 . FreeBSD <https://www.freebsd.org/> (10.3; x86).
 253
 254 Occasional tests:
 255
 256 . OpenBSD <https://www.openbsd.org/> (6.1; x86).
 257 . Solaris <http://opencsw.org/>
 258   @ First of all: thanks to OpenCSW.org for offering SSH access to
 259     their Solaris build cluster!
 260   * In order to be able to run the tests you will need a cksum(1) that
 261     supports CRC-32 (POSIX).  We look into /opt/csw/gnu/cksum, but if
 262     that cannot be found you have to adjust the $cksum variable (see
 263     above) to something that works.
 264   * With $OPT_AUTOCC: we try to use Sun cc(1) whenever we find it.
 265     If your gcc(1) installation is doing alright you have to turn
 266     $OPT_AUTOCC off and use $CC, $CFLAGS and $LDFLAGS.
 267   * Warnings about iconv(3) prototypes which i will not address.
 268   * Some notes collected on earlier trials:
 269     + We may forcefully disable stack protectors on SunOS/gcc because of
 270       linking errors seen in earlier tests.
 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 $OPT_AUTOCC add this:
 277        EXTRA_CFLAGS='-D__builtin_stdarg_start=__builtin_va_start'
 278     + I couldn't get us going on SunOS 5.9 Sparc: the build system had
 279       to be extended to check for UINTPTR_MAX being defined as the empty
 280       string and similar very special things.
 281   - The OpenCSW build cluster consists of SunOS 5.9 - 5.11 machines
 282     under SPARC and i386.  And it looked good on 2017-07-01.
 283 . Void Linux <https://www.voidlinux.eu/> (x86; not in 2017 FIXME)
 284
 285 # s-ts-mode