a_main_doc_dump(), main(): sort after long options in --long-help

[s-mailx.git] / make.rc

#@ make.rc defines the set of features and values used.
#@ Reading INSTALL (first) is beneficial.
#@
#@ - Choosing a predefined CONFIG= disallows further option fine-tuning.
#@   (With some exceptions, e.g., OPT_DEBUG.)
#@
#@ - Specifying settings on the command line will take precedence over
#@   the variables in here (correctly triggering build updates as
#@   necessary, too).
#@
#@ - Features / options have an OPT_ prefix and usually need to be
#@   assigned a boolean value, as in OPT_IDNA=yes.  Booleans are 1/0,
#@   y/n, true/false, yes/no and on/off (case does not matter).
#@
#@   The value "require" is also a true boolean, but will in addition
#@   cause configuration to fail if the requested condition cannot be
#@   satisfied.  "require" is available where documented only.
#@
#@ - Values have a VAL_ prefix, and are assigned strings, for example
#@       VAL_PREFIX="/usr/local"
#@
#@   Values which are only used during configuration, building, and / or
#@   installation have no prefix, e.g., DESTDIR, VERBOSE, awk, sed etc.
#@   Strings which contain whitespace need to be quoted.
#@
#@   Some values offer "multiple choice" values, e.g., VAL_RANDOM
#@   (without accompanying feature option) and VAL_IDNA (with OPT_IDNA).
#@   They address the case of different implementations, and can then be
#@   used to choose the desired one(s).
#@   The value must be a comma-separated list of strings, for example
#@   "idn2,idn,idnkit", the case is ignored, but the order is important.
#@   The special strings "all" and "any" as well as the empty value
#@   are wildcard matches; if any entry in the list is a wildcard match,
#@   the entire list is ignored.
#@   The special string "error" will abort configuration once its list
#@   position is reached; this is only supported if documented, and not
#@   with an accompanying OPT_ (which then offers "require", as above).
#@
#@ - This file is parsed by the shell: it is in sh(1), not in make(1)
#@   syntax.  Evaluation occurs *after* it has been read, so command
#@   line overwrites take effect.  To use multiline values, escape the
#@   newlines on all lines but the last with a reverse solidus (back-
#@   slash), as in "LINE \".
#@   To embed a shell variable unexpanded, use two: "XY=\\${HOME}".
#@   The parsing is sequential top-to-bottom (nonetheless), so that
#@   shell snippets in a value can refer only to stuff yet defined.
#@
#@ - You may NOT comment out anything in here -- if you want to disable
#@   a feature, set it to a false boolean.

## IDENTITIES, PATHS AND PROGRAMS ##

# Contact info (end up as the INTERNAL VARIABLES *contact-mail* and
# *contact-web*, respectively).
VAL_CONTACT_MAIL=s-mailx@lists.sdaoden.eu
VAL_CONTACT_WEB=https://www.sdaoden.eu/code.html

# The user ID our small privilege-separated dotlock helper program will
# be SETUID to, shall it be included ($OPT_DOTLOCK).
# Installation will then require the chown(1) program (as below) and
# sufficient privileges to perform a SETUID to this user ID.
VAL_PS_DOTLOCK_USER=root

# General prefix of installation.
VAL_PREFIX=/usr/local

# Fine tune individual locations, normally under $VAL_PREFIX.
# . the place of normal binaries.
VAL_BINDIR=${VAL_PREFIX}/bin
# . the place of privilege-separated binaries, names of which are
#   ${VAL_SID}${VAL_MAILX}-foo ($VAL_SID and $VAL_MAILX are below).
#   (Only with: $OPT_DOTLOCK.)
VAL_LIBEXECDIR=${VAL_PREFIX}/libexec
# . of the manual.
VAL_MANDIR=${VAL_PREFIX}/share/man
# . of the exemplary resource file.
VAL_SYSCONFDIR=${VAL_PREFIX}/etc

# The variable $DESTDIR is prepended to all the paths from above at
# installation time; this feature can be used for, e.g., package
# building: if $VAL_PREFIX is "/usr/local", but $DESTDIR is "here",
# then $VAL_PREFIX is still "/usr/local" whereas the build system
# will instead use "here/usr/local".
# NOTE: it cannot be set in here, but must be given on the command
# line when running the "install" make(1) rule.
# (That is, if you uncomment it, it will be update-tracked.)
#DESTDIR=

# Where the local mail system stores user $MAIL files.
VAL_MAIL=`\
   if [ -d /var/spool/mail ]; then \
      echo /var/spool/mail;\
   else \
      echo /var/mail;\
   fi`

# Path to the local MTA (Mail-Transfer-Agent).
# MTA aliases (aliases(5)) are optionally supported via OPT_MTA_ALIASES.
VAL_MTA=`\
   if [ -x /usr/bin/sendmail ]; then \
      echo /usr/bin/sendmail;\
   elif [ -x /usr/lib/sendmail ]; then \
      echo /usr/lib/sendmail;\
   else \
      echo /usr/sbin/sendmail;\
   fi`

# 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 often 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.
VAL_MTA_ARGV0=sendmail

# Default $SHELL (sh(1) path).
# (Sometimes however we simply invoke a command directly via execlp(3)
# instead of indirectly through $SHELL -- in these cases execlp(3) may
# fallback to it's own built-in sh(1) path.)
VAL_SHELL=/bin/sh

# Some more default fallback values, some of which are standardized
# and (thus)/or documented in the manual (changes not reflected there!).
# Note that default paths are often not (shell) quoted when displayed.
VAL_DEAD_BASENAME=dead.letter
VAL_DEAD=~/${VAL_DEAD_BASENAME}
VAL_EDITOR=ed
VAL_LISTER=ls
VAL_MAILRC=~/.mailrc
VAL_MBOX=~/mbox
VAL_NETRC=~/.netrc
VAL_PAGER=more
VAL_TMPDIR=/tmp
VAL_VISUAL=vi

# Default locations of mime.types(5).
VAL_MIME_TYPES_USR=~/.mime.types
VAL_MIME_TYPES_SYS=/etc/mime.types

# Default screen width.  The width is reduced by 1 for compatibility
# with some old terminals; if termcap/terminfo support is available then
# we will use the full width if possible.
# Values must be decimal numbers, SHOULD > 10, MUST < 1000.
VAL_HEIGHT=24
VAL_WIDTH=80

# The following tools may be provided a.k.a. overwritten,
# `command -v NAME` is used to query the utility otherwise:
#  STRIP=, awk=, basename=, cat=, chmod=, cp=, cmp=, cksum=, getconf=
#     grep=, ln=, mkdir=, mv=, pwd=, rm=, sed=, sort=, tee=, tr=, uname=
# Usually in administrator paths:
#  chown= [$OPT_DOTLOCK]
# Note that awk(1), rm(1), tr(1) and uname(1) are needed before this
# file is read, all other utilities will be checked afterwards only.
# uname(1) is in fact needed before the initial OS setup and thus no OS
# specific adjustments (e.g., $PATH) have been performed yet, but its
# use can be circumvented by setting $OS (uname -s) and $OSFULLSPEC
# (uname -a: this is not baked into the binary, it is only used to
# recognize build environment changes).
# Due to the evaluation order of the build system all those programs are
# usually needed, but by setting any of the variables to true(1), as in
# chown=/usr/bin/true, availability of unneeded programs can be faked.

## FEATURE SET ##

# Some operating systems only support the C/POSIX (7-bit, but eight bit
# bytes are passed through unchanged) and UTF-8 based locales, e.g.,
# Plan9, Musl based Linux variants and newer OpenBSD.  For such
# environments we can avoid a lot of tests and may enable support for
# features which would otherwise not be available.
# Note: $OS is available as normalized all-lowercase upon evaluation.
OPT_ALWAYS_UNICODE_LOCALE=`\
   if [ "${OS}" = openbsd ] || [ -f /lib/ld-musl-x86_64.so.1 ]; then \
      echo yes;\
   else \
      echo no;\
   fi`

# It is possible to compile as "single-source", meaning that all source
# files are injected into a single compilation unit.
# This allows the compiler to perform more optimizations, and also
# reduces the management overhead of the runtime linker.  In theory.
# (Note this meant as a pure optimization, the make(1)file system will
# offer no source dependency tracking in this mode.)
OPT_AMALGAMATION=no

# Shall the build try to automatically detect a compiler and detect and
# provide a set of known-good compiler flags?  It will use $CC if this
# variable is set, otherwise a compiler is actively searched for.
# If this option is chosen additions to flags may still be provided
# by setting $EXTRA_CFLAGS and $EXTRA_LDFLAGS to whatever is desired.
# Thus: set this to false and use your normal $CC / $CFLAGS / $LDFLAGS,
# otherwise pass additional flags via $EXTRA_CFLAGS / $EXTRA_LDFLAGS:
#     $ make EXTRA_CFLAGS=-std=c99 tangerine
# Whatever you do, the configuration is fixated and updates will force
# rebuilds.
OPT_AUTOCC=yes

   # With $OPT_AUTOCC we will use stack protector guards shall the
   # detected compiler support them; this goes in line with our own
   # (heap) memory canaries and will detect buffer overflows.  Usually
   # only useful during development, but often always enabled today.
   OPT_AUTOCC_STACKPROT=yes

# Whether the commands `csop', `vexpr' .. shall be included.
# v15compat: until v15 VEXPR needs CSOP.
OPT_CMD_CSOP=yes
OPT_CMD_VEXPR=yes

# A simple form of coloured output can optionally be produced.
OPT_COLOUR=yes

# For cross-compilation purposes it may be useful to not actually run
# systemcall etc. tests (link and run the executable) but only to
# perform the link tests necessary to detect host environment.
OPT_CROSS_BUILD=no

# We may include `help' etc. strings for commands, increasing size a bit.
OPT_DOCSTRINGS=yes

# File dotlocking is performed for "system mailbox" (%[USER] and
# %:ANYFILE) MBOX files: when synchronizing any such FILE a FILE.lock
# file will be created in the directory of FILE, for the duration of the
# synchronization: set $OPT_DOTLOCK to support this traditional mail
# spool file locking.
# $VAL_MAIL(s) where normal system mailboxes reside are usually not
# writable by normal users, except that a user may read and write his
# own mailbox.  But this means that a program run by the user cannot
# create a .lock file!  The solution is to install a privilege-separated
# mini-program that has the sole purpose and functionality of managing
# the dotlock file in such situations -- and only then, as a last
# ressort.  With it dotlock files can be created for any mailbox for
# which the invoking user has read (or read-write) permissions, and
# under the UID and GID of the mailbox itself!  We call it -dotlock.
# It will be SETUID to VAL_PS_DOTLOCK_USER, as above.
# $OPT_DOTLOCK can be "require"d.
OPT_DOTLOCK=yes

# Enable the `errors' command; as a console-based application errors
# may fly by pretty fast as other operations are in progress;
# or $PAGERs are started and clear errors off the screen.
# If enabled errors will be duplicated to an error queue as they happen
# and the `errors' command will show them when asked to.
# VAL_ERRORS_LIMIT will be the default value of *errors-limit*.
OPT_ERRORS=yes
VAL_ERRORS_LIMIT=8000

# We do have a very primitive HTML tagsoup filter which can be used to
# convert HTML to plain text for display purposes.  If enabled it will
# be used for all MIME types which have the corresponding type marker
# (more on this in the manual section "The mime.types files").  And
# which do not have any user defined MIME type handler, of course.
OPT_FILTER_HTML_TAGSOUP=yes

# 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.
# Can be "require"d.
# TODO should not wrap lines when only WS or a NL-escaping \ follows
OPT_FILTER_QUOTE_FOLD=yes

# 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.
# Multiple implementations are supported:
# . libc (whether iconv(3) available in C library).
# . iconv (via external iconv library, for example GNU libiconv,
#     https://www.gnu.org/software/libiconv).
# This should usually be enabled; it can be "require"d.
OPT_ICONV=yes
VAL_ICONV=libc,iconv

# 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>.  :)
# Multiple implementations are supported:
# . idnkit - idnkit, https://www.nic.ad.jp/ja/idn/idnkit/download,
#     either of version 1 for IDNA 2003 or version 2 for IDNA 2008.
# . idn2 - GNU Libidn2 for IDNA 2008, https://www.gnu.org/software/libidn/,
# . idn - GNU Libidn for IDNA 2003, same,
# OPT_IDNA can be "require"d.
OPT_IDNA=yes
VAL_IDNA=idnkit,idn2,idn

# 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.
OPT_IMAP_SEARCH=yes

# Support for RFC 1524 a.k.a mailcap files can be made available.
# The search order when looking up MIME type handlers for display /
# quoting purposes is then *pipe-EXTENSION*, *pipe-TYPE/SUBTYPE*,
# mailcap entry, `mimetype's type-marker extension.
# For other purposes mailcap entries are used exclusively.
# RFC 1524 specifies the default $VAL_MAILCAPS path search as follows,
# and it specifies the $MAILCAPS environment variable to override it.
OPT_MAILCAP=yes
VAL_MAILCAPS=~/.mailcap:/etc/mailcap:/usr/etc/mailcap:/usr/local/etc/mailcap

# Whether support for Maildir email directories shall be enabled.
OPT_MAILDIR=yes

# Line editing and -history (manual "On terminal and line editor").
# If ISO C (ISO/IEC 9899:1990/Amendment 1:1995) is supported on the
# system then our built-in MLE (Mailx-Line-Editor) version can be used.
# An enabled & available OPT_TERMCAP may affect and improve the MLE.
# Can be "require"d.
OPT_MLE=yes

   # Add support for `history' management.
   OPT_HISTORY=yes

   # Add support for `(un)?bind'ing of key sequences.
   OPT_KEY_BINDINGS=yes

   # Use termcap(5) for MLE terminal control; can be "require"d.
   # Today most environments ship a termcap(5) that in fact is part of
   # terminfo(5), and acts as a converting wrapper for this library.
   # To avoid this redundancy we also support terminfo(5), and use it
   # instead if we find it (assuming that termcap(5) is a stub, then).
   # Note that terminfo(5) offers access to more key sequences, e.g.,
   # kLFT5, for which no termcap(5) entry exists.
   # terminfo(5) support can (thus) be "require"d.
   OPT_TERMCAP=yes
      OPT_TERMCAP_VIA_TERMINFO=yes

# Whether support for MTA aliases(5) shall be included.
# With it, and if *mta-aliases* is set to a file, MTA aliases will be
# expanded as a last step before messages are sent.
# Note this only supports text-, no database files.
OPT_MTA_ALIASES=yes

# Several different P(seudo) R(andom number) G(enerator) possibilities.
# No need for somewhat strong random is necessary.
# The following will be used as sole PRG implementations.
# . arc4 - we search for arc4random(3).
# . tls - if OPT_TLS is available that libraries' PRNG can be used.
# The following will only be used to seed our builtin ARC4 PRNG.
# . libgetrandom - getrandom(3) via C library.
# . sysgetrandom - getrandom(2) via SYSCALL.
# . getentropy - getentropy(3) (a la POSIX: with GETENTROPY_MAX).
# . urandom - reading from /dev/urandom.
# . builtin - unscientific seeding for our builtin ARC4 implementation.
# . (error - bail out)
VAL_RANDOM=arc4,tls,libgetrandom,sysgetrandom,getentropy,urandom,builtin

# Regular expression (re_format(7)) support for searches, conditional
# expressions etc., we use the extended ones, then; can be "require"d.
OPT_REGEX=yes

# Major switch to toggle *all* network related protocols
# (POP3,SMTP,IMAP) and related/dependent stuff (GSS-API,TLS);
# can be "require"d.
OPT_NET=yes

   # Detect support for GSS-API (Generic Security Services Application
   # Programming Interface) based authentication, e.g., Kerberos v5?
   # Available for IMAP and SMTP; can be "require"d.
   OPT_GSSAPI=yes

   # Add support for IMAP protocol.
   # Reading of mails directly on the server.
   # Requires $OPT_ICONV unless $OPT_ALWAYS_UNICODE_LOCALE, in which
   # case it only warns.  Can be "require"d.
   OPT_IMAP=yes

   # The MD5 message digest (RFC 1321) enables several authentication
   # possibilities for POP3 (APOP), IMAP and SMTP (CRAM-MD5).
   OPT_MD5=yes

   # Support for parsing of user and password credentials from the
   # ~/.netrc file ($NETRC; see *netrc-lookup* manual entry).
   OPT_NETRC=yes

   # Add support for POP3 protocol.
   # Download of mails via POP protocol.  Can be "require"d.
   OPT_POP3=yes

   # Add support for SMTP (and SUBMISSION) protocol.
   # Sending mails directly over the network.  Can be "require"d.
   OPT_SMTP=yes

   # Detect support for Secure Socket Layer (Transport Layer Security,
   # TLS), i.e., encrypted socket connections; can be "require"d.
   # It also automatically enables support for S/MIME message signing,
   # verification, en- and decryption.
   # Supported are the OpenSSL (https://www.openssl.org) and LibreSSL
   # (http://www.libressl.org) libraries.
   OPT_TLS=yes

      # If $OPT_TLS: shall mechanisms to support more digest and cipher
      # algorithms than the few that are documented be used?
      # For S/MIME *smime-cipher* for example this will cause
      # EVP_get_cipherbyname(3) to be tried shall the built-in knowledge
      # not suffice to understand the user request.
      # Will create a large statically linked binary; dynamically linked
      # the costs only arise once the extended lookup is actually needed
      # (the first time).  Some TLS libraries will always support all
      # algorithms.  This can be "require"d.
      OPT_TLS_ALL_ALGORITHMS=yes

# Interaction with a spam email filter is possible.
# Refer to all commands and variables with a "spam" prefix, and
# see the manual example section "Handling spam".
# . OPT_SPAM_FILTER:
#   Generic filter hook which can be used with e.g. bogofilter(1)
#   and sylfilter(1): see documentation for the *spam-filter-**
#   variables for expected application behaviour.
# . OPT_SPAM_SPAMC:
#   Support for interaction with spamassassin(1)s spamc(1).
OPT_SPAM_FILTER=yes
OPT_SPAM_SPAMC=no

# Removing (almost) all user interface and error messages is possible.
# This might be interesting for automated use cases (only).
OPT_UISTRINGS=yes

# Whether package system, for example pkgsrc(7) on NetBSD and more,
# OpenCSW on SunOS/Solaris, etc., specific paths shall be automatically
# included in $C_INCLUDE_PATH and $LD_LIBRARY_PATH when seen?
OPT_USE_PKGSYS=yes

##  --  >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 built by concatenating $VAL_SID and $VAL_MAILX:
# $(VAL_SID)$(VAL_MAILX).  Note that the final string must be longer
# than two characters, must fit _easily_ in NAME_MAX-1, must not contain
# any whitespace, and must not contain multibyte sequences.
VAL_SID=s-
VAL_MAILX=nail

# The name of the exemplary resource template.
# Note 1: not overwritten by "make install" if yet exists!
VAL_SYSCONFRC=${VAL_SID}${VAL_MAILX}.rc

## FEATURE SET, DEVELOPMENT ##

# With $OPT_AUTOCC we can make use of the ASan AddressSanitizer and ASan
# MemorySanitizer of Google
# (https://github.com/google/sanitizers/wiki/AddressSanitizer).
# Also USAN (https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html).
# These are definitily only useful for debugging.
# Also, external libraries are often problematic (e.g., ncursesw), and
# ASAN_MEMORY of the tried clang 4.0.0 (4.0.0-2 of ArchLinux) was faulty.
# Can be "require"d.
OPT_ASAN_ADDRESS=no
OPT_ASAN_MEMORY=no
OPT_USAN=no

# Use debug compiler flags, enable code assertions and memory canaries,
# which require a rather large amount of runtime memory.
OPT_DEBUG=no

# Development only.
OPT_DEVEL=no

# We use the crypto libraries' MD5 implementation if possible, unless..
OPT_NOEXTMD5=no

# If $OPT_DEBUG is true we will use a simple memory wrapper with
# canaries.  This interferes with memory debuggers like valgrind(1) or
# the LLVM -fsanitize stuff.  Enable this to not use our wrapper.
OPT_NOMEMDBG=`\
   if feat_yes ASAN_MEMORY || feat_yes ASAN_ADDRESS; then \
      echo yes;\
   else \
      echo no;\
   fi`

# vim:set tw=72: s-it-mode