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