Generalize and straigthen handling of the soft-exit-status *!*

[s-mailx.git] / INSTALL

I n s t a l l i n g  S - n a i l / S - m a i l x
================================================

1.  Compilation
1.1 What if configuration fails?
1.2 What if building fails?
1.3 How can i enable debugging?
2.  Notes on building the latest release

1. Compilation
--------------

System specific notes can be found in the next section.
All (optional) features are documented (and adjustable) in make.rc.
Adjustments may also take place, and are usually done, from the command
line, overriding those made in make.rc (if any).
Without any adjustments all non-experimental features will be enabled,
except some which provide redundant functionality (e.g., OPT_SPAMC is
disabled because the generic OPT_SPAM_FILTER can do the same).
None of the features are "require"d by default, so that configuration
won't fail shall any of them not be available or usable.

  $ make tangerine  # equals "$ make config build test install"
  $ make distclean  # *Completely* cleanup working directory

With adjustments:

  $ make OPT_POP3=no OPT_SMTP=require tangerine
  $ make OPT_CROSS_BUILD=y VAL_PREFIX=/some/nasty/prefix tangerine

With utility program and feature adjustments:

  $ make awk=/usr/bin/nawk OPT_SOCKETS=no DESTDIR=./zzz tangerine

If OPT_DOTLOCK has been enabled then the minimal privilege-separated
SETUID (to VAL_PRIVSEP_USER, default "root") helper program will be build
and installed, and therefore the installation process needs to have the
appropriate privileges.  In this case it may be useful to separate the
configuration / building and the installation tasks and give the last
step higher privileges via super(1), sudo(1), su(1) or a similar
mechanism, e.g.:

  $ make VAL_PREFIX=/usr config && make MAKEJOBS='-j 4' &&
    super make DESTDIR=./xy install

would create a "s-nail" binary and install a "s-nail" manual etc.  under
the prefix "/usr" but rooted under "[./]xy", i.e., the binary would be
installed as "[./]xy/usr/bin/s-nail".
The following make(1) targets exists, the default being `build':

- tangerine   Shorthand for "$ make config build test install":
              create or check and update configuration, build, test and
              install.
              The variable $DESTDIR will be honoured (see make.rc),
              but not be tracked in the configuration.
              In order to parallelize the `build' step pass a $MAKEJOBS
              variable, as shown below.
- all         Shorthand for "$ make config build".
              In order to parallelize the `build' step pass a $MAKEJOBS
              variable, as shown below.

- config      Only create or check and update the configuration.
- build       Only build (using the existing configuration).
              This can be parallelized, either by a corresponding make(1)
              invocation when the target is run by itself, or by setting
              the $MAKEJOBS variable otherwise, e.g., "MAKEJOBS='-j 4'".
              $MAKEJOBS is not tracked in the configuration.
- install     Only install using the built files of the existing
              configuration.
              The variable $DESTDIR will be honoured (see make.rc),
              but not be tracked in the configuration.

              S-nail will create an uninstall shell script
              (VAL_UAGENT-uninstall.sh), but which will *not* be installed
              if $DESTDIR is set non-empty -- within $DESTDIR, that is.
              Copy or move it manually from the S-nail root directory ./
              into $DESTDIR as necessary.

- clean       Remove anything which can be rebuild.
- distclean   Remove anything which can be rebuild or reconfigured.

- test        Run cc-test.sh in --check-only mode on the built binary.

Setting the make(1) variable $VERBOSE to an arbitrary value during
`config' time, as in "$ make VERBOSE=xy tangerine", will change the
output of the `all', `install' etc. targets to a more verbose one.
If some libraries are missing that you know are installed on your
system, or if other errors occur due to missing files but which you know
exist, please ensure that the environment variable $C_INCLUDE_PATH
includes the necessary "include/" paths and the environment variable
$LD_LIBRARY_PATH includes the necessary "lib/"rary paths.

The S-nail make system will inspect these two environment variables and
*automatically* convert them to cc(1) (c99(1)) -I and -L options (since
these environment variables are, different to the command line options,
not part of the POSIX standard).
To set these environment variables, the following can be done in
a Bourne / Korn / POSIX compatible shell:

  $ C_INCLUDE_PATH="${C_INCLUDE_PATH}:/usr/local/include"
  $ LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib"
  $ export C_INCLUDE_PATH LD_LIBRARY_PATH
  $ make tangerine

The S-nail make system will also automatically integrate pkgsrc(7) paths
into this mechanism.  (pkgsrc(7) is a portable package management system
that is used as a default on diverse operating systems.)
And if all else fails you can also forcefully pass in include directives
and library paths by passing prefilled $INCS and $LIBS variables:

  $ make INCS=-I/mypath/lib LIBS=-l/mypath/iconv tangerine

Note there are also some predefined configuration sets available, ment
to be used instead of doing manual adjustments (in make.rc or) on the
command line (names are case-insensitive):

- CONFIG=NULL, CONFIG=NULLI
  Anything that can be turned off is off.  MIME can't.
  The latter adds and "require"s iconv(3), though.

- CONFIG=MINIMAL
  This is the most plain mailx(1)-alike mode, but with MIME support and
  (if available) character set conversion and regular expressions
  builtin.  Dotlock files and the privileged separated dotlock helper.

  "Require"s dotlocking and the privileged separated dotlock helper.

- CONFIG=MEDIUM
  Possibly what people want who need nothing but a MIME-capable mailx(1)
  and don't regret improved usability for the rare interactive use
  occasions.

  Like MINIMAL, but with documentation strings, the builtin line editor
  (MLE) with history support and key bindings, error tracking, basic
  colour support and IDNA addresses.

  "Require"s iconv(3), dotlocking and the privileged separated dotlock
  helper.

- CONFIG=NETSEND
  Sending messages directly to the mail provider via the SMTP protocol,
  instead of requiring a local mail-transfer-agent (MTA) who does.

  Adds SSL/TLS, GSSAPI and .netrc file parsing on top of MEDIUM, on the
  other hand spam filter support is removed.

  "Require"s iconv(3), SSL/TLS, SMTP (sockets), dotlocking and the
  privileged separated dotlock helper.

- CONFIG=MAXIMAL
  Anything on, including experimental features.
  S-nail(1) gains mail fetching capabilities and heads more towards
  being a full-featured mail-user-agent (MUA) with this configuration.

  "Require"s iconv(3), regex(3), the MLE as well as dotlocking and the
  privileged separated dotlock helper.

1.1 What if configuration fails?
--------------------------------

The configuration process creates some files named "config":

- config.log  output generated by the configuration compile tests.
- config.lst  configuration (chosen option, programs, paths).
              (Removing this file reenables configuration even after
              a screwed up configuration, e.g., due to power failure.)
- config.h    C program header produced according to config.lst.
- config.ev   A set of sh(1) variable for reproducable compile runs.
- config.inc  List of C header include paths, as compiler directives.
- config.lib  List of used library information, as compiler directives.

Of special interest is config.log since the error usually manifests here
in textual output.  Maybe that makes it obvious what can be done (header
files could not be found because of missing entries in $C_INCLUDE_PATH,
libraries could not be linked because of incomplete $LD_LIBRARY_PATH,
etc.).
Otherwise it is getting complicated, and it would be appreciated if you
would contact the mailing-list!

1.2 What if building fails?
---------------------------

Even worse!  This should not happen if configuration succeeded!  It
would be very kind and highly appreciated if you would report this
to the mailing-list.

1.3 How can i enable debugging?
-------------------------------

Please ensure OPT_DEBUG=yes is enabled during compilation, as in

  $ make CONFIG=MAXIMAL OPT_DEBUG=yes

If $OPT_AUTOCC is enabled then the build system should automatically
adjust the compiler flags accordingly, please see make.rc for more.
There is also a `devel'opment target which does most of this by itself:

  $ make devel

$OPT_DEBUG (`devel') will enable memory bound debug canaries and
Not-Yet-Dead function graph listings etc.  Whereas the latter will try
to write its listing into a file named after your favourite MUA in
your $TMPDIR (or "/tmp" or "./", in order), falling back to STDERR shall
creation of the file not be possible (we won't overwrite an existing
file), the debug facilities in general make their appearance on the
standard error channel; because this can be a quite long output, then,
it is possibly a good idea to redirect it to a file:

  $ s-nail -dvv 2> error.log

Should you really discover any problems with S-nail it would be very
useful for development if you would contact the mailing-list!
Thank you!

2. Notes on building the latest release
---------------------------------------

This software has been in use or is used on a regulary basis on FreeBSD
and Linux.  Occasional tests happens on the remains of the following.
Unless otherwise noted the following applies to saying
"$ make tangerine; make devel && make test".
In alphabetical order:

- All systems:
  * I've turned off -Wstrict-overflow warnings unless we're debug
    enabled (talking about OPT_AUTOCC=yes here).
  * You will likely see warnings on unused returns from write(2),
    ftruncate(2) and a few other I/O functions.  These will vanish after
    the large I/O and MIME rewrite that comes with v15.
  * I am using the latest gcc(1) and clang(1) compilers, and am doing
    scan-build(1) and Coverity.com inspection before major releases.
    Some "XYZ may be used uninitialized" warnings are logically false.

- All 32-bit systems:
  * There _may_ be warnings about format strings, like, e.g.,
      auxlily.c:1610:10: warning: format '%lu' expects type 'long
      unsigned int', but argument 3 has type 'size_t'
    The codebase is ISO C89, so we have no %z printf(3) format.
    However we try hard to detect the real type size and define the
    "PRI[du]Z" macros which end up with the correct size, which is
    also compile-time asserted (see the "MCTA(sizeof(size_t) == XZ)"
    statements in nail.h).

    You can completely overcome this situation by forcing ISO C99 mode
    when compiling, e.g., with gcc(1) and clang(1): if you use
    $OPT_AUTOCC then also pass "EXTRA_CFLAGS=-std=c99", otherwise
    ensure -std=c99 is set in your $CFLAGS.

. AlpineLinux <https://www.alpinelinux.org/>
  AlpineLinux 3.4.3, gcc(1).

. ArchLinux <https://www.archlinux.org/>
  Latest as of 2016-09-16, clang(1) and gcc(1).

. CRUX Linux <https://www.crux.nu/>
  CRUX 3.2 RC3, gcc(1).

. DragonFly BSD <https://www.dragonflybsd.org/>
  DragonFly 4.6.0, gcc(1).
  * I will never get iconv(3) right for Solaris it seems.

- FreeBSD <https://www.freebsd.org/>
  FreeBSD 10.3, clang(1).

- NetBSD <https://www.netbsd.org/>
  Not tested.

. OpenBSD <https://www.openbsd.org/>
  OpenBSD 5.9.

- Solaris <http://opencsw.org/>
  @ First of all: thanks to OpenCSW.org for offering SSH access to
    their Solaris build cluster!
  * In order to be able to run the tests you will need a cksum(1) that
    supports CRC-32 (POSIX).  We look into /opt/csw/gnu/cksum, but if
    that cannot be found you have to adjust the $cksum variable (see
    above) to something that works.
    (v15 will use a different test suite.)
  * With $OPT_AUTOCC: we try to use Sun cc(1) whenever we find it.
    If your gcc(1) installation is doing alright you have to turn
    $OPT_AUTOCC off and use $CC, $CFLAGS and $LDFLAGS.
  * I will never get iconv(3) right for Solaris it seems.
  * Some notes collected on earlier trials:
    + We may forcefully disable stack protectors on SunOS/gcc because of
      linking errors seen in earlier tests.
    + If you get the compiler / system header installation error
        Undefined                       first referenced
         symbol                             in file
        __builtin_stdarg_start              auxlily.o
      then you have to overwrite this symbol with __builtin_va_start,
      e.g., in conjunction with $OPT_AUTOCC add this:
       EXTRA_CFLAGS='-D__builtin_stdarg_start=__builtin_va_start'
    + I couldn't get us going on SunOS 5.9 Sparc: the build system had
      to be extended to check for UINTPTR_MAX being defined as the empty
      string and similar very special things.
  - The OpenCSW build cluster consists of SunOS 5.9 - 5.11 machines
    under SPARC and i386.
    It looked good on 2016-09-16.

- UnixWare 7.1.4.
  * Note: it is no longer possible to use the `install' rule, because
    we use shell functions to ease the task of directory creation etc.
    (especially useful due to $VERBOSE), and that won't work due to bugs
    (in the system make(1) program i presume).
  + Not tested after v14.8.4, just fine before that.

. Void Linux <http://www.voidlinux.eu/>
  Not yet tested for v14.9.0.
  (My current working environment is restricted since i've lost
  my main development machine.)

# s-ts-mode