Re: Calling other external Makefiles and outside Make systems

[Alexandre Duret-Lutz]

>>> "Ralf" == Ralf Wildenhues <address@hidden> writes:

[...]

 Ralf> A few issues that come to my mind possibly worth
 Ralf> improving (not the documentation, but Auto{make,conf}
 Ralf> with this respect) are

 Ralf> - provide a way to communicate the value of AC_CONFIG_AUX_DIR
 Ralf> to sub-package configure scripts (do we need to think about
 Ralf> AC_CONFIG_MACRO_DIR, too?), so they don't need adaptation.

I don't understand this.  If a third-party package uses an
auxiliary script, say install-sh, then that third-party package
already contains install-sh and does not care about the parent's
auxdir.  Am I missing something?  What kind of adaptation do you
want to avoid passing AC_CONFIG_AUX_DIR?

 Ralf> - With this respect, what is the value of top_builddir,
 Ralf> top_srcdir and are these properly documented?  I only
 Ralf> found out about distdir and top_distdir in the manual.

It's because they really are predefined Autoconf substitutions.

Anyway, thank you for mentioning that.  I really forgot to
though about VPATH builds while writing this.

Someday I would like to write two introductory sections to the
manual.  One section would be `Automake projects from the user's
perspective', explaining the various targets available and
different uses of the GNU build system (cross-compilation, VPATH
builds, DESTDIR installs).  I don't really expect end-users to
read the Automake manual, but it is a nice way to introduce
these concept before showing how they work.  The other section
would be the `developer's perspective'.  It would explain how a
project is usually organized, the purpose of each autotool, and
how everything fits to achieve the feature listed in the
previous section.  Perhaps this second section will need to be
split in many sub-sections, explaining how DESTDIR installs,
cross-compilation, VPATH builds, etc. work.  The discussion
about srcdir/top_srcdir/top_buildir belongs there, IMHO.

 Ralf> Other than that, a few language hints (disclaimer: from a
 Ralf> non-native):

Thanks again.  The only changes I didn't include are the colons,
but that's a matter of taste and if someone insists I can put
them in.

Here is a new version of that section, with additions
highlighted on the left.

  Third-Party `Makefile's
  =======================
  
  In most projects all `Makefile's are generated by Automake.  In some
  cases, however, projects need to embed subdirectories with handwritten
  `Makefile's.  For instance one subdirectory could be a third-party
  project with its own build system, not using Automake.
  
     It is possible to list arbitrary directories in `SUBDIRS' or
  `DIST_SUBDIRS' provided each of these directories has a `Makefile' that
  recognizes all the following recursive targets.
  
     When a user runs one of these targets, that target is run recursively
  in all subdirectories.  This is why it is important that even
  third-party `Makefile's support them.
  
  `all'
       Compile the entire package.  This is the default target in
       Automake-generated `Makefile's, but it does not need to be the
       default in third-party `Makefile's.
  
  `distdir'
       Copy files to distribute into `$(distdir)', before a tarball is
       constructed.  Of course this target is not required if the
       `no-dist' option (*note Options::) is used.
  
|      The variables `$(top_distdir)' and `$(distdir)' (*note Dist::)
|      will be passed from the outer package to the subpackage when the
|      `distdir' target is invoked.  These two variables have been
|      adjusted for the directory which is being recursed into, so they
|      are ready to use.
  
  `install'
  `install-data'
  `install-exec'
  `uninstall'
       Install or uninstall files (*note Install::).
  
  `install-info'
       Install only the Texinfo documentation (*note Texinfo::).
  
  `installdirs'
       Create install directories, but do not install any files.
  
  `check'
  `installcheck'
       Check the package (*note Tests::).
  
  `mostlyclean'
  `clean'
  `distclean'
  `maintainer-clean'
       Cleaning rules (*note Clean::).
   
  `dvi'
  `pdf'
  `ps'
  `info'
  `html'
       Build the documentation in various formats (*note Texinfo::).
   
  `tags'
  `ctags'
       Build `TAGS' and `CTAGS' (*note Tags::).
  
     If you have ever used Gettext in a project, this is how it works.
  The `Makefile's in the `po/' and `intl/' directories are handwritten
  `Makefile's that implement all these targets.  That way they can be
  added to `SUBDIRS' in Automake packages.
  
     Directories which are only listed in `DIST_SUBDIRS' but not in
  `SUBDIRS' need only the `distclean', `maintainer-clean', and `distdir'
  rules (*note Top level::).
     
     Usually, many of these rules are irrelevant to the third-party
  subproject, but they are required for the whole package to work.  It's
  OK to have a rule that does nothing, so if you are integrating a
  third-party project with no documentation or tag support, you could
  simply augment its `Makefile' as follows:
  
       EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
       .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
       $(EMPTY_AUTOMAKE_TARGETS):
     
|    Another aspect of integrating third-party build systems is whether
| they support VPATH builds.  Obviously if the subpackage does not
| support VPATH builds the whole package will not support VPATH builds.
| This in turns means that `make distcheck' will not work, because it
| relies on VPATH builds.  Some people can live without this (actually,
| many Automake users have never heard of `make distcheck').  Other
| people may prefer to revamp the existing `Makefile's to support VPATH.
| Doing so does not necessarily require Automake, only Autoconf is needed
| (*note Build Directories: (autoconf)Build Directories.).  The necessary
| substitutions: address@hidden@', address@hidden@', and address@hidden@' are
| defined by `configure' when it processes a `Makefile' (*note Preset
| Output Variables: (autoconf)Preset Output Variables.), they are not
| computed by the Makefile like the aforementioned `$(distdir)' and
| `$(top_distdir)' variables..
   
     It is sometimes inconvenient to modify a third-party `Makefile' to
  introduce the above required targets.  For instance one may want to
  keep the third-party sources untouched to ease upgrades to new versions.
  
     Here are two other ideas.  If GNU make is assumed, one possibility is
  to add to that subdirectory a `GNUmakefile' that defines the required
| targets and include the third-party `Makefile'.  For this to work in
| VPATH builds, `GNUmakefile' must lie in the build directory; the
| easiest way to do this is to write a `GNUmakefile.in' instead, and have
| it processed with `AC_CONFIG_FILES' from the outer package.  For
| example if we assume `Makefile' defines all targets except the
| documentation targets, and that the `check' target is actually called
| `test', we could write `GNUmakefile' (or `GNUmakefile.in') like this:
  
       # First, include the real Makefile
       include Makefile
       # Then, define the other targets needed by Automake Makefiles.
       .PHONY: dvi pdf ps info html check
       dvi pdf ps info html:
       check: test
  
     A similar idea that does not use `include' is to write a proxy
  `Makefile' that dispatches rules to the real `Makefile', either with
  `$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target' (if it's OK to rename
  the original `Makefile') or with `cd subdir && $(MAKE) $(AM_MAKEFLAGS)
  target' (if it's OK to store the subdirectory project one directory
  deeper).  The good news is that this proxy `Makefile' can be generated
  with Automake.  All we need are -local targets (*note Extending::) that
  perform the dispatch.  Of course the other Automake features are
  available, so you could decide to let Automake perform distribution or
  installation.  Here is a possible `Makefile.am':
  
       all-local:
               cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
       check-local:
               cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
       clean-local:
               cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
       
       # Assuming the package knows how to install itself
       install-data-local:
               cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
       install-exec-local:
               cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
       uninstall-local:
               cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
       
       # Distribute files from here.
       EXTRA_DIST = subdir/Makefile subdir/program.c ...
  
     Pushing this idea to the extreme, it is also possible to ignore the
  subproject build system and build everything from this proxy
| `Makefile.am'.  This might sounds very sensible if you need VPATH
| builds but the subproject does not support them.

-- 
Alexandre Duret-Lutz