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