ax_subdirs_configure
====================

Synopsis
********

     AX_SUBDIRS_CONFIGURE( [subdirs], [mandatory arguments], [possibly merged arguments], [replacement arguments], [forbidden arguments])

Description
***********

AX_SUBDIRS_CONFIGURE attempts to be the equivalent of AC_CONFIG_SUBDIRS with customizable options for configure scripts.

Run the configure script for each directory from the comma-separated m4 list 'subdirs'. This macro can be used multiple times. All arguments of this macro must be comma-separated lists.

All command line arguments from the parent configure script will be given to the subdirectory configure script after the following modifications (in that order):

1. The arguments from the 'mandatory arguments' list shall always be appended to the argument list.

2. The arguments from the 'possibly merged arguments' list shall be added if not present in the arguments of the parent configure script or merged with the existing argument otherwise.

3. The arguments from the 'replacement arguments' list shall be added if not present in the arguments of the parent configure script or replace the existing argument otherwise.

4. The arguments from the 'forbidden arguments' list shall always be removed from the argument list.

The lists 'mandatory arguments' and 'forbidden arguments' can hold any kind of argument. The 'possibly merged arguments' and 'replacement arguments' expect their arguments to be of the form --option-name=value.

This macro aims to remain as close as possible to the AC_CONFIG_SUBDIRS macro. It corrects the paths for '--srcdir' and adds '--disable-option-checking' and '--silent' if necessary. However, it does not change the '--cache-file' argument: typically, configure scripts run with different arguments will not be able to share the same cache. If you wish to share a single cache, you should give an absolute path to '--cache-file'.

This macro also sets the output variable subdirs_extra to the list of directories recorded with AX_SUBDIRS_CONFIGURE. This variable can be used in Makefile rules or substituted in configured files.

This macro shall do nothing more than managing the arguments of the configure script. Just like when using AC_CONFIG_SUBDIRS, it is up to the user to check any requirements or define and substitute any required variable for the remainder of the project.

Configure scripts recorded with AX_SUBDIRS_CONFIGURE may be executed before configure scripts recorded with AC_CONFIG_SUBDIRS.

Without additional arguments, the behaviour of AX_SUBDIRS_CONFIGURE should be identical to the behaviour of AC_CONFIG_SUBDIRS, apart from the contents of the variables subdirs and subdirs_extra (except that AX_SUBDIRS_CONFIGURE expects a comma-separated m4 list):

       AC_CONFIG_SUBDIRS([something])
       AX_SUBDIRS_CONFIGURE([something])

This macro may be called multiple times.

Usage example:

Let us assume our project has 4 dependencies, namely A, B, C and D. Here are some characteristics of our project and its dependencies:

- A does not require any special option.

- we want to build B with an optional feature which can be enabled with its configure script's option '--enable-special-feature'.

- B's configure script is strange and has an option '--with-B=build'. After close inspection of its documentation, we don't want B to receive this option.

- C and D both need B.

- Just like our project, C and D can build B themselves with the option '--with-B=build'.

- We want C and D to use the B we build instead of building it themselves.

Our top-level configure script will be called as follows:

       $ <path/to/configure> --with-A=build --with-B=build --with-C=build \
         --with-D=build --some-option

Thus we have to make sure that:

- neither B, C or D receive the option '--with-B=build'

- C and D know where to find the headers and libraries of B.

Under those conditions, we can use the AC_CONFIG_SUBDIRS macro for A, but need to use AX_SUBDIRS_CONFIGURE for B, C and D:

- B must receive '--enable-special-feature' but cannot receive '--with-B=build'

- C and D cannot receive '--with-B=build' (or else it would be built thrice) and need to be told where to find B (since we are building it, it would probably not be available in standard paths).

Here is a configure.ac snippet that solves our problem:

       AC_CONFIG_SUBDIRS([dependencies/A])
       AX_SUBDIRS_CONFIGURE(
           [dependencies/B], [--enable-special-feature], [], [],
           [--with-B=build])
       AX_SUBDIRS_CONFIGURE(
           [[dependencies/C],[dependencies/D]],
           [],
           [[CPPFLAGS=-I${ac_top_srcdir}/dependencies/B -I${ac_top_builddir}/dependencies/B],
            [LDFLAGS=-L${ac_abs_top_builddir}/dependencies/B/.libs]],
           [--with-B=system],
           [])

If using automake, the following can be added to the Makefile.am (we use both $(subdirs) and $(subdirs_extra) since our example above used both AC_CONFIG_SUBDIRS and AX_SUBDIRS_CONFIGURE):

       SUBDIRS = $(subdirs) $(subdirs_extra)

Source Code
***********

Download the latest version of ax_subdirs_configure.m4 (http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_subdirs_configure.m4) or browse the macro's revision history (http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=history;f=m4/ax_subdirs_configure.m4).

License
*******

Copyright © 2017 Harenome Ranaivoarivony-Razanajato ranaivoarivony-razanajato@hareno.me

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Under Section 7 of GPL version 3, you are granted additional permissions described in the Autoconf Configure Script Exception, version 3.0, as published by the Free Software Foundation.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.