INSTALL

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