autotools doc PR: No depends_on('m4') with depends_on('autoconf') (#26101)

* autotoolspackage.rst: No depends_on('m4') with depends_on('autoconf')
  - Remove `m4` from the example depends_on() lines for the autoreconf phase.
  - Change the branch used as example from develop to master as it is
    far more common in the packages of spack's builtin repo.
- Fix the wrong info that libtoolize and aclocal are run explicitly
  in the autoreconf phase by default. autoreconf calls these internally
  as needed, thus autotools.py also does not call them directly.
- Add that autoreconf() also adds -I<aclocal-prefix>/share/aclocal.
- Add an example how to set autoreconf_extra_args.
- Add an example of a custom autoreconf phase for running autogen.sh.

Co-authored-by: Harmen Stoppels <harmenstoppels@gmail.com>

1 files changed, 32 insertions, 8 deletions

diff --git a/lib/spack/docs/build_systems/autotoolspackage.rst b/lib/spack/docs/build_systems/autotoolspackage.rst
index 558c56da0f..0cb87a58eb 100644
--- a/lib/spack/docs/build_systems/autotoolspackage.rst
+++ b/lib/spack/docs/build_systems/autotoolspackage.rst
@@ -112,20 +112,44 @@ phase runs:
 
 .. code-block:: console
 
-   $ libtoolize
-   $ aclocal
-   $ autoreconf --install --verbose --force
+   $ autoreconf --install --verbose --force -I <aclocal-prefix>/share/aclocal
+
+In case you need to add more arguments, override ``autoreconf_extra_args``
+in your ``package.py`` on class scope like this:
+
+.. code-block:: python
+
+   autoreconf_extra_args = ["-Im4"]
 
 All you need to do is add a few Autotools dependencies to the package.
 Most stable releases will come with a ``configure`` script, but if you
-check out a commit from the ``develop`` branch, you would want to add:
+check out a commit from the ``master`` branch, you would want to add:
 
 .. code-block:: python
 
-   depends_on('autoconf', type='build', when='@develop')
-   depends_on('automake', type='build', when='@develop')
-   depends_on('libtool',  type='build', when='@develop')
-   depends_on('m4',       type='build', when='@develop')
+   depends_on('autoconf', type='build', when='@master')
+   depends_on('automake', type='build', when='@master')
+   depends_on('libtool',  type='build', when='@master')
+
+It is typically redundant to list the ``m4`` macro processor package as a
+dependency, since ``autoconf`` already depends on it.
+
+"""""""""""""""""""""""""""""""
+Using a custom autoreconf phase
+"""""""""""""""""""""""""""""""
+
+In some cases, it might be needed to replace the default implementation
+of the autoreconf phase with one running a script interpreter. In this
+example, the ``bash`` shell is used to run the ``autogen.sh`` script.
+
+.. code-block:: python
+
+   def autoreconf(self, spec, prefix):
+       which('bash')('autogen.sh')
+
+"""""""""""""""""""""""""""""""""""""""
+patching configure or Makefile.in files
+"""""""""""""""""""""""""""""""""""""""
 
 In some cases, developers might need to distribute a patch that modifies
 one of the files used to generate ``configure`` or ``Makefile.in``.