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 What if tests fail?
   8 1.4 How can i enable debugging?
   9 2.  Notes on building the latest release
  10
  11 1. Compilation
  12 --------------
  13
  14 System specific notes can be found in the next section.
  15 All (optional) features are documented (and adjustable) 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 Without any adjustments all non-experimental features will be enabled,
  20 except some which provide redundant functionality (e.g., OPT_SPAM_SPAMC
  21 is disabled because the generic OPT_SPAM_FILTER can do the same).
  22 None of the features are "require"d by default, so that configuration
  23 will not fail shall any of them not be available or usable.
  24 The generated configuration is tracked: changes will be recognized
  25 and cause automatic cleanups and rebuilds as necessary.
  26 Experts could find it valuable to adjust some settings in config.h.
  27
  28   $ make tangerine  # equals "$ make config build test install"
  29   $ make citron     # equals "$ make config build install"
  30   $ make distclean  # *Completely* cleanup working directory
  31
  32 With adjustments:
  33
  34   $ make OPT_POP3=no OPT_SMTP=require tangerine
  35   $ make OPT_CROSS_BUILD=y VAL_PREFIX=/some/nasty/prefix citron
  36
  37 With utility program and feature adjustments:
  38
  39   $ make awk=/usr/bin/nawk OPT_SOCKETS=no DESTDIR=./zzz tangerine
  40
  41 If OPT_DOTLOCK has been enabled then the minimal privilege-separated
  42 SETUID (to VAL_PRIVSEP_USER, default "root") helper program will be build
  43 and installed, and therefore the installation process needs to have the
  44 appropriate privileges.  In this case it may be useful to separate the
  45 configuration / building and the installation tasks and give the last
  46 step higher privileges via super(1), sudo(1), su(1) or a similar
  47 mechanism, e.g.:
  48
  49   $ make VAL_PREFIX=/usr config && make MAKEJOBS='-j 4' &&
  50     super make DESTDIR=./xy install
  51
  52 would create a "s-nail" binary and install a "s-nail" manual etc.  under
  53 the prefix "/usr" but rooted under "[./]xy", i.e., the binary would be
  54 installed as "[./]xy/usr/bin/s-nail".
  55 Out-of-tree compilation is supported; to use it, create the target
  56 directory of desire, change into it and run the make-emerge.sh script
  57 shipped with S-nail, then proceed as with normal in-tree building.
  58 The following make(1) targets exists, the default being `build':
  59
  60 - tangerine   Shorthand for "$ make config build test install": create
  61               or check and update configuration, build, test and install.
  62               The variable $DESTDIR will be honoured (see make.rc),
  63               but not be tracked in the configuration.
  64               In order to parallelize the `build' step pass a $MAKEJOBS
  65               variable, as shown below.
  66 - citron      Shorthand for "$ make config build install".
  67               `build' parallelization via $MAKEJOBS, as shown below.
  68 - all         Shorthand for "$ make config build".
  69               `build' parallelization via $MAKEJOBS, as shown below.
  70
  71 - config      Only create or check and update the configuration.
  72 - build       Only build (using the existing configuration).
  73               This can be parallelized, either by a corresponding make(1)
  74               invocation when the target is run by itself, or by setting
  75               the $MAKEJOBS variable otherwise, e.g., "MAKEJOBS='-j 4'".
  76               $MAKEJOBS is not tracked in the configuration.
  77 - install     Only install using the built files of the existing
  78               configuration.
  79               The variable $DESTDIR will be honoured (see make.rc),
  80               but not be tracked in the configuration.
  81
  82               S-nail will create an uninstall shell script
  83               (VAL_UAGENT-uninstall.sh), but which will *not* be installed
  84               if $DESTDIR is set non-empty -- within $DESTDIR, that is.
  85               Copy or move it manually from the S-nail root directory ./
  86               into $DESTDIR as necessary.
  87
  88 - clean       Remove anything which can be rebuild.
  89 - distclean   Remove anything which can be rebuild or reconfigured.
  90
  91 - test        Run cc-test.sh in --check-only mode on the built binary.
  92
  93 Setting the make(1) variable $VERBOSE to an arbitrary value during
  94 `config' time, as in "$ make VERBOSE=xy tangerine", will change the
  95 output of the `all', `install' etc. targets to a more verbose one.
  96
  97 If some libraries are missing that you know are installed on your
  98 system, or if other errors occur due to missing files but which you know
  99 exist, please ensure that the environment variable $C_INCLUDE_PATH
 100 includes the necessary "include/" paths and the environment variable
 101 $LD_LIBRARY_PATH includes the necessary "lib/"rary paths.
 102
 103 The S-nail make system will inspect these two environment variables and
 104 *automatically* convert them to cc(1) (c99(1)) -I and -L options (since
 105 these environment variables are, different to the command line options,
 106 not part of the POSIX standard).
 107 To set these environment variables, the following can be done in
 108 a Bourne / Korn / POSIX compatible shell:
 109
 110   $ C_INCLUDE_PATH="${C_INCLUDE_PATH}:/usr/local/include"
 111   $ LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib"
 112   $ export C_INCLUDE_PATH LD_LIBRARY_PATH
 113   $ make tangerine
 114
 115 Other than the standard paths /usr/{bin,include,lib} and /usr/local/[.]
 116 should possibly be placed first instead, presuming that they are meant
 117 to override things which usually exist in standard locations.
 118 If all else fails you can also forcefully pass in include directives and
 119 library paths by passing prefilled $INCS and $LIBS variables:
 120
 121   $ make INCS=-I/mypath/include LIBS="-L/mypath/lib -lmylib" tangerine
 122
 123 There are also some predefined configuration sets available, ment to be
 124 used instead of doing manual adjustments.
 125
 126 - CONFIG=NULL, CONFIG=NULLI
 127   Anything that can be turned off is off.  MIME cannot.
 128   The latter adds and "require"s iconv(3) and adds the user interface
 129   strings.
 130
 131 - CONFIG=MINIMAL
 132   Possibly what people want who need nothing but a MIME-capable mailx(1)
 133   and do not regret improved usability for the rare interactive use
 134   occasions.  Adds documentation strings, the built-in line editor (MLE)
 135   with history support and key bindings, error tracking, basic colour
 136   support and IDNA addresses, as well as generic spam filter support.
 137
 138   "Require"s iconv(3), regex(3) and the dotlock helper.
 139
 140 - CONFIG=NETSEND
 141   Sending messages directly to the mail provider via the SMTP protocol,
 142   instead of requiring a local mail-transfer-agent (MTA) who does.
 143
 144   Adds SSL/TLS, SMTP, GSSAPI and .netrc file parsing on top of MINIMAL.
 145
 146   "Require"s iconv(3), SSL/TLS, SMTP (sockets) and the dotlock helper.
 147
 148 - CONFIG=MAXIMAL
 149   Like MINIMAL, but turns on all (other) options, also obsolete or
 150   redundant ones, but none of them required.
 151
 152 1.1 What if configuration fails?
 153 --------------------------------
 154
 155 The configuration process creates some files named "mk-config.*":
 156
 157 - mk-config.log  output generated by the configuration compile tests.
 158 - mk-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 - mk-config.h    C program header produced according to mk-config.lst.
 162 - mk-config.ev   A set of sh(1) variables for reproducible compile runs.
 163 - mk-config.inc  List of C header include paths, as compiler directives.
 164 - mk-config.lib  List of used library information, as compiler directives.
 165
 166 Of special interest is mk-config.log since the error usually manifests
 167 here in textual output.  Maybe that makes it obvious what can be done
 168 (header files could not be found because of missing entries in
 169 $C_INCLUDE_PATH, libraries could not be linked because of incomplete
 170 $LD_LIBRARY_PATH, etc.).
 171
 172 Otherwise it is getting complicated, and it would be appreciated if you
 173 would contact the mailing-list!
 174
 175 1.2 What if building fails?
 176 ---------------------------
 177
 178 Even worse!  This should not happen if configuration succeeded!  It
 179 would be very kind and highly appreciated if you would report this
 180 to the mailing-list.
 181
 182 1.3 What if tests fail?
 183 -----------------------
 184
 185 That would be a disaster.  Please contact the mailing-list!
 186 If you have used OPT_AUTOCC (the default) and a non-debug target, you
 187 could try to reconfigure with an additional cc_maxopt=1 on the command
 188 line and report whether that turns the green testing light on.
 189
 190 Otherwise you could run the cc-test.sh script in --mae-test mode and
 191 invoke the failing tests (testing echoes the actual test names in
 192 brackets): this will produce output files of the form mae-test-TESTXY.
 193 It would be nice if these outputs could be send to the mailing-list;
 194 possibly stored altogether in a compressed tar(1) file (the mailing-list
 195 has a message size restriction).  For example:
 196
 197   $ ./cc-test.sh --mae-test ./s-nail t_behave_localopts t_behave_mbox
 198   $ tar -czf badtests.tar.gz mae-test-*
 199   $ rm mae-test-*
 200
 201 Thank you!
 202
 203 1.4 How can i enable debugging?
 204 -------------------------------
 205
 206 Please ensure OPT_DEBUG=yes is enabled during compilation, as in
 207
 208   $ make CONFIG=MAXIMAL OPT_DEBUG=yes
 209
 210 If OPT_AUTOCC is enabled then the build system should automatically
 211 adjust the compiler flags accordingly, please see make.rc for more.
 212 There is also a `devel'opment target which does most of this by itself:
 213
 214   $ make devel
 215
 216 OPT_DEBUG (`devel') will enable memory bound debug canaries and
 217 Not-Yet-Dead function graph listings etc.  Whereas the latter will try
 218 to write its listing into a file named after your favourite MUA in
 219 your $TMPDIR (or "/tmp" or "./", in order), falling back to STDERR shall
 220 creation of the file not be possible (we will not overwrite an existing
 221 file), the debug facilities in general make their appearance on the
 222 standard error channel; because this can be a quite long output, then,
 223 it is possibly a good idea to redirect it to a file:
 224
 225   $ s-nail -dvv 2> error.log
 226
 227 Should you really discover any problems with S-nail it would be very
 228 useful for development if you would contact the mailing-list!
 229 Thank you!
 230
 231 2. Notes on building the latest release
 232 ---------------------------------------
 233
 234 - All systems:
 235   * I have turned off -Wstrict-overflow warnings unless we are debug
 236     enabled (talking about OPT_AUTOCC=yes here).
 237   * There are warnings on unused returns from some I/O functions.
 238     These will vanish after the large v15 I/O and MIME rewrite.
 239   * Some "XYZ may be used uninitialized" warnings are logically false.
 240
 241 - All 32-bit systems:
 242   * There _may_ be warnings about format strings, like, e.g.,
 243       auxlily.c:1610:10: warning: format '%lu' expects type 'long
 244       unsigned int', but argument 3 has type 'size_t'
 245     The codebase is ISO C89 which has no %z printf(3) format.
 246     However we try hard to detect the real type size and define the
 247     "PRI[du]Z" macros which end up with the correct size, which is
 248     also compile-time asserted (see the "MCTA(sizeof(size_t) == XZ)"
 249     statements in nail.h).
 250
 251     By forcing ISO C99 mode when compiling these warnings vanish, e.g.,
 252     with gcc(1) and clang(1): with OPT_AUTOCC pass
 253     "EXTRA_CFLAGS=-std=c99", otherwise ensure -std=c99 in $CFLAGS.
 254
 255 Development and/or regular tests:
 256
 257 . AlpineLinux <https://www.alpinelinux.org/> (3.7, edge; x86-64).
 258 . ArchLinux <https://www.archlinux.org/> (weekly updated; x86-64).
 259 . CRUX Linux <https://www.crux.nu/> (3.3; x86-64).
 260 . FreeBSD <https://www.freebsd.org/> (11.1; x86).
 261   - The tests behave:iconv_mbyte_base64-4 and
 262     behave:iconv_mbyte_base64-8 will fail because the ISO C function
 263     iswprint(3) will falsely claim that U+FF08 and U+FF09 (FULLWIDTH
 264     LEFT and RIGHT PARENTHESIS, respectively) are not printable, causing
 265     replacements.  This is a known bug, see
 266       <https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=225692>
 267 . OpenBSD <https://www.openbsd.org/> (6.2; x86).
 268
 269 Occasional tests:
 270
 271 . Solaris <http://opencsw.org/>
 272   @ First of all: thanks to OpenCSW.org for offering SSH access to
 273     their Solaris build cluster!
 274   * In order to be able to run the tests you will need a cksum(1) that
 275     supports CRC-32 (POSIX).  We look into /opt/csw/gnu/cksum, but if
 276     that cannot be found you have to adjust the $cksum variable (see
 277     above) to something that works.
 278   * With OPT_AUTOCC: we try to use Sun cc(1) whenever we find it.
 279     If your gcc(1) installation is doing alright you have to turn
 280     OPT_AUTOCC off and use $CC, $CFLAGS and $LDFLAGS.
 281   * Some notes collected on earlier trials:
 282     + We may forcefully disable stack protectors on SunOS/gcc because of
 283       linking errors seen in earlier tests.
 284     + If you get the compiler / system header installation error
 285         Undefined                       first referenced
 286          symbol                             in file
 287         __builtin_stdarg_start              auxlily.o
 288       then you have to overwrite this symbol with __builtin_va_start,
 289       e.g., in conjunction with OPT_AUTOCC add this:
 290        EXTRA_CFLAGS='-D__builtin_stdarg_start=__builtin_va_start'
 291   - The OpenCSW build cluster consists of SunOS 5.9 - 5.11 machines
 292     under SPARC and i386.  And it looked perfect on 2018-03-24.
 293 . Void Linux <https://www.voidlinux.eu/> (x86)
 294
 295 # s-ts-mode