gnome-common is completely deprecated, in favour of using macros from upstream autoconf-archive, and open-coding things in autogen.sh.
Reasons for deprecation
gnome-common is deprecated because:
- The macros it contained are useful to more projects than just GNOME, and should be upstream.
- The code in gnome-autogen.sh was mostly boilerplate, and largely deprecated by jhbuild.
- It’s a dependency which needs to be pulled in before a module can start to be built, and the fact that it’s needed might not always be obvious.
- Its use immediately marks modules as ‘for use within GNOME only’, even though they might well be useful everywhere (e.g. libraries).
Want to continue using gnome-common?
Copy the macros and gnome-autogen.sh from the final gnome-common release into your project, or ensure that your project is packaged with a hard dependency on that version of gnome-common.
I have a useful macro which could be shared with other modules!
Is it generally useful to all modules? Stop hoarding it in your build system! Submit it to autoconf-archive (though note that it must be polished and API-stable to be accepted).
Porting guide
autogen.sh
Instead of using gnome-autogen.sh, the following template should be used for your autogen.sh. In general, you can directly copy the template into your project and start using it, however if your project uses gtkdocize or one of the almost obsolete tools glib-gettextize or intltoolize then you need to add some additional lines that are documented further below. Note that you should not use both glib-gettextize and intltoolize in the same module, and it is better to use neither; see the FAQ entry below for details.
Note that this version does not support NO-AUTO-GEN files or multiple configure.ac files in subdirectories.
The below autogen.sh can be used in two ways. Either directly from the source directory by running ./autogen.sh, or from some other directory which will then be used as build directory. To use some other directory as build directory you can change to that directory first and then run autogen.sh relative from there. The following example creates a directory named build/ inside your source directory and runs autogen.sh from there:
mkdir build/ cd build/ ../autogen.sh
autogen.sh template:
#!/bin/sh
# Run this to generate all the initial makefiles, etc.
test -n "$srcdir" || srcdir=$(dirname "$0")
test -n "$srcdir" || srcdir=.
olddir=$(pwd)
cd $srcdir
(test -f configure.ac) || {
echo "*** ERROR: Directory '$srcdir' does not look like the top-level project directory ***"
exit 1
}
# shellcheck disable=SC2016
PKG_NAME=$(autoconf --trace 'AC_INIT:$1' configure.ac)
if [ "$#" = 0 -a "x$NOCONFIGURE" = "x" ]; then
echo "*** WARNING: I am going to run 'configure' with no arguments." >&2
echo "*** If you wish to pass any to it, please specify them on the" >&2
echo "*** '$0' command line." >&2
echo "" >&2
fi
autoreconf --verbose --force --install || exit 1
cd "$olddir"
if [ "$NOCONFIGURE" = "" ]; then
$srcdir/configure "$@" || exit 1
if [ "$1" = "--help" ]; then
exit 0
else
echo "Now type 'make' to compile $PKG_NAME" || exit 1
fi
else
echo "Skipping configure process."
fiIf you are still using the deprecated glib-gettextize, then add the following line immediately before autoreconf:
glib-gettextize --force --copy || exit 1
If you are still using the almost obsolete intltoolize, then add the following line immediately before autoreconf:
intltoolize --force --copy --automake || exit 1
If you are using gtk-doc you need to call gtkdocize before autoreconf:
gtkdocize --copy || exit 1
In all of the above three cases you will need to add an additional call to aclocal, so assuming you are using glib-gettextize and gtkdocize the resulting part of your autogen.sh could look like this:
aclocal --install || exit 1 glib-gettextize --force --copy || exit 1 gtkdocize --copy || exit 1 autoreconf --verbose --force --install || exit 1
If you want warnings if necessary autoconf macros are not installed, e.g. for Yelp, AppData or AppStream, add the following to configure.ac, using the AX_REQUIRE_DEFINED macro from autoconf-archive (see: http://www.gnu.org/software/autoconf-archive/ax_require_defined.html):
AX_REQUIRE_DEFINED([YELP_HELP_INIT]) AX_REQUIRE_DEFINED([APPSTREAM_XML]) AX_REQUIRE_DEFINED([GTK_DOC_CHECK])
Note that you should only require the macros you use, otherwise you are including unnecessary dependencies at build time.
See an example of porting away from gnome-autogen.sh in Hitori, in libgdata and in Yelp.
autoconf macros
Firstly, add
AC_CONFIG_MACRO_DIR([m4])
to your configure.ac.
Secondly, add a dependency on m4-common to your module in its JHBuild moduleset, as you will be depending on macros from autoconf-archive, which m4-common pulls in. (See https://bugzilla.gnome.org/show_bug.cgi?id=752009 for discussion.)
If you get errors like the following, you’re trying to build a module which is missing an explicit m4-common dependency, which should be added to JHBuild now:
./configure: line 12053: syntax error near unexpected token `GOBJECT_INTROSPECTION_CHECK' ./configure: line 12053: `AX_REQUIRE_DEFINED(GOBJECT_INTROSPECTION_CHECK)'
The autoconf macros used in configure.ac should be ported as follows. Any macros used from autoconf-archive can either be
- used without copying, and a build time dependency on autoconf-archive added to your project; or
copied into your project’s source tree in the m4 directory.
You must do one or the other, or will receive bash errors from configure about unrecognised variables or similar.
The first option, adding a dependency on autoconf-archive, is preferred. While the latest version of autoconf-archive is not widely packaged in distributions, JHBuild has a dependency on it — so any module using JHBuild will automatically have the correct macros available. aclocal --install will automatically copy the macros into the m4/ directory of module, and they will be disted with the tarball, so autoconf-archive is not needed for non-git builds.
Having a dependency on autoconf-archive means that the latest version of each macro will always be used, rather than a potentially stale copy in each module’s source tree. It also reduces duplication of the macros. Note also that there may be licence compatibility issues with shipping non-public-domain macros in your project’s git repository.
If you do decide to copy macros into your project's version control (the second, discouraged, option), there is no need to add them to EXTRA_DIST or similar automake variables — AC_CONFIG_MACRO_DIR does this automatically.
AX_IS_RELEASE
See: http://www.gnu.org/software/autoconf-archive/ax_is_release.html.
This should be added to the top of your configure.ac, after AC_INIT. You will need to choose a release policy; see the documentation. The recommended policy is git-directory, but minor-version works equally well for modules following the GNOME release schedule.
AX_IS_RELEASE([git-directory])
See an example of using AX_IS_RELEASE in Hitori, in libgdata and in Yelp.
GNOME_CODE_COVERAGE
See: http://www.gnu.org/software/autoconf-archive/ax_code_coverage.html.
Change GNOME_CODE_COVERAGE in configure.ac to:
AX_CODE_COVERAGE()
Change GNOME_CODE_COVERAGE_RULES in Makefile.am to CODE_COVERAGE_RULES.
See an example of using AX_CODE_COVERAGE in Hitori.
GNOME_DEBUG_CHECK
See: http://www.gnu.org/software/autoconf-archive/ax_check_enable_debug.html.
Change GNOME_DEBUG_CHECK in configure.ac to the following, which will enable debug by default for non-release builds:
AX_CHECK_ENABLE_DEBUG([yes],[GNOME_ENABLE_DEBUG])
If you wish to completely preserve compatibility with GNOME_DEBUG_CHECK, leaving debug disabled by default, use the following. This is not recommended, because debug output is useful:
AX_CHECK_ENABLE_DEBUG([no],[GNOME_ENABLE_DEBUG])
In both cases, the user can override this with the --enable-debug=[yes|info|profile|no] configure option.
If you wish to eliminate the second argument (GNOME_ENABLE_DEBUG), use the following in configure.ac, and then change all #ifdef GNOME_ENABLE_DEBUG in your code to #ifndef NDEBUG to use the more-standard NDEBUG macro:
AX_CHECK_ENABLE_DEBUG([yes])
The fourth argument specifies whether a release is being built: this should come from the AX_IS_RELEASE macro (described above). It defaults to $ax_is_release, so works automagically.
See an example of using AX_CHECK_ENABLE_DEBUG in Hitori and in Yelp.
GNOME_MAINTAINER_MODE_DEFINES
This has no replacement: all the modules it refers to are outdated and unused. Remove use of it completely.
See an example of removing GNOME_MAINTAINER_MODE_DEFINES in Hitori.
GNOME_COMPILE_WARNINGS and GNOME_CXX_WARNINGS
See: http://www.gnu.org/software/autoconf-archive/ax_compiler_flags.html.
Change GNOME_COMPILE_WARNINGS and GNOME_CXX_WARNINGS to AX_COMPILER_FLAGS in configure.ac:
AX_COMPILER_FLAGS([WARN_CFLAGS],[WARN_LDFLAGS])
You must set the following in your ~/.config/jhbuildrc:
disable_Werror = False
and ensure that your module builds without any warnings before pushing your changes. If you do not, you are dumping the work of fixing your compiler warnings onto others (specifically, those who maintain CI in GNOME), which is not friendly or fair.
There is no equivalent for GNOME_COMPILE_WARNINGS([maximum]) — AX_COMPILER_FLAGS defaults to ‘error’.
The first two arguments specify the names of variables to populate with warning flags. You should add these variables to target_CFLAGS and target_LDFLAGS for each target in your project, as described in the AX_COMPILER_FLAGS documentation. Also add WARN_SCANNERFLAGS to target_gir_SCANNERFLAGS for each GObject Introspection GIR file generated by your project.
The third argument specifies whether a release is being built: this should come from the AX_IS_RELEASE macro (described above). It defaults to $ax_is_release, so works automagically.
Subsequent arguments specify additional flags to set in WARN_CFLAGS and WARN_LDFLAGS for when warnings are disabled and enabled. If your project has additional warning flags it wants to enable, they should be passed in here, and will be automatically checked for compiler support. Note that non-warning compiler flags should not be passed here, as they may end up being disabled.
If your project wants to disable a specific error, you should use pragmas in the first instance, to disable those errors on a case-by-case basis in the code. If a more widespread solution is needed, pass -Wno-[flag-name] to one of the subsequent AX_COMPILER_FLAGS arguments. However, please consider fixing the warnings rather than disabling them. If you strongly believe a given warning flag should not be in the default set, get in touch with PhilipWithnall.
One of the flags enabled by AX_COMPILER_FLAGS by default is `-Wswitch-enum`. This is intended to enable a more explicit coding style, where all enum cases are explicitly handled (or explicitly aliased to ‘default’). This is beneficial for project maintenance, as it means that when new enum values are added, the compiler points out all places where those cases need handling.
AX_COMPILER_FLAGS has a bail-out option: --disable-Werror, which unconditionally disables use of the -Werror compiler option to make warnings fatal. This should be used by non-developers of a module who just want to build the module without contributing to it. It is the default in JHBuild. Developers, however, must keep their modules building clean of warnings.
See an example of using AX_COMPILER_FLAGS in Hitori, in libgdata and in Yelp.
GNOME_COMMON_INIT
This macro can simply be removed.
GNOME_DOC_INIT
Replace this with usage of yelp.m4: YELP_HELP_INIT.
FAQ
Please add any questions here, or contact PhilipWithnall or DavidKing.
- What's up with ACLOCAL_AMFLAGS?
It used to be common to modify ACLOCAL_AMFLAGS in the top-level Makefile.am in order to cause m4 macros to be installed, but this variable is deprecated and should not be used anymore. If you call aclocal --install in your autogen.sh then you do not need it. In the future, autoreconf --install will handle this automatically.
- What's up with gettext, glib-gettext, and intltool?
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. To port, use AM_GNU_GETTEXT instead of AM_GLIB_GNU_GETTEXT in your configure.ac, and see this example of how to make gettext play nicely with git. intltoolize is obsolete: gettext 0.19.7 includes all the functionality GNOME projects used from intltool, so you should port from intltool to gettext.
- Is it normal that I now see the following message when running autogen.sh?
+ glib-gettextize --force --copy Copying file po/Makefile.in.in Please add the files codeset.m4 gettext.m4 glibc21.m4 iconv.m4 isc-posix.m4 lcmessage.m4 progtest.m4 from the $prefix/share/aclocal directory to your autoconf macro directory or directly to your aclocal.m4 file. You will also need config.guess and config.sub, which you can get from ftp://ftp.gnu.org/pub/gnu/config/.
If you want to keep using glib-gettextize, just ignore the message. The macros should be automatically concatenated to the aclocal.m4 script in the tarball, if they are actually used by any of the build system. Note that it is recommended to stop using glib-gettextize altogether.