301 lines
11 KiB
Text
301 lines
11 KiB
Text
Required tools
|
|
--------------
|
|
|
|
If you are planning to hack on mutt, please subscribe to the
|
|
mutt-dev mailing list (mutt-dev@mutt.org). To subscribe, send an
|
|
email with as subject "subscribe" to mutt-dev-request@mutt.org .
|
|
Announcements about recent development versions go to that mailing
|
|
list, as go technical discussions and patches.
|
|
|
|
Patches should, if possible, be made using Git against the latest
|
|
revision.
|
|
|
|
You'll need several GNU development utilities for working on mutt:
|
|
|
|
- autoconf (versions less than 2.59 are unsupported)
|
|
(this package includes autoheader and autoreconf)
|
|
|
|
If the build fails during any of the auto* stages, first of all try if
|
|
re-running the ./prepare script fixes things. Remember to give the
|
|
same options you passed to it or to the configure it generated the
|
|
last time, you can query them with:
|
|
./config.status --version
|
|
|
|
- automake (versions less than 1.9 are not officially supported)
|
|
(this package includes aclocal)
|
|
|
|
Note that you MUST re-run ./prepare (with the original arguments)
|
|
if you change the automake version between builds for the same source
|
|
directory.
|
|
|
|
- GNU make may be needed for the dependency tricks
|
|
|
|
- The internationalization (i18n) stuff requires GNU gettext.
|
|
See intl/VERSION for the version we are currently relying on.
|
|
Please note that using gettext-0.10 will most probably not work -
|
|
get the latest test release from alpha.gnu.org, it's the recommended
|
|
version of gettext anyway.
|
|
|
|
If you are experiencing problems with unknown "dcgettext" symbols,
|
|
the autoconf/automake macros from your gettext package are broken.
|
|
Apply the following patch to that macro file (usually found under
|
|
/usr/share/aclocal/gettext.m4):
|
|
|
|
--- gettext.m4.bak Thu Jul 2 18:46:08 1998
|
|
+++ gettext.m4 Mon Oct 5 23:32:54 1998
|
|
@@ -46,12 +46,13 @@
|
|
|
|
if test "$gt_cv_func_gettext_libc" != "yes"; then
|
|
AC_CHECK_LIB(intl, bindtextdomain,
|
|
- [AC_CACHE_CHECK([for gettext in libintl],
|
|
- gt_cv_func_gettext_libintl,
|
|
- [AC_CHECK_LIB(intl, gettext,
|
|
- gt_cv_func_gettext_libintl=yes,
|
|
- gt_cv_func_gettext_libintl=no)],
|
|
+ [AC_CHECK_LIB(intl, gettext,
|
|
+ gt_cv_func_gettext_libintl=yes,
|
|
gt_cv_func_gettext_libintl=no)])
|
|
+ fi
|
|
+
|
|
+ if test "$gt_cv_func_gettext_libintl" = "yes" ; then
|
|
+ LIBS="-lintl $LIBS"
|
|
fi
|
|
|
|
if test "$gt_cv_func_gettext_libc" = "yes" \
|
|
|
|
|
|
Generating Mutt Documentation From Source
|
|
-----------------------------------------
|
|
|
|
To translate Mutt's Docbook XML documentation into HTML (and then text),
|
|
you'll need one tool and two sets of data which you may need to download
|
|
and install. The tool is xsltproc (part of the libxslt package), and
|
|
it's a command-line program for performing XSL transformations on XML
|
|
documents. The data sets are the Docbook XML and Docbook XSL libraries.
|
|
|
|
Whenever your operating system provides packages or pkgsrc or ports of
|
|
these, you should install them. Some systems, for instance SUSE Linux
|
|
and FreeBSD's ports system, automatically set up a registry of installed
|
|
XML/XSL and SGML catalogs so that the user does not need to care about
|
|
what to install where, how to set environment variables, and so on.
|
|
|
|
If your system does not provide these libraries and data sets,
|
|
you can download them from:
|
|
|
|
. xsltproc
|
|
http://xmlsoft.org/
|
|
ftp://xmlsoft.org/libxslt/libxslt-1.1.17.tar.gz
|
|
|
|
. docbook-xml-4.2
|
|
http://www.docbook.org/
|
|
http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip
|
|
|
|
. docbook-xsl-1.70.1
|
|
http://docbook.sourceforge.net/
|
|
http://prdownloads.sourceforge.net/docbook/docbook-xsl-1.70.1.zip
|
|
|
|
First, if you don't already have xsltproc, build and install libxslt,
|
|
which will provide xsltproc, too.
|
|
|
|
Next, obtain and unpack the two docbook archives. You can unpack these
|
|
anywhere that you want to have them installed -- there's no installation
|
|
procedure other than unarchival. On my Solaris system, I install
|
|
packages under /opt/pkgs/packagename-version, so I unpacked these ZIP
|
|
archives to /opt/pkgs/docbook-xml-4.2 and /opt/pkgs/docbook-xsl-1.70.1.
|
|
|
|
Now you need to create (and export) an environment variable to process
|
|
the manuals. The environment variable will contain a space-separated
|
|
list of "catalog" files for the two docbook archives, so substitute
|
|
the path where you unpacked them below:
|
|
|
|
sh$ XML_CATALOG_FILES="/path/to/docbook-xml-4.2/catalog.xml /path/to/docbook-xsl-1.70.1/catalog.xml"; export XML_CATALOG_FILES
|
|
or
|
|
csh$ setenv XML_CATALOG_FILES "/path/to/docbook-xml-4.2/catalog.xml /path/to/docbook-xsl-1.70.1/catalog.xml"
|
|
|
|
Once all these are installed and XML_CATALOG_FILES is set, you should be
|
|
able to generate manual.html with a simple "make" -- all as a part of
|
|
the mutt compilation.
|
|
|
|
The Makefile depends upon lynx (or any other text-mode web browser)
|
|
to turn the HTML into text, so if that fails you may need to install
|
|
something else.
|
|
|
|
|
|
Getting started from Git
|
|
------------------------
|
|
|
|
The official Git repository is located at:
|
|
https://gitlab.com/muttmua/mutt. You can get a fresh clone via:
|
|
|
|
$ git clone https://gitlab.com/muttmua/mutt.git mutt
|
|
|
|
Once you've checked out a copy of the source, or changed your
|
|
automake version, you'll need to run the script called './prepare' that
|
|
is in the root directory. The script does all the automake/autoconf
|
|
magic that needs to be done with a fresh checkout.
|
|
|
|
|
|
Contributing patches
|
|
--------------------
|
|
|
|
As Git is a distributed version control system, it's easy to
|
|
commit changes locally without impacting anybody else's work, starting
|
|
over again, or turn several commit and backouts into a new single patch
|
|
ready for submission.
|
|
|
|
These so-called "changesets" (a diff with a reasonable message
|
|
describing the change) can be exported using Git through the
|
|
"send-email" command (please see the git documentation for details)
|
|
which also is the preferred format for submission to the mutt-dev
|
|
mailing list for discussion and review.
|
|
|
|
In order to ease later bisecting in case of bugs and code history,
|
|
changes should be grouped logically, feature by feature or bugfix by
|
|
bugfix. Especially a single patch fixing several problems at once
|
|
should be avoided.
|
|
|
|
Before submitting patches, please make sure the check_sec.sh script
|
|
in the top-level source directory reports no errors/warnings.
|
|
Documentation changes should be validated by running 'make validate'
|
|
in the doc subdirectory.
|
|
|
|
|
|
String comparisons
|
|
------------------
|
|
|
|
A word of warning about string comparisons: Since mutt may run in a
|
|
huge variety of locales, case-insensitive string comparisons and
|
|
case conversions may be dangerous. For instance, in iso-8859-9,
|
|
tolower('I') is DIFFERENT from 'i' - it's indeed the Turkish dotless
|
|
lowercase i.
|
|
|
|
For this reason, always use the ascii_* functions defined in ascii.h
|
|
and implemented in ascii.c when comparing or handling strings which
|
|
are defined as us-ascii. This concerns lots of text-based
|
|
protocols, message header tags, character set names, domain names,
|
|
e-mail addresses, etc.
|
|
|
|
|
|
A word about warnings
|
|
---------------------
|
|
|
|
Mutt's default build process sets some pretty restrictive compiler
|
|
flags which may lead to lots of warnings. Generally, warnings are
|
|
something which should be eliminated.
|
|
|
|
Nevertheless, the code in intl/ is said to generate some warnings with
|
|
the compiler settings we usually rely upon. This code is not
|
|
maintained by the mutt developers, so please redirect any comments to
|
|
the GNU gettext library's developers.
|
|
|
|
|
|
Style Guide
|
|
-----------
|
|
|
|
- global functions should have the prefix "mutt_". All
|
|
other functions should be declared "static".
|
|
|
|
- avoid global variables where possible. If one is required,
|
|
try to contain it to a single source file and declare it
|
|
"static". Global variables should have the first letter of
|
|
each word capitalized, and no underscores should be used
|
|
(e.g., MailGid, LastFolder, MailDir).
|
|
|
|
- re-use code as much as possible. There are a lot of
|
|
"library" functions. One of the biggest causes of bloat
|
|
in ELM and PINE is the tremendous duplication of code...
|
|
Help keep Mutt small!
|
|
|
|
- when adding new options, make the old behavior the
|
|
default.
|
|
|
|
- try to keep mutt as portable as possible.
|
|
|
|
- special characters should be in utf-8. If you find remnants
|
|
from the times when this was an iso-8859-1 source code tree,
|
|
please feel free to fix them.
|
|
|
|
- prefix translator comments with L10N:
|
|
/* L10N: this is a translator comment */
|
|
puts(_("String to translate));
|
|
|
|
|
|
|
|
Documentation
|
|
-------------
|
|
|
|
Please document your changes. Note that there are several places
|
|
where you may have to add documentation:
|
|
|
|
- doc/manual.xml.{head,tail} contain The Manual.
|
|
|
|
- doc/muttrc.man.{head,tail} contain an abridged version of The
|
|
Manual in nroff format (see man(7)), which deals with
|
|
configuration file commands.
|
|
|
|
- UPDATING includes short documentation of user-visible
|
|
changes, i.e., any incompatibilities should go here.
|
|
|
|
Configuration _variables_ are documented directly in init.h. Note
|
|
that this includes documentation for possibly added format flags!
|
|
|
|
The parts of The Manual and the muttrc manual page dealing with
|
|
these variables, and the global Muttrc, are generated automatically
|
|
from that documentation. To start this process, type "make
|
|
update-doc" in the top-level source directory.
|
|
|
|
Note that you may have to update the makedoc utility (makedoc.pl)
|
|
when adding new data types to init.h.
|
|
|
|
More precisely, variable name, type, and default value are directly
|
|
extracted from the initializer for the MuttVars array. Documentation
|
|
is expected in special comments which _follow_ the initializer.
|
|
For a line to be included with the documentation, it must (after,
|
|
possibly, some white space) begin with either "/**" or "**".
|
|
Any following white space is ignored. The rest of the line is
|
|
expected to be plain text, with some formatting instructions roughly
|
|
similar to [ntg]roff:
|
|
|
|
- \fI switches to italics
|
|
|
|
- \fB switches to boldface
|
|
|
|
- \fT switches to monospace
|
|
|
|
- \fP switches to normal display after \fI, \fB or \fT
|
|
|
|
- \(as can be used to represent an asterisk (*). This is intended
|
|
to help avoiding character sequences such as /* or */ inside
|
|
comments.
|
|
|
|
- \(rs can be used to represent a backslash (\). This is intended
|
|
to help avoiding problems when trying to represent any of the \
|
|
sequences used by makedoc.
|
|
|
|
- .dl on a line starts a "definition list" environment (name taken
|
|
from HTML) where terms and definitions alternate.
|
|
|
|
- .dt marks a term in a definition list.
|
|
|
|
- .dd marks a definition in a definition list.
|
|
|
|
- .de on a line finishes a definition list environment.
|
|
|
|
- .ts on a line starts a "verbose tscreen" environment (name taken from
|
|
SGML). Please try to keep lines inside such an environment
|
|
short; a length of about 40 characters should be OK. This is
|
|
necessary to avoid a really bad-looking muttrc (5) manual page.
|
|
|
|
- .te on a line finishes this environment.
|
|
|
|
- .pp on a line starts a paragraph.
|
|
|
|
- $word will be converted to a reference to word, where appropriate.
|
|
Note that $$word is possible as well.
|
|
Use $$$ to get a literal $ without making a reference.
|
|
|
|
- '. ' in the beginning of a line expands to two space characters.
|
|
This is used to protect indentations in tables.
|
|
|
|
Do _not_ use any other SGML or nroff formatting instructions here!
|
|
|