INSTALL

   1 Supported platforms
   2 ===================
   3
   4 Mutt has been reported to compile and run under the following Unix operating
   5 systems:
   6
   7         AIX
   8         BSDI
   9         Convex
  10         Data General Unix (DG/UX)
  11         Digital Unix (OSF/1)
  12         DYNIX/ptx
  13         FreeBSD
  14         HP-UX
  15         IRIX
  16         Linux
  17         Mac OS X
  18         Atari MiNT
  19         MkLinux
  20         NetBSD
  21         OpenBSD
  22         QNX
  23         SCO Unix 3.2v4/5
  24         Solaris
  25         SunOS
  26         Ultrix
  27         UnixWare
  28
  29 - If you are building from Mercurial, or if you are changing parts of mutt,
  30   particularly the build system, do read doc/devel-notes.txt.
  31
  32 - An ANSI C compiler (such as GCC) is required.
  33
  34 - You must also have a SysV compatible curses library, or you must
  35   install either
  36
  37         GNU ncurses, ftp://prep.ai.mit.edu/pub/gnu/
  38   or
  39         S-Lang, ftp://space.mit.edu/pub/davis/slang/
  40
  41 - Mutt needs an implementation of the iconv API for character set
  42   conversions.  A free one can be found under the following URL:
  43
  44         http://www.gnu.org/software/libiconv/
  45
  46 - For building the manual, mutt needs the DocBook XSL stylesheets
  47   as well as the DocBook DTD as of version 4.2 installed locally.
  48   For details, please see the section "Generating Mutt Documentation
  49   From Source" in doc/devel-notes.txt.
  50
  51
  52 Installation
  53 ============
  54
  55 Installing Mutt is rather painless through the use of the GNU
  56 autoconf package.  Simply untar the Mutt distribution, and run the
  57 ``configure'' script.  If you have obtained the distribution from
  58 the Mercurial repository, run the ``prepare'' script with the same command
  59 line parameters you would pass to configure.  It will set up mutt's
  60 build environment and add the files which are present in the tar
  61 balls, but not in the Mercurial repository.
  62
  63 In most cases, configure will automatically determine everything it
  64 needs to know in order to compile.  However, there are a few options
  65 to ``configure'' to help it out, or change the default behavior:
  66
  67 --prefix=DIR
  68         install Mutt in DIR instead of /usr/local
  69
  70 --with-curses=DIR
  71         use the curses lib in DIR/lib.  If you have ncurses, ``configure''
  72         will automatically look in /usr/include/ncurses for the include
  73         files.
  74
  75 --with-slang[=DIR]
  76         use the S-Lang library instead of ncurses.  This library seems to
  77         work better for some people because it is less picky about proper
  78         termcap entries than ncurses.  It is recommended that you use at
  79         *least* version 0.99-38 with Mutt.
  80
  81 --with-mailpath=DIR
  82         specify where the spool mailboxes are located on your system
  83
  84 --with-homespool[=FILE]
  85         treat file in the user's home directory as the spool mailbox.  Note
  86         that this is *not* the full pathname, but relative to the user's
  87         home directory.  Defaults to "mailbox" if FILE is not specified.
  88
  89 --enable-pop
  90         enable POP3 support
  91
  92 --enable-imap
  93         enable IMAP support
  94
  95 --with-gss[=PFX]
  96         Enable GSSAPI authentication to IMAP servers. This should work with
  97         both MIT and Heimdal GSSAPI implementations - others haven't been
  98         tested. Note that the Cyrus SASL library also supports GSSAPI,
  99         and may be able to encrypt your session with it - you should use
 100         SASL instead if you can.
 101
 102 --with-ssl[=PFX]
 103         enable SSL support with IMAP and POP. SSL support requires you to
 104         have OpenSSL headers and libraries properly installed before
 105         compiling.  If the OpenSSL headers and libraries are not in the
 106         default system pats you can use the optional PFX argument to
 107         define the root directory of your installation.  The libraries
 108         are then expected to be found in PFX/lib and headers in
 109         PFX/include/openssl.
 110
 111 --with-sasl[=PFX]
 112         Use the Cyrus SASL library for IMAP or POP authentication. This
 113         library provides generic support for several authentication methods,
 114         and more may be added by the system administrator without recompiling
 115         mutt. SASL may also be able to encrypt your mail session even if
 116         SSL is not available.
 117
 118 --disable-nls
 119         This switch disables mutt's native language support.
 120
 121 --with-included-gettext
 122         Mutt will be built using the GNU gettext library included in
 123         the intl/ sub-directory.  You may need to use this switch if
 124         your machine has something which looks like gettext to the
 125         configure script, but isn't able to cope with mutt's catalog
 126         files.
 127
 128 --with-regex
 129         use GNU regex instead of local regexp routines.  Many systems
 130         don't have the POSIX compliant regcomp/regexec/regfree
 131         routines, so this provides a way to support them.
 132
 133 --enable-flock
 134         use flock() to lock files.
 135
 136 --disable-fcntl
 137         by default, Mutt uses fcntl() to lock files.  Over NFS this can
 138         result in poor performance on read/write.  Note that using this
 139         option could be dangerous if dotlocking is also disabled.
 140
 141 --enable-nfs-fix
 142         some implementations of NFS do not always write the
 143         atime/mtime of small files.  This means that Mutt's ``mailboxes''
 144         feature does not always work properly, as it uses these
 145         attributes to work out whether the file has new mail.  This
 146         option enables a workaround to this bug.
 147
 148 --enable-locales-fix
 149         on some systems, the result of isprint() can't be used reliably
 150         to decide which characters are printable, even if you set the
 151         LANG environment variable.  If you set this option, Mutt will
 152         assume all characters in the ISO-8859-* range are printable.  If
 153         you leave it unset, Mutt will attempt to use isprint() if either
 154         of the environment variables LANG, LC_ALL or LC_CTYPE is set,
 155         and will revert to the ISO-8859-* range if they aren't.
 156         If you need --enable-locales-fix then you will probably need
 157         --without-wc-funcs too. However, on a correctly configured
 158         modern system you shouldn't need either (try setting LANG,
 159         LC_ALL or LC_CTYPE instead).
 160
 161 --without-wc-funcs
 162         by default Mutt uses the functions mbrtowc(), wctomb() and
 163         wcwidth() provided by the system, when they are available.
 164         With this option Mutt will use its own version of those
 165         functions, which should work with 8-bit display charsets, UTF-8,
 166         euc-jp or shift_jis, even if the system doesn't normally support
 167         those multibyte charsets.
 168
 169         If you find Mutt is displaying non-ascii characters as octal
 170         escape sequences (e.g. \243), even though you have set LANG and
 171         LC_CTYPE correctly, then you might find you can solve the problem
 172         with either or both of --enable-locales-fix and --without-wc-funcs.
 173
 174 --with-exec-shell=SHELL
 175         on some versions of unix, /bin/sh has a bug that makes using emacs
 176         with mutt very difficult.  If you have the problem that whenever
 177         you press control-G in emacs, mutt and emacs become very confused,
 178         you may want to try using a Bourne-derived shell other than
 179         /bin/sh here.  Some shells that may work are bash, zsh, and ksh.
 180         C shells such as csh and tcsh will amost certainly not work right.
 181         Note that this option is unrelated to what shell mutt gives you
 182         when you press '!'.  Only use this option to solve the above problem,
 183         and only specify one of the above shells as its argument.
 184
 185         (If you encounter this problem with your platform's native
 186         Bourne shell, please send a short report to mutt-dev@mutt.org,
 187         so a short note on this topic can be added to the Platform notes
 188         section below.)
 189
 190 --enable-exact-address
 191         By default, Mutt will rewrite all addresses in the form
 192                 Personal Name <user@host.domain>
 193         regardless of the input.  By enabling this option, Mutt will write
 194         addresses in the same form they are parsed.  NOTE: this requires
 195         significantly more memory.
 196
 197 Once ``configure'' has completed, simply type ``make install.''
 198
 199 Mutt should compile cleanly (without errors) and you should end up with a
 200 binary called ``mutt.''  If you get errors about undefined symbols like
 201 A_NORMAL or KEY_MIN, then you probably don't have a SysV compliant curses
 202 library.  You should install either ncurses or S-Lang (see above), and then
 203 run the ``configure'' script again.
 204
 205 Please note that "VPATH" builds currently only work with GNU make (gmake).
 206
 207
 208
 209 Character set support
 210 =====================
 211
 212 Mutt no longer contains functions for doing character set conversion.
 213 Instead, it expects the iconv functions (iconv_open, iconv,
 214 iconv_close) to be provided. Most up-to-date systems provide these
 215 functions, often as part of the C library. If you are installing Mutt
 216 on a system which does not have them, it is recommended that you
 217 install Bruno Haible's portable libiconv library, which you can obtain
 218 from:
 219
 220                ftp://ftp.ilog.fr/pub/Users/haible/gnu/
 221
 222 Even if your system does provide the iconv functions, you might want
 223 to install libiconv, as some systems provide only a very limited
 224 version of iconv.
 225
 226
 227 If you decide to use your system's iconv implementation, you may
 228 need to tell mutt about implementation-defined names for some
 229 character sets.  Sample configuration files for various systems can
 230 be found in the directory contrib/iconv/ in this source
 231 distribution, and will be installed in the samples/iconv directory
 232 as part of mutt's documentation.
 233
 234 In order to use these sample configuration files, just put a line
 235 like
 236
 237      source /usr/local/doc/mutt/samples/iconv/iconv.osf1-4.0d.rc
 238
 239 into your system's global Muttrc, which normally resides in /etc or
 240 /usr/local/etc.
 241
 242
 243 If you really want to, you can configure Mutt --disable-iconv, but
 244 there will then be no character set conversion.
 245
 246
 247 Platform Notes
 248 ==============
 249
 250 All platforms
 251
 252         There is a bug in most (if not all) S-Lang versions which
 253         prevents the Meta key from working with mutt.  A patch can
 254         be found in the file contrib/patch.slang-1.2.2.keypad.1 in
 255         this mutt distribution.
 256
 257
 258 Solaris 2.4
 259
 260         The system regcomp() and regexec() routines are very badly
 261         broken.  This should be automatically detected by the
 262         configure script.  If not, use the --with-regex switch when
 263         configuring mutt.
 264
 265         We are also hearing reports that Solaris 2.4's NLS libraries
 266         dump core with mutt when using a locale different from "C".
 267         Use the --with-included-gettext configuration switch if you
 268         experience this problem.
 269
 270         Color does not work right with Solaris curses.  You will
 271         have to compile with either ncurses or slang to get working
 272         color support.
 273
 274 Solaris 2.6
 275
 276         There are reports that mutt behaves strangely when linked with
 277         the system regexp library.  Please use the --with-regex switch
 278         when configuring on this platform.
 279
 280         For the real fix, applying Sun patches # 105490-05 (linker
 281         patch) and # 105210-17 (libc and malloc patch) from
 282         sunsolve.sun.com has been reported to stop these problems
 283         from occuring.
 284
 285 Linux
 286
 287         On recent Linux systems, flock() and fcntl() locks don't mix.  If
 288         you use the --enable-flock switch on such systems, be sure to
 289         give the --disable-fcntl argument as well.
 290
 291 Sparc Linux
 292
 293         Redhat 4.2 Sparc users reported problems with some system
 294         include files when building mutt.  Configuring mutt with the
 295         --disable-warnings switch is said to help against this problem.
 296
 297
 298 Digital Unix (OSF/1)
 299
 300         The system curses library is said to be badly broken.  Use GNU
 301         ncurses or SLang instead.