INSTALL

   1 I n s t a l l i n g  S - n a i l
   2 ================================
   3
   4 Quick start
   5 -----------
   6
   7 Read user.conf and maybe adjust some feature settings according to your
   8 needs.  You may also want to look into the Makefile, e.g., to change the
   9 PREFIX, or to adjust whatever else before the >8 scissor line.  Then run
  10
  11   $ [make &&] make install # (Or only make install)
  12   $ make uninstall         # (Will not remove the example configuration)
  13   $ make distclean         # *Completely* cleanup working directory
  14
  15 Instead of actually *editing* the Makefile it is probably much easier to
  16 override variables from within the command line instead, e.g., to change
  17 the installation directory:
  18
  19   $ make PREFIX=/some/nasty/prefix STRIP='/usr/bin/strip -s' install
  20
  21 And instead of editing user.conf you may also choose predefined CONFIG
  22 sets from the command line:
  23
  24   CONFIG=MINIMAL  little is left but some air to breathe.
  25   CONFIG=NETLESS  all settings from user.conf relating internet connect-
  26                   ivity are off.
  27   CONFIG=NETSEND  WANT_SMTP and WANT_SSL settings are enabled, otherwise
  28                   identical to MINIMAL.
  29
  30 When this CONFIG-set approach is used, the following additional switches
  31 may be used on the command line:
  32
  33   WANT_IDNA=0     Do not (try to) support internationalized domain names.
  34
  35 E.g.:
  36
  37   $ make CONFIG=MINIMAL WANT_IDNA=0 DESTDIR=xtest SID=mini- install
  38
  39 would create a "mini-nail" binary and install a "mini-nail" manual etc.
  40 under the prefix /usr/local but rooted under [./]xtest, i.e., the binary
  41 would be installed as "[./]xtest/usr/local/bin/mini-nail".  Note that
  42 for "make uninstall" the *exact* command line should be repeated.
  43
  44 Notes for S-nail(1) v13
  45 -----------------------
  46
  47 - Mac OS X Snow Leopard.  Tested with all features (except IPv6) with
  48   the default CC=clang(1) and CC=gcc(1), -O2 and -O3, the WARNs
  49   including -fstrict-overflow+.
  50 - FreeBSD 9.0.  Tested with all features except IPv6, iconv() and IDNA
  51   with the default CC=clang(1) and CC=gcc(1), -O2, and the WARNs
  52   including -fstrict-overflow.
  53 - NetBSD 5.1 and 6.0.  Tested with all features except IPv6 and IDNA
  54   with the default compiler, -O2 and -O3.
  55   Note that on 6.0 you should not enable -fstrict-overflow, as it
  56   produces much more warnings than i saw before when testing with all
  57   the other combinations shown here, and i had yet no time to look over
  58   all those.
  59 - Lightly tested on a default OpenBSD 5.1 with -O2.
  60 - Compiled and lightly tested on TinyCoreLinux 4.4 with default compiler
  61   environment available at that time with -O2.
  62
  63 The current maintainer has not yet looked at the following for real:
  64 IPv6, IMAP+, POP3+, NSS, Bayesian filter.
  65
  66 [Heirloom file content follows]
  67
  68 How to configure and install mailx
  69 ==================================
  70
  71 Quick start
  72 -----------
  73
  74         make
  75         make install
  76
  77 No 'configure' step is necessary anymore. If 'make install' fails because
  78 no /usr/ucb/install program is present, try
  79
  80         make install UCBINSTALL=/usr/bin/install
  81
  82 Detailed description
  83 --------------------
  84
  85 Path names are configurable as Makefile variables:
  86
  87 PREFIX          The default Makefile puts BINDIR and MANDIR below this.
  88
  89 BINDIR          The mailx binary is installed there.
  90
  91 MANDIR          The mailx manual page is put in $(MANDIR)/man1.
  92
  93 SYSCONFDIR      nail.rc is installed in this directory unless it already
  94                 exists.
  95
  96 MAILSPOOL       The directory where the mail files of users are stored
  97                 under their respective names and in mbox format. If only
  98                 POP3 is used to read mail, the value does not matter.
  99
 100 SENDMAIL        Path to the de-facto standard /usr/lib/sendmail interface
 101                 normally offered by Unix MTAs. If only SMTP is used to send
 102                 mail, the value does not matter. Note that if you want to
 103                 use the '-r' option in mailx, the sendmail interface must
 104                 support the '-r' option too.
 105
 106 DESTDIR         Prepended to BINDIR, MANDIR etc. at 'make install'. Mostly
 107                 useful for package building.
 108
 109 UCBINSTALL      Path name to a BSD-style install, like /usr/ucb/install on
 110                 SVR4 or GNU install.
 111
 112 STRIP           A command to strip the binary at 'make install'. Use the
 113                 do-nothing command ':' to avoid stripping.
 114
 115 Mailx uses a simple shell script named 'makeconfig' to check for header
 116 files and library functions. It is automatically invoked by 'make all'.
 117 The script generates three files, 'config.h', 'LIBS', and 'config.log'.
 118 'config.h' is included as usual, 'LIBS' contains options for the linker,
 119 and 'config.log' contains all test programs and test results. Neither of
 120 these files is changed by make once it exists until 'make mrproper' is
 121 run, so they can be edited by hand without much fear of losing them.
 122
 123 Useful Makefile targets:
 124
 125 all             Initiates the build; just type 'make'.
 126
 127 install         Installs the binary and the manual page. If the systemwide
 128                 configuration file is not present already, is is also
 129                 installed.
 130
 131 clean           Removes object files.
 132
 133 mrproper        Removes object files and the configuration results.
 134
 135 Makefile variables to control the build process:
 136
 137 CFLAGS          Flags for the C compiler, such as '-O'.
 138
 139 CPPFLAGS        Flags for the C preprocessor. Some versions of glibc on
 140                 Linux need '-D_GNU_SOURCE' here, or wcwidth() will not be
 141                 available and multibyte characters cannot be displayed
 142                 correctly.
 143
 144 INCLUDES        A list of additional include file directories, as
 145                 '-I/usr/local/include'. Use this to locate the include
 146                 files for NSS, OpenSSL, or iconv(3), if they are not present
 147                 in the standard include directories. Also, some versions
 148                 of RedHat Linux need -I/usr/kerberos/include to compile
 149                 with OpenSSL, or to compile with GSSAPI authentication
 150                 included.
 151
 152 LDFLAGS         Flags for the linker. To compile with GSSAPI authentication
 153                 included, some RedHat versions need -L/usr/kerberos/lib.
 154                 Also use this to specify the NSS or OpenSSL library path.
 155
 156 LIBS            A list of additional libraries such as '-lfoo'. -lsocket,
 157                 -lnsl, -lssl, -lcrypto, -liconv, and NSS libraries are
 158                 automatically included by makeconfig and should not be
 159                 put into this.
 160
 161 As usual with Makefile variables, you can pass these values to make in
 162 the environment or on the command line. Thus if you want to avoid to edit
 163 the Makefile, you can create a shell script to invoke make, or set flags
 164 of general use (such as CFLAGS) in .profile. Note that passing flags on
 165 the command line does not override those specified in the Makefile itself
 166 with several commercial versions of make in combination with the recursive
 167 make calls that are executed at configuration time.
 168
 169
 170 Transition remarks concerning the old configure system
 171 ======================================================
 172
 173 * --prefix and other common configure options: Path names can be specified
 174   in the Makefile or as assignment arguments to make.
 175
 176 * --with-openssl: No longer available. Mailx is always built with OpenSSL
 177   support if possible. If you really want to have a mailx binary without
 178   OpenSSL support, edit config.h after running 'make config.h'.
 179
 180 * --enable-all-chars: No longer available at compile time. 'print-all-chars'
 181   can be set in mailx in those cases where use of this option was necessary.
 182
 183 * --with-rcfile, --with-mailspool, --with-sendmail: These path names can
 184   be set in the Makefile or as arguments to make.
 185
 186 * --with-csh: No longer used. Mailx now uses /bin/sh for executing commands
 187   if the SHELL variable is not set.
 188
 189 * --with-more, --with-pg, --with-ed, --with-vi: No longer available. If the
 190   PAGER, EDITOR, or VISUAL variables are not set, the executable is looked
 191   up using $PATH.
 192
 193 * --with-catname=NAME: Contact the author if you want usable message
 194   catalogue support.
 195
 196 In short, if you were using
 197 --------
 198
 199         ./configure --prefix=/opt/nail --with-rcfile=/opt/nail/etc/nail.rc
 200
 201 up to now, replace it by
 202
 203         make PREFIX=/opt/mailx SYSCONFDIR=/opt/mailx/etc
 204
 205 The DESTDIR variable for building packages is available as before.
 206 If you intend to build mailx packages, a look at 'mailx.spec' might
 207 be helpful - even if you don't use RPM, the process is likely to
 208 be similar.
 209
 210
 211 Why autoconf/automake are no longer used
 212 ========================================
 213
 214 Autoconf and automake are systems of considerable complexity which
 215 one must know well to make real use of them. The autoconf/automake
 216 scripts for mailx were supplied by a contributor in 2000 and were
 217 out of date as of 2004; they wouldn't work with recent versions of
 218 automake, in particular. But I'm not very interested in learning
 219 automake myself, and I'm absolutely not interested in keeping such
 220 knowledge up-to-date with new automake versions.
 221
 222 Furthermore, I've made some horrible hacks for the autoconf/automake
 223 scripts in previous versions (such as --with-rcfile) because once one
 224 doesn't like some particular behavior of them, working around can be
 225 difficult. Such hacks are unnecessary now.
 226
 227 The new build system needs approximately the same number of lines
 228 as just the maintainer-supplied portions of the old autoconf/automake
 229 system did. Since it is written in standard languages (shell and make),
 230 any Unix developer can read and understand it; to make adjustments to
 231 it, no special versions of third-party tools are needed. Every serious
 232 developer should understand the advantage (except perhaps some GNU
 233 addicts who have learned and installed all versions of automake anyway).
 234
 235 For the user who just wants to build mailx, the new system is not more
 236 complicated than the old one; transition mostly involves passing path
 237 names to make instead of passing them to configure. (It's not even an
 238 argument that the user needs to know the names of Makefile variables;
 239 --prefix didn't work as designed by the GNU folks with the old system
 240 anyway.)
 241
 242 In short, everything is better now.
 243
 244
 245 Building S/MIME and SSL/TLS support using Mozilla NSS
 246 =====================================================
 247
 248 It is possible to build encryption support using Mozilla NSS instead
 249 of OpenSSL. Doing so has both advantages and disadvantages:
 250
 251 - With NSS, mailx can use the same key and certificate databases as the
 252   Mozilla applications (Mozilla Suite, Firefox, Thunderbird). This makes
 253   it possible to install and configure certificates at one central location.
 254   Note that running mailx and Mozilla at the same time from one certificate
 255   directory may result in 'Bad database' errors in mailx if Mozilla modifies
 256   the configuration files (mailx never modifies them). If you encounter such
 257   problems, create a copy of the .db files for exclusive use with mailx.
 258
 259 - OpenSSL offers more transparent control over certificates. While it is
 260   possible to modify the NSS databases using command line utilities (see
 261   <http://www.mozilla.org/projects/security/pki/nss/tools/>), it is
 262   certainly easier to use PEM files along with descriptions in OpenSSL if
 263   direct control is desired (e.g. for batch use).
 264
 265 - NSS supports S/MIME in both versions 2 and 3, OpenSSL currently only
 266   supports version 2.
 267
 268 - Building OpenSSL is much easier than building NSS for use with non-Mozilla
 269   applications like mailx.
 270
 271 To build using NSS, you need both the NSS and the NSPR libraries/include
 272 files from the Mozilla project. If you are using a Linux distribution,
 273 chances are that you can install appropriate RPMs from your vendor, e.g.
 274
 275 seamonkey-nspr-1.0.5-0.1.el4.centos4
 276 seamonkey-nspr-devel-1.0.5-0.1.el4.centos4
 277 seamonkey-nss-1.0.5-0.1.el4.centos4
 278 seamonkey-nss-devel-1.0.5-0.1.el4.centos4
 279
 280 for CentOS 4. Note that you can install these without installing the
 281 RPM for the Mozilla main application. Thus it is no problem if you prefer
 282 to use a more recent Mozilla installation in /opt or so. NSS and NSPR are not
 283 updated as often as the Mozilla end-user applications in recent times (but you
 284 should watch for possible future security fixes regardless, of course.)
 285
 286 If you have these RPMs installed, you can uncomment the marked lines in either
 287 the Makefile or in mailx.spec. Mailx should then build cleanly with NSS support
 288 included, and that's all.
 289
 290 On recent Solaris versions, NSS and NSPR are available in the packages
 291 SUNWmoznss, SUNWmoznss-devel, SUNWmoznspr, and SUNWmoznspr-devel. If these
 292 packages are installed, the following make variables activate NSS support:
 293 INCLUDES=-I/usr/sfw/include/mozilla/nspr -I/usr/sfw/include/mozilla/nss
 294 LDFLAGS=-L/usr/sfw/lib/mozilla -R/usr/sfw/lib/mozilla
 295
 296 If you want to use NSS without RPMS, you can get binary or source .tar.gz
 297 archives from the Mozilla project pages:
 298
 299 <http://www.mozilla.org/projects/security/pki/nss/>
 300 <http://www.mozilla.org/projects/nspr/>
 301
 302 Or you can use the files from a Mozilla application build directory if you
 303 are building Mozilla Suite, Firefox, Thunderbird etc. from source. Just set
 304 the INCLUDES and LDFLAGS variables appropriately.
 305
 306 If both NSS and OpenSSL are available, NSS is used. This is just because
 307 NSS is normally not found without special action, and thus the build process
 308 simply assumes that you want to build NSS if it manages to build the test
 309 executable.
 310
 311
 312         Gunnar Ritter                                   12/25/06