README

   1 GNU `m4' is an implementation of the traditional Unix macro
   2 processor.  It is mostly SVR4 compatible, although it has some
   3 extensions (for example, handling more than 9 positional parameters
   4 to macros).  `m4' also has builtin functions for including files,
   5 running shell commands, doing arithmetic, etc.  Autoconf needs GNU
   6 `m4' for generating `configure' scripts, but not for running them.
   7
   8 GNU `m4' was originally written by Rene' Seindal, from Denmark.
   9
  10 GNU `m4' has a web site at http://www.gnu.org/software/m4/.
  11
  12 If GNU `m4' is meant to serve GNU `autoconf', beware that `m4'
  13 should be fully installed *prior to* configuring `autoconf' itself.
  14 Likewise, if you intend on hacking GNU `m4' from git, the bootstrap
  15 process requires that you first install a released copy of GNU `m4'.
  16
  17 If you are just trying to build `m4' from a released tarball, you
  18 should not normally need to run `./bootstrap' or `autoreconf'; just go
  19 ahead and start with `./configure'.  If you are trying to build `m4'
  20 from git or CVS, more information can be found in the file HACKING,
  21 only found in a version control checkout.
  22
  23 In the subdirectories `tests' and `examples' you will find various m4
  24 files, ranging from trivial test files to rather advanced macros.  If
  25 you intend to use m4 seriously, you might find useful material down
  26 there.
  27
  28 See file `COPYING' for copying conditions.
  29 See file `INSTALL' for compilation and installation instructions.
  30 See file `ABOUT-NLS' for how to customize this program to your language.
  31 See file `NEWS' for a list of major changes in the current release.
  32 See file `AUTHORS' for the names of maintainers.
  33 See file `THANKS' for a list of contributors.
  34
  35 By using `./configure --with-gmp, you get multiple precision integral
  36 and rational arithmetic using mpeval.  The implementation depends on the
  37 GNU gmp v2 library.
  38
  39 By using `./configure --with-modules=`foo bar baz', you get an m4 with only
  40 the named modules preloaded.  The default modules (preloaded if you do not
  41 use this option) are sufficient to do the job of GNU m4-1.4.  Additional
  42 modules may be desirable, or necessary if libltdl does not support your
  43 host architecture.  The implementation uses libltdl interface, details of
  44 which are in the libtool manual.  See file `modules/README' for a more
  45 detailed description.
  46
  47 By using `./configure --with-dmalloc', GNU m4 is linked with Gray
  48 Watson's dmalloc package.  It is a debugging option for finding memory
  49 management problems.  Gray Watson's dmalloc package is available at
  50 ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz.
  51
  52 GNU M4 uses GNU Libtool in order to build shared libraries on a
  53 variety of systems.  While this is very nice for making usable
  54 binaries, it can be a pain when trying to debug a program. For that
  55 reason, compilation of shared libraries can be turned off by
  56 specifying the `--disable-shared' option to `configure'.  However,
  57 without shared libraries, modules that are not preloaded will not be
  58 available for use.
  59
  60 Send bug reports, comments or ideas to `bug-m4@gnu.org'.  A bug report
  61 is an adequate description of the problem: your input, what you
  62 expected, what you got, and why this is wrong.  Diffs are welcome, but
  63 they only describe a solution, from which the problem might be uneasy to
  64 infer.  Don't forget all relevant information about your operating
  65 system, compiler, libraries, ...
  66
  67 The easiest way to remember this information is by using the
  68 testsuite.  Any test failures are automatically logged, along with
  69 lots of useful information about your setup; simply mailing
  70 tests/testsuite.log to `bug-m4@gnu.org' is a good start.  If you want
  71 to dive in and debug a failure, you may find it useful to fine-tune
  72 the execution of the testsuite.  For example, running test 12 in
  73 verbose mode can be done with:
  74
  75 make check TESTSUITEFLAGS='-v -d -x 12'
  76
  77 The testsuite understands --help to tell you more about the current
  78 set of tests.
  79
  80 ========================================================================
  81
  82 Copyright (C) 2000, 2005, 2006, 2007 Free Software Foundation, Inc.
  83
  84 Permission is granted to copy, distribute and/or modify this document
  85 under the terms of the GNU Free Documentation License, Version 1.2 or
  86 any later version published by the Free Software Foundation; with no
  87 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  88 Texts.  A copy of the license is included in the ``GNU Free
  89 Documentation License'' file as part of this distribution.