Re: Documentation for build system setup



On Thu, 2017-02-09 at 10:32 +0000, Emmanuele Bassi wrote:
Hi;

On 9 February 2017 at 09:56, Sebastian Geiger (Lanoxx) <lanoxx gmx ne
t> 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.

It would be good if the first two were consolidated a bit. They
probably also need updating, since they’re now quite old.

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" "$@"
```

Can we please standardise on the autogen.sh given in
https://wiki.gnome.org/Projects/GnomeCommon/Migration#autogen.sh ?

It does everything we need, and meets all the standards (like build-
api). If you’ve got improvements to make, please make them on that
page.

Sebastian: the paragraph immediately above the example does say that
you should remove one or both of the intltoolize/glib-gettextize calls
as appropriate.

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.

If you want JHBuild to build with srcdir ≠ builddir, set checkoutroot,
buildroot and prefix to different paths. For example, I have them set
to:

checkoutroot = '/opt/gnome/source'
buildroot = '/opt/gnome/build'
prefix = '/opt/gnome/install'

https://developer.gnome.org/jhbuild/stable/config-reference.html.en

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.

Yeah, I would go with those recommendations too. Basically, the ones we
commonly use are the ones listed on
https://wiki.gnome.org/Projects/GnomeCommon/Migration.

I also commonly use AX_VALGRIND_CHECK: https://www.gnu.org/software/aut
oconf-archive/ax_valgrind_check.html#ax_valgrind_check.

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.

That would be useful; I’d be happy to help review such an addendum,
though I wouldn’t have time to work on it.

Philip

Attachment: signature.asc
Description: This is a digitally signed message part



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]