Documentation for build system setup

["Sebastian Geiger (Lanoxx)" <lanoxx gmx net>]

Hi Gnome Devs,

I was looking at the following overview page today:

https://developer.gnome.org/platform-overview/unstable/
e.g. "platform-overview/3.22/index.page"

I would like to submit the following feedback about this page. An aspect
that I am missing here is
some information about the build system setup. For example most Gnome
Modules are currently
autotools based, they ship an autogen.sh and follow a certain set of
best practices in their
configure.ac and Makefile.am files. It would be great to have an
additional entry on this
page that is maybe named "build automation" or "building the
application" and that contains
some information about how to setup the build system. I would suggest to
limit that
to autotools for the moment but it could be extended to mention meson or
cmake in the
future.

I know we already have a bunch of good documentation on the wiki,
for example:

 https://wiki.gnome.org/Initiatives/GnomeGoals/ModernAutotools
 https://wiki.gnome.org/Initiatives/GnomeGoals/NicerBuilds
 https://wiki.gnome.org/Projects/GnomeCommon/Migration

However it seems to me that none of these pages offers
a really up to date information and consistent summary
of how a typical gnome application should be setup
today.

I guess that there probably exist other wiki pages that I have not found
yet.
I am also pretty certain that I have seen various blog posts on Planet
Gnome about
build system aspects but cant remember the links to them.

A few example questions for which I would hope to find answers in
the documentation are:

1. What are best practices when setting up autogen.sh, is there are
recommended template
    to start with. I know the GnomeCommon migration guide lists one, but
I did not find it useful.
    In particular because it contains calls to both glib-gettextize and
intltoolize and the page later
    mentions that exactly this should not be done.
> Your autogen.sh file might include a call to either glib-gettextize or
> intltoolize. (If it calls both, then you have done something wrong,
> since they don't work properly together.) glib-gettextize is now
> obsoleted by new functionality in upstream gettext, and autoreconf
> will call autopoint automatically.

2. What are best practices regarding builddir!=srcdir builds? Are there
any special steps required when using jhbuild, when I want it to do
out-of-tree builds?

3. What are some recommended macros from autoconf-archive that should be
used?

If there is already a good documentation about this, and I just missed
it, then I apologise for the noise.

Best Regards
Sebastian

P.S. I am cross-posting this on the desktop-devel-list, maybe other
people have some suggestions about this.