Re: Documentation for build system setup

[Emmanuele Bassi <ebassi gmail com>]

Hi;

On 9 February 2017 at 09:56, Sebastian Geiger (Lanoxx) <lanoxx gmx net> wrote:

> 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'm not entirely sure GNOME should have a section on best practices
for the build system you may or may not be using. GNOME doesn't really
mandate *how* you build your application or library code, as long as:

  - if it's an application
    - it installs a desktop file under XDG_DATA_DIRS/applications
    - it installs a DBus service file in the DBus service directory
    - it installs an appdata XML file
  - if it's a library
    - it installs a pkg-config file under PKG_CONFIG_PATH
    - the pkg-config file contains the appropriate compiler and linker
flags to find the headers and shared objects

All of these best practices are really general ones, for any build system

If you want to learn the best practices for autotools, I can strongly
recommend reading the "Autotools Mythbuster" book:

  https://autotools.io/index.html

> 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

These are mostly goals for GNOME projects hosted on git.gnome.org —
and they are "nice to have", not strictly mandatory.

> 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.

Again, the Autotools Mythbuster book is probably what you're looking for.

> 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 should only call `autoreconf`; that will take care of
things like libtoolize and gettextize.

If you are writing a library and using gtk-doc, then you'll need to
call `gtkdocize` prior to `autoreconf`.

There are a couple of additional things for helping non-srcdir builds
and a autobuilders like Continuous:

 * switch to "$srcdir" before calling anything that will need to
modify the srcdir, e.g. autoreconf and gtkdocize
 * if your autogen.sh wants to helpfully call the generated configure
script, then check if the NOCONFIGURE environment variable is set
first

The smallest autogen.sh I can think of is:

```sh
test -n "$srcdir" || srcdir=`dirname "$0"`
test -n "$srcdir" || srcdir=.

olddir=`pwd`
cd "$srcdir"

autoreconf --force --install --verbose || exit $?

cd "$olddir"
test -n "$NOCONFIGURE" || exec "$srcdir/configure" "$@"
```

> 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?

Making sure that autogen.sh switches to srcdir before modifying it is enough.

When writing Makefile.am rules, always remember to include paths under
top_builddir if you're including a path from top_srcdir; also remember
that if you're generating files, their source is in srcdir, but their
results are in builddir.

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

This depends entirely on what you're trying to achieve.

The recommendations are usually for compiler arguments checks and code
coverage for test suites. Appdata and Yelp have their own macros as
well, but they are not shipped by autoconf-archive.

If you want to start assembling an addendum to the Autotools
Mythbuster with the additional practices for GNOME projects, feel free
to just do it and put it on the wiki. Just ask here for reviews, or
ask in #gnome-hackers on IRC.

Ciao,
 Emmanuele.

-- 
https://www.bassi.io
[@] ebassi [@gmail.com]