README: tweaks

[s-mailx.git] / conf.rc

#@ conf.rc can be used adjust the set of desired features, paths, etc.
#@ You should have read `INSTALL' first.
#@ Notes:
#@ . This file is parsed by the shell: it is in sh(1), not in make(1) syntax.
#@ . Choosing one of the predefined CONFIG= sets overwrites a lot of items
#@   that can be set in here
#@ . Specifying settings on the command line will take precedence over the
#@   variables in here (correctly triggering build updates as necessary)
#@ . Using one of the predefined CONFIG= sets overrides anything else
#@ . You may NOT comment out anything in here -- if you want to disable a
#@   feature, simply set it to `0'.  (It won't work properly otherwise!)

## FEATURE SET ##
#
# The variables in here can be used to adjust the feature set of S-nail.
# Only if a variable is set to `1' it is treated as being `set'.
# Only a `set' variable will cause the possibly necessary feature tests to be
# performed, so as to detect wether the wanted feature really can be used

# S-nail automatically detects compilers and has a set of known compiler flags
# which work well.  Since users should be able to define their own $CC, $CFLAGS
# and $LDFLAGS, however, it only uses the detected environment if the user
# forces their usage via setting WANT_AUTOCC=1.  (Except for $CC, which is
# always set if it's empty or set to "cc".)
# Note: it is possible to add to the detected values by setting ADDCFLAGS="xy"
# and/or ADDLDFLAGS="xy" -- "configuration-has-changed" detection will work on
# the final $CC / $CFLAGS / $LDFLAGS, and thus will include those additions
# Thus: set this to 0 and use your normal $CC / $CFLAGS / $LDFLAGS, set this to
# 1 and pass additional flags via ADDCFLAGS / ADDLDFLAGS.
# Whatever you do, the configuration is fixated and updates will force rebuilds
WANT_AUTOCC=1

# It is possible to compile S-nail as a "single-source", meaning that all
# source files are injected into a single compilation unit, which is then
# compiled.  This allows the compiler to perform much more optimizations, and
# also reduces the management overhead that is used for / needed by the linker.
# Of course compiling such a large source requires a lot of memory by itself
WANT_AMALGAMATION=0

# Major switch to toggle *all* network related protocols (IMAP,POP3,SMTP) and
# related/dependent stuff (GSS-API,SSL)
WANT_SOCKETS=1

# If WANT_SOCKETS, should the IPv6 family of functions be searched for and
# compiled into the program if found?
# TODO NOTE:
# TODO S-nail does not yet support IPv6 address notation, as in, e.g.,
# TODO imaps://user1@::1 (or @[::1]), but it will happily establish a
# TODO connection to imaps://user1@host1 if host1 listens via IPv6
WANT_IPV6=1

# Support for SecureSocketLayer (TransportLayerSecurity, TLS), i.e.,
# encrypted socket connections.
# This needs OpenSSL libraries (<http://www.openssl.org>; these should be
# installed by default on practically all operating systems today, though)
WANT_SSL=1

# Support for IMAP protocol?  (Reading of mails directly on the server)
WANT_IMAP=1

# Support for POP3 protocol?  (Download of mails via POP over the network)
WANT_POP3=1

# Support for SMTP protocol?  (Directly sending mails over the network)
WANT_SMTP=1

# Support for GSS-API (Generic Security Services Application Programming
# Interface) based authentication, e.g., Kerberos v5?
WANT_GSSAPI=1

# Support for parsing of user and password credentials from ~/.netrc ($NETRC)
# can optionally be supported (see *netrc-lookup*)
WANT_NETRC=1

# Passwords can also be looked up through an external "agent" in order to allow
# for encrypted password storage (see *agent-shell-lookup*)
WANT_AGENT=1

# Several facilities use the MD5 message digest, but for some of them it is
# only used for optional features (POP3: APOP authentification, IMAP: CRAM-MD5
# authentification, SMTP: CRAM-MD5 authentification).
# If you don't need those, you may exclude MD5 from S-nail.
# Note that WANT_MD5 is automatically turned off if its exclusion will only
# affect MIME boundary strings and Message-Id: fields
WANT_MD5=1

# Character set conversion enables reading and sending of mails in multiple
# character sets through usage of the iconv(3) library.
# Please read the manual section "Character sets" for the complete picture.
# This should usually be enabled
WANT_ICONV=1

# IDNA (internationalized domain names for applications) offers users the
# possibility to use domain names in their native language, i.e., to use
# non-US-ASCII content, as in, e.g., <www.räksmörgåsa.example>, which the IDNA
# algorithm would convert to <www.xn--rksmrgsa-0zap8p.example>.  :)
# This needs the GNU Libidn library (<https://www.gnu.org/software/libidn/>)
WANT_IDNA=1

# IMAP-style SEARCH expressions can be supported.
# This addressing mode is available with all types of folders; for folders not
# located on IMAP servers, or for servers unable to execute the SEARCH command,
# the search is performed locally
WANT_IMAP_SEARCH=1

# Regular expression (re_format(7)) support for searches, conditional
# expressions etc.
WANT_REGEX=1

# Command line editing and -history.
# S-nail actually supports three different command line editors, one builtin
# and two fully fledged external libraries which may offer a slightly better
# user experience at the cost of more memory usage and CPU time; also the
# interactive behaviour may not be one-to-one to what is documented.
# Note that these are tested in shown order, and each desired one must be
# enabled by itself!
# . WANT_READLINE
#   The GNU readline(3) compatible interface
# . WANT_EDITLINE
#   Command line editing via BSD editline(3)
# . WANT_NCL
#   If ISO C (ISO/IEC 9899:1990/Amendment 1:1995) is supported on the system
#   then our builtin NCL (Nail Command Line editor) version can be used.
#   It is documented in the manual section "Command line editor" (in ./nail.1)
WANT_READLINE=0
WANT_EDITLINE=0
WANT_NCL=1
# For all command line editors we optionally support history management
WANT_HISTORY=1
# For the NCL command line editor we optionally support "expand-on-tabulator".
# Turning it off shrinks the binary.  Please see the respective manual entry
WANT_TABEXPAND=1

# Interaction with a spam email filter is possible.
# Refer to all commands with a `spam' prefix, and see the manual section
# "Handling spam" (`./nail.1')
WANT_SPAM=1

# If given an optional argument the `help' command will print a help string
# only for the mentioned command; those strings take up space and so one may
# disable this feature
WANT_DOCSTRINGS=1

# A simple line-based quoting mechanism can be made available via the
# *quote-fold* mechanism.
# This will be turned off automatically if the required character
# classification is not available on the host.
# TODO shouldn't wrap lines when only WS or a NL-escaping \ follows
WANT_QUOTE_FOLD=1

# A simple form of coloured output can optionally be produced (see manual)
WANT_COLOUR=1

## PATHS AND PROGRAMS ##

# General prefix where S-nail should be installed
PREFIX=/usr/local

# Fine tune individual locations, normally under $PREFIX
# . the place of the S-nail program
BINDIR="${PREFIX}/bin"
# . of the manual
MANDIR="${PREFIX}/man"
# . of the exemplary resource file
SYSCONFDIR="${PREFIX}/etc"

# This variable is prepended to all the paths from above at installation time;
# this feature can be used for, e.g., package building: if $PREFIX is
# `/usr/local', but $DESTDIR is set to, say, `here', then S-nail will still
# think its $PREFIX is `/usr/local' whereis the build system will instead use
# `here/usr/local'
DESTDIR=

# The directory where the local mail system stores user mail (mbox) files.
# (Only of interest if the local mail system is used)
# xxx Should we `dirname ${MAIL}` if -n ${MAIL} first / instead?
MAILSPOOL=`[ -d /var/spool/mail ] && echo /var/spool/mail || echo /var/mail`

# Path to the local MTA (Mail Transport Agent).
# (Only of interest if the local mail system is used)
SENDMAIL=/usr/sbin/sendmail

# Today a lot of systems no longer use sendmail(1), but a different MTA.
# To ensure compatibility with sendmail(1), a system called mailwrapper(8) is
# used, which selects the required service by looking at the name by which the
# program actually has been invoked.
# This variable can be used to adjust this name as necessary
# (Only of interest if the local mail system is used)
SENDMAIL_PROGNAME=sendmail

# Fallback sh(1) path.
# Note that it is not guaranteed that *all* uses of the shell use this, but it
# may actually happen that execlp(2) will need to fallback to its own one.
# (Note: this is named XSHELL so that it doesn't clash with the POSIX
# standard $SHELL, which would effectively cause this setting to be ignored)
XSHELL=/bin/sh

# The default *LISTER* (in the $PATH).
# (Note: this is named XLISTER so that it doesn't clash with the POSIX
# standard $LISTER, which would effectively cause this setting to be ignored)
XLISTER=ls

# The default *PAGER* (in the $PATH).
# (Note: this is named XPAGER so that it doesn't clash with the POSIX standard
# $PAGER, which would effectively cause this setting to be ignored)
XPAGER=more

# The following tools may be provided a.k.a. overwritten, `command -v NAME`
# is used to query the utility otherwise:
#  MAKE=, STRIP=, awk=, cat=, chmod=, cp=, cmp=, grep=, mkdir=, mv=, tee=
#  rm=, sed=
# Note that rm(1) and sed(1) are needed before this file is read, all other
# utilities will be checked afterwards only.
# For cross-compilation setting MAKE= and STRIP= may be necessary

##  --  >8  --  8<  --  ##

## Normal users should not need to read any further

## PATHS AND PROGRAMS, DEVELOPMENT ##

# To ease the life of forkers and packagers "our" name can be changed.
# The name is build by concatenating $SID and $NAIL, i.e., $(SID)$(NAIL).
# Note that the final string must be longer than two characters and may not
# contain any whitespace
NAIL=nail
SID=s-

# The location of the exemplary resource template.
# Note 1: it's not overwritten if it yet exists!
# Note 2: `make install' assumes it's under $SYSCONFDIR!
SYSCONFRC="${SYSCONFDIR}/${SID}${NAIL}.rc"

## FEATURE SET, DEVELOPMENT ##

# Use debug compiler flags, enable some additional commands (like `sstats',
# `smemtrace'), some code assertions, possibly experimental code etc.
# Note that setting this also enables our own memory canaries, which require
# a rather large amount of runtime memory, and forcefully disables alloca(3)
# stack memory usage (see WANT_NOALLOCA below), so as to be able to track usage
# of stack memory via our memory canaries
WANT_DEBUG=0

# We use the crypto libraries' MD5 implementation if possible unless this one
WANT_NOEXTMD5=0

# The codebase makes a lot of use of alloca(3), and this will remain since
# S-nail will continue to be compliant to ISO C89, which has no variable
# arrays, etc.  For testing purposes it is however nice to use the much slower
# normal S-nail heap memory allocator instead.
# Note: this will be forcefully set (again) if WANT_DEBUG=1
WANT_NOALLOCA="${WANT_DEBUG}"

# Note: this will be forcefully set (again) if WANT_DEBUG=1
WANT_DEVEL=0

# Our functions are instrumented with Not-Yet-Dead chirps, which print
# a function call trace when the program crashes.  Whereas NYD will be used
# automatically when either of WANT_DEBUG and WANT_DEVEL is defined, an
# extended level of NYD is compiled in only on explicit request
# TODO Separation in between NYD and NYD2 not yet fully done
WANT_NYD2=0

# s-it-mode