INSTALL

   1 I n s t a l l i n g  S - n a i l
   2 ================================
   3
   4 Compilation
   5 -----------
   6
   7 System specific notes can be found in the next section.
   8 Any (optional) feature is adjustable and documented in `conf.rc'.
   9 Adjustments may also take place, and are usually done, from the command
  10 line, overriding those made in `conf.rc' (if any):
  11
  12   $ [make &&] make install
  13   $ make uninstall          # Won't remove the system wide startup file!
  14   $ make distclean          # *Completely* cleanup working directory
  15
  16 With adjustments:
  17
  18   $ make WANT_IMAP=0 install
  19   $ make WANT_NCL=0 PREFIX=/some/nasty/prefix install
  20
  21 There are also some predefined restricted configuration sets available,
  22 which take precedence over anything else:
  23
  24 . CONFIG=MINIMAL
  25   little is left but some air to breathe; no internet connectivity, no
  26   internationalized domain names, no command line editor, no
  27   documentation strings.
  28
  29 . CONFIG=MEDIUM
  30   Like MINIMAL, but with documentation strings, and the builtin command
  31   line editor will be included if that is possible.
  32
  33 . CONFIG=NETSEND
  34   WANT_SMTP and WANT_SSL settings are enabled, internationalized domain
  35   names will be supported if the necessary libraries are available,
  36   otherwise identical to MEDIUM.
  37
  38 E.g.:
  39
  40   $ make CONFIG=MINIMAL DESTDIR=xtest install
  41
  42 would create a `s-nail' binary and install a `s-nail' manual etc.
  43 under the prefix `/usr/local' but rooted under [./]`xtest', i.e., the
  44 binary would be installed as `[./]xtest/usr/local/bin/s-nail'.
  45 The following make(1) target exists, and note that you can use
  46 a VERBOSE=1 command line option to gain more (or a different kind of)
  47 verbosity:
  48
  49 . all         Create / check and update configuration, build.
  50 . install     Create / check and update configuration, build, install.
  51 . clean       Remove anything which can be rebuild.
  52 . distclean   Remove anything which can be rebuild or reconfigured.
  53 . uninstall   Uninstall (if configured).
  54
  55 . config      Only create or check and update the configuration.
  56 . build       Only build (using the existing configuration).
  57 . test        Run ./cc-test.sh in --check-only mode on the built binary.
  58 . packager-install
  59               Only install using the built files of the existing
  60               configuration.  It is possible to overwrite DESTDIR= when
  61               using this target nonetheless (a following `uninstall'
  62               won't know about that overwritten value, however).
  63
  64 If some libraries are missing that you know are installed on your
  65 system, or if other errors occur due to missing files but which you know
  66 exist, please ensure that the environment variable `C_INCLUDE_PATH'
  67 includes the necessary `include/' paths and the environment variable
  68 `LD_LIBRARY_PATH' includes the necessary `lib/'rary paths.
  69
  70 The S-nail make system will inspect these two environment variables and
  71 *automatically* convert them to cc(1) (c99(1)) -I and -L options (since
  72 these environment variables are, different to the command line options,
  73 not part of the POSIX standard).
  74 To set these environment variables, the following can be done in
  75 a Bourne/Korn/POSIX compatible shell:
  76
  77   $ C_INCLUDE_PATH="${C_INCLUDE_PATH}:/usr/local/include"
  78   $ LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib"
  79   $ export C_INCLUDE_PATH LD_LIBRARY_PATH
  80   $ make install
  81
  82 The S-nail make system will also automatically integrate pkgsrc(7) paths
  83 into this mechanism.  pkgsrc(7) is used to handle building (compilation),
  84 installation and removal of software packages on a lot of operating
  85 systems, including all BSD systems, Linux, Solaris ...
  86
  87 Notes for S-nail(1) v14.5*
  88 --------------------------
  89
  90 S-nail(1) has been or is used regulary on these systems (`uname -srm').
  91 Note first that MAILSPOOL is by default `/var/mail' (see `conf.rc').
  92
  93 Also, i'm (compile) testing manually with WANT_AUTOCC=1, WANT_DEBUG=[01]
  94 and WANT_AMALGAMATION=[01] (and WANT_GSSAPI=1), which is what is
  95 reflected by the following statements.
  96
  97 . All 32-bit systems:
  98   - There _may_ be warnings about format strings, like, e.g.,
  99
 100       auxlily.c:1610:10: warning: format '%lu' expects type 'long
 101       unsigned int', but argument 3 has type 'size_t'
 102
 103     This is ugly, but it has been decided to keep the S-nail codebase
 104     ISO C89 compatible, which means that there are no usable language
 105     hints for format strings.  However, `nail.h' tries hard to detect
 106     the real type sizes and ends up in a way that should ensure that the
 107     actually expected datatype is of the same size in reality:
 108
 109 /* XXX Note we don't really deal with that the right way in that we pass size_t
 110  * XXX arguments without casting; should do, because above we assert UINT_MAX
 111  * XXX is indeed ui32_t */
 112 #if defined __STDC_VERSION__ && __STDC_VERSION__ + 0 >= 199901L
 113 # define ZFMT           "zu"
 114 #elif defined SIZE_MAX && SIZE_MAX == 0xFFFFFFFFu && ULONG_MAX != UINT_MAX
 115 # define ZFMT           "u"
 116 #endif
 117 #ifndef ZFMT
 118 # define ZFMT           "lu"
 119 #endif
 120
 121 . Mac OS X <https://www.apple.com/>
 122   (Snow Leopard) Darwin 10.8.0 Darwin Kernel Version 10.8.0: Tue Jun
 123   7 16:33:36 PDT 2011; root:xnu-1504.15.3~1/RELEASE_I386 i386.
 124   - gcc-mp-4.8 (MacPorts gcc48 4.8.2_0) 4.8.2.
 125     + Note: with WANT_AMALGAMATION there is a single warning on 'signed
 126       overflow'.  I think it's wrong.
 127   - clang version 3.4 (branches/release_34 197314)
 128     Target: x86_64-apple-darwin10.8.0
 129     Thread model: posix.
 130   - i686-apple-darwin10-gcc-4.2.1 (GCC) 4.2.1 (Apple Inc. build 5666)
 131     (dot 3).
 132   - Apple clang version 1.7 (tags/Apple/clang-77) (based on LLVM
 133     2.9svn).
 134
 135 . ArchLinux <https://www.archlinux.org/>
 136   Linux 3.12.6-1-ARCH x86_64
 137   - gcc (GCC) 4.8.2 20131219 (prerelease)
 138     + Note: warnings on unused results, just ignore (for now).
 139
 140 . NetBSD <https://www.netbsd.org/>
 141   NetBSD 6.99.28 NetBSD 6.99.28 (GENERIC) #0: Fri Jan  3 05:24:46 UTC
 142   2014 i386
 143   - gcc (NetBSD nb1 20120916) 4.5.4
 144     + Warnings on format strings -- as above.
 145     + Note: i think faulty message on longjmp() clobbering (on
 146       a variable that is 'const').
 147     + Note: with WANT_AMALGAMATION there are many warnings on 'signed
 148       overflow', all referring to the same code, and i think it's wrong.
 149
 150   NetBSD 6.99.24 NetBSD 6.99.24 (GENERIC) #0: Tue Oct 29 08:23:21 UTC
 151   2013 amd64.
 152   - gcc (NetBSD nb1 20120916) 4.5.4.
 153     + Note: i think faulty message on longjmp() clobbering (on
 154       a variable that is 'const'.
 155     + Note: with WANT_AMALGAMATION there are many warnings on 'signed
 156       overflow', all referring to the same code, and i think it's wrong.
 157
 158 . CRUX Linux <http://www.crux.nu/>
 159   Linux 3.6.11 #1 SMP Sun Sep 15 17:47:31 UTC 2013 x86_64.
 160   - gcc (CRUX-x86_64-multilib) 4.7.2.
 161     + Note: there is a single warning on 'signed overflow'.  I think it's
 162       wrong.
 163
 164 . OpenBSD <http://www.openbsd.org/>
 165   OpenBSD 5.4 i386.
 166   - gcc (GCC) 4.2.1 20070719.
 167     + Note: i think faulty message on longjmp() clobbering (on
 168       a variable that is 'const').
 169
 170 . FreeBSD <https://www.freebsd.org/>
 171   FreeBSD 10.0-CURRENT amd64.
 172   - FreeBSD clang version 3.3 (tags/RELEASE_33/final 183502) 20130610
 173     Target: x86_64-unknown-freebsd10.0
 174     Thread model: posix.
 175
 176 . Void Linux <http://www.voidlinux.eu/>
 177   Linux 3.10.19_1 i686.
 178   - gcc (GCC) 4.7.3.
 179     + Note: there is a single warning on 'signed overflow'.  I think it's
 180       wrong.
 181
 182 . DragonFly BSD <https://www.dragonflybsd.org/>
 183   DragonFly 3.6-RELEASE x86_64
 184   - gcc 4.7.3 [DragonFly] Release/2013-04-11.
 185     + Note: harmless iconv(3) warning again (as if we didn't have had to
 186       treat it specially already).
 187     + Note: there is a single warning on 'signed overflow'.  I think it's
 188       wrong.
 189
 190 . UnixWare 7.1.4.
 191   + Note: this make(1) requires the -e option to pass values to make(1)
 192     subprocesses, so, if you want to overwrite DESTDIR= when doing
 193     `packager-install', you better say '$ make -e DESTDIR=xy ...'.
 194   + You'll see some harmless and ignorable warnings.
 195
 196 I'm very interested in reports from other combinations.
 197 (It should work practically everywhere, generally speaking.)
 198
 199 Program features yet to be overhauled
 200 -------------------------------------
 201
 202 Since i've forked Heirloom mailx(1) (for real) as S-nail(1) on
 203 2012-09-18 i make my way through the codebase, but have not yet taken
 204 a look (rather: at all) into the following modules/parts:
 205
 206   [List view/threading], Maildir, SSL, IMAP, POP3, SMTP, GSSAPI, Caching
 207
 208 These will remain features of S-nail(1) and they will be looked at, and
 209 of course i will fix bugs when i notice them, but they are not yet part
 210 of the overhauled "S-nail core" (though SMTP and POP are in daily use,
 211 and IMAP is slowly coming along).
 212
 213 I'll hope to be able to release S-nail v20 on 2018-03-25, the 40th
 214 anniversary of Mail, as a good one, then.  Also see `TODO'.
 215
 216 vim:set fenc=utf-8:s-ts-mode