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' has been 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 CVS, the bootstrap
  15 process requires that you first install a released copy of GNU `m4'.
  16
  17 In the subdirectories `tests' and `examples' you will find various m4
  18 files, ranging from trivial test files to rather advanced macros.  If
  19 you intend to use m4 seriously, you might find useful material down
  20 there.
  21
  22 See file `COPYING' for copying conditions.
  23 See file `INSTALL' for compilation and installation instructions.
  24 See file `ABOUT-NLS' for how to customize this program to your language.
  25 See file `NEWS' for a list of major changes in the current release.
  26 See file `AUTHORS' for the names of maintainers.
  27 See file `THANKS' for a list of contributors.
  28
  29 By using `./configure --with-gmp, you get multiple precision integral
  30 and rational arithmetic using mpeval.  The implementation depends on the
  31 GNU gmp v2 library.
  32
  33 By using `./configure --with-modules=`foo bar baz', you get an m4 with only
  34 the named modules preloaded.  The default modules (preloaded if you do not
  35 use this option) are sufficient to do the job of GNU m4-1.4.  Additional
  36 modules may be desirable, or necessary if libltdl does not support your
  37 host architecture.  The implementation uses libltdl interface, details of
  38 which are in the libtool manual.  See file `modules/README' for a more
  39 detailed description.
  40
  41 By using `./configure --with-dmalloc', GNU m4 is linked with Gray
  42 Watson's dmalloc package.  It is a debugging option for finding memory
  43 management problems.  Gray Watson's dmalloc package is available at
  44 ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz.
  45
  46 GNU M4 uses GNU Libtool in order to build shared libraries on a
  47 variety of systems.  While this is very nice for making usable
  48 binaries, it can be a pain when trying to debug a program. For that
  49 reason, compilation of shared libraries can be turned off by
  50 specifying the `--disable-shared' option to `configure'.
  51
  52 Send bug reports, comments or ideas to `bug-m4@gnu.org'.  A bug report
  53 is an adequate description of the problem: your input, what you
  54 expected, what you got, and why this is wrong.  Diffs are welcome, but
  55 they only describe a solution, from which the problem might be uneasy to
  56 infer.  Don't forget all relevant information about your operating
  57 system, compiler, libraries, ...
  58
  59 The easiest way to remember this information is by using the
  60 testsuite.  Any test failures are automatically logged, along with
  61 lots of useful information about your setup; simply mailing
  62 tests/testsuite.log to `bug-m4@gnu.org' is a good start.  If you want
  63 to dive in and debug a failure, you may find it useful to fine-tune
  64 the execution of the testsuite.  For example, running test 12 in
  65 verbose mode can be done with:
  66
  67 make check TESTSUITEFLAGS='-v -d -x 12'
  68
  69 The testsuite understands --help to tell you more about the current
  70 set of tests.
  71
  72
  73 ## ------- ##
  74 ## Patches ##
  75 ## ------- ##
  76
  77 If you wish to run bootstrap, the released versions of autoconf,
  78 automake, and libtool are missing some functionality we need.  You
  79 will need a CVS build of libtool head (1.5.x does not have enough
  80 functionality), and use the 2.59d snapshot of autoconf or a CVS
  81 build.  If you do not use a CVS build of automake, you can instead
  82 patch automake-1.9.5 or 1.9.6 according to the patch below:
  83
  84 --- automake-1.9.5/automake.in.orig     2005-02-12 10:06:56.000000000 +0000
  85 +++ automake-1.9.5/automake.in  2005-04-20 14:08:05.000000000 +0100
  86 @@ -142,6 +142,7 @@
  87  use Automake::RuleDef;
  88  use Automake::Wrap 'makefile_wrap';
  89  use File::Basename;
  90 +use File::Spec;
  91  use Carp;
  92
  93  ## ----------- ##
  94 @@ -333,6 +334,10 @@
  95  # in Makefiles.
  96  my $am_config_aux_dir = '';
  97
  98 +# Directory to search for AC_LIBSOURCE file, as set by AC_CONFIG_LIBOBJ_DIR
  99 +# in configure.ac.
 100 +my $config_libobj_dir = '';
 101 +
 102  # Whether AM_GNU_GETTEXT has been seen in configure.ac.
 103  my $seen_gettext = 0;
 104  # Whether AM_GNU_GETTEXT([external]) is used.
 105 @@ -2067,7 +2072,7 @@
 106
 107        if ($iter =~ /\.h$/)
 108         {
 109 -         require_file_with_macro ($cond, $var, FOREIGN, $iter);
 110 +         require_libobj_with_macro ($cond, $var, FOREIGN, $iter);
 111         }
 112        elsif ($iter ne 'alloca.c')
 113         {
 114 @@ -2079,7 +2084,7 @@
 115           my $bs = var ('BUILT_SOURCES');
 116           if (! $bs || ! grep (/$rewrite/, $bs->value_as_list_recursive))
 117             {
 118 -             require_file_with_macro ($cond, $var, FOREIGN, $iter);
 119 +             require_libobj_with_macro ($cond, $var, FOREIGN, $iter);
 120             }
 121         }
 122      }
 123 @@ -2092,7 +2097,7 @@
 124    $lt ||= '';
 125    $var->requires_variables ("\@${lt}ALLOCA\@ used", $lt . 'ALLOCA');
 126    $dep_files{'$(DEPDIR)/alloca.P' . $myobjext} = 1;
 127 -  require_file_with_macro ($cond, $var, FOREIGN, 'alloca.c');
 128 +  require_libobj_with_macro ($cond, $var, FOREIGN, 'alloca.c');
 129    &saw_extension ('c');
 130  }
 131
 132 @@ -4636,6 +4641,7 @@
 133                 AC_CONFIG_AUX_DIR => 1,
 134                 AC_CONFIG_FILES => 1,
 135                 AC_CONFIG_HEADERS => 1,
 136 +               AC_CONFIG_LIBOBJ_DIR => 1,
 137                 AC_CONFIG_LINKS => 1,
 138                 AC_INIT => 0,
 139                 AC_LIBSOURCE => 1,
 140 @@ -4731,6 +4737,12 @@
 141               push @config_headers, $spec;
 142             }
 143         }
 144 +      elsif ($macro eq 'AC_CONFIG_LIBOBJ_DIR')
 145 +       {
 146 +         $config_libobj_dir = $args[1];
 147 +         $relative_dir = '.';
 148 +         check_directory ($config_libobj_dir, $where);
 149 +       }
 150        elsif ($macro eq 'AC_CONFIG_LINKS')
 151         {
 152           foreach my $spec (split (' ', $args[1]))
 153 @@ -5761,6 +5773,15 @@
 154      use constant IN_COMMENT => 2;
 155      my $prev_state = IN_RULE_DEF;
 156
 157 +    # Calculate the relative path from this Makefile to LIBOBJDIR.
 158 +    my $am_libobj_dir = '';
 159 +    unless ($config_libobj_dir eq '')
 160 +      {
 161 +       my $dir = File::Spec->abs2rel ($config_libobj_dir, $relative_dir);
 162 +       $am_libobj_dir = "$dir/" unless $dir eq '';
 163 +      }
 164 +    &define_variable ('LIBOBJDIR', "$am_libobj_dir", INTERNAL);
 165 +
 166      while ($_ = $am_file->getline)
 167      {
 168          $where->set ("$amfile:$.");
 169 @@ -6975,6 +6996,22 @@
 170      require_file ($macro->rdef ($cond)->location, $mystrict, @files);
 171  }
 172
 173 +# &require_libobj_with_macro ($COND, $MACRO, $MYSTRICT, @FILES)
 174 +# -------------------------------------------------------------
 175 +sub require_libobj_with_macro ($$$@)
 176 +{
 177 +    my ($cond, $macro, $mystrict, @files) = @_;
 178 +    $macro = rvar ($macro) unless ref $macro;
 179 +    if ($config_libobj_dir eq '')
 180 +      {
 181 +       require_file ($macro->rdef ($cond)->location, $mystrict, @files);
 182 +      }
 183 +    else
 184 +      {
 185 +       require_file_internal ($macro->rdef ($cond)->location, $mystrict,
 186 +                              $config_libobj_dir, @files);
 187 +      }
 188 +}
 189
 190  # &require_conf_file ($WHERE, $MYSTRICT, @FILES)
 191  # ----------------------------------------------