Re: Documentation for build system setup

[Philip Withnall]

On Thu, 2017-02-09 at 10:32 +, Emmanuele Bassi wrote:
> Hi;
> 
> On 9 February 2017 at 09:56, Sebastian Geiger (Lanoxx)  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 

Documentation for build system setup

[Sebastian Geiger (Lanoxx)]

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.

___
desktop-devel-list mailing list
desktop-devel-list@gnome.org
https://mail.gnome.org/mailman/listinfo/desktop-devel-list

Re: Documentation for build system setup

[Emmanuele Bassi]

On 9 February 2017 at 13:57, Sebastian Geiger (Lanoxx)  wrote:
> What confuses me is that this paragraph starts with the phrase "it does
> not need any modifications made".
>
>> It does not need any modifications made, unless you need to run
>> another tool before configure, or do not use one of glib-gettextize,
>> gtkdocize or intltoolize. (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.)
>
> It might be more helpful to provide a autogen.sh listing that omits both
> glib-gettextize and intltoolize and then add a paragraph explaining to
> add these for project that use either of these tools. If I understand
> right both a deprecated anyway and should not be needed for
> state-of-the-art projects.
>
> Maybe write something like this:
>
> If 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

Those look like good changes, indeed. Feel free to update the wiki.

Ciao,
 Emmanuele.

> On 09/02/17 11:45, Philip Withnall wrote:
>> 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.
>
>
> ___
> desktop-devel-list mailing list
> desktop-devel-list@gnome.org
> https://mail.gnome.org/mailman/listinfo/desktop-devel-list



-- 
https://www.bassi.io
[@] ebassi [@gmail.com]
___
desktop-devel-list mailing list
desktop-devel-list@gnome.org
https://mail.gnome.org/mailman/listinfo/desktop-devel-list

Re: Documentation for build system setup

[Sebastian Geiger (Lanoxx)]

What confuses me is that this paragraph starts with the phrase "it does
not need any modifications made".

> It does not need any modifications made, unless you need to run
> another tool before configure, or do not use one of glib-gettextize,
> gtkdocize or intltoolize. (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.) 

It might be more helpful to provide a autogen.sh listing that omits both
glib-gettextize and intltoolize and then add a paragraph explaining to
add these for project that use either of these tools. If I understand
right both a deprecated anyway and should not be needed for
state-of-the-art projects.

Maybe write something like this:

If 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



On 09/02/17 11:45, Philip Withnall wrote:
> 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.


___
desktop-devel-list mailing list
desktop-devel-list@gnome.org
https://mail.gnome.org/mailman/listinfo/desktop-devel-list

Re: Documentation for build system setup

[Michael Catanzaro]

On Thu, 2017-02-09 at 15:12 +0100, Sebastian Geiger (Lanoxx) wrote:
> One more question:
> 
> The sample autogen.sh on https://wiki.gnome.org/Projects/GnomeCommon/
> Migration also explicitly calls aclocal like this:
> 
> aclocal --install || exit 1
> 
> But the man page for autoreconf says that autoreconf also calls
> aclocal, is this redundant? If so, can it be removed?

I think it can indeed be removed if you're not using any of the other
-ize programs (glib-gettextize, intltoolize, gtkdocize).

Michael
___
desktop-devel-list mailing list
desktop-devel-list@gnome.org
https://mail.gnome.org/mailman/listinfo/desktop-devel-list

Re: Documentation for build system setup

[Sebastian Geiger (Lanoxx)]

I have just updated the wiki, please let me know if something I changed
is not right:

https://wiki.gnome.org/Projects/GnomeCommon/Migration


On 09/02/17 15:03, Emmanuele Bassi wrote:
> On 9 February 2017 at 13:57, Sebastian Geiger (Lanoxx)  wrote:
>> What confuses me is that this paragraph starts with the phrase "it does
>> not need any modifications made".
>>
>>> It does not need any modifications made, unless you need to run
>>> another tool before configure, or do not use one of glib-gettextize,
>>> gtkdocize or intltoolize. (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.)
>> It might be more helpful to provide a autogen.sh listing that omits both
>> glib-gettextize and intltoolize and then add a paragraph explaining to
>> add these for project that use either of these tools. If I understand
>> right both a deprecated anyway and should not be needed for
>> state-of-the-art projects.
>>
>> Maybe write something like this:
>>
>> If 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
> Those look like good changes, indeed. Feel free to update the wiki.
>
> Ciao,
>  Emmanuele.
>
>> On 09/02/17 11:45, Philip Withnall wrote:
>>> 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.
>>
>> ___
>> desktop-devel-list mailing list
>> desktop-devel-list@gnome.org
>> https://mail.gnome.org/mailman/listinfo/desktop-devel-list
>
>

___
desktop-devel-list mailing list
desktop-devel-list@gnome.org
https://mail.gnome.org/mailman/listinfo/desktop-devel-list

Re: Documentation for build system setup

[Sébastien Wilmet]

On Thu, Feb 09, 2017 at 04:14:13PM +0100, Sebastian Geiger (Lanoxx) wrote:
> I have just updated the wiki, please let me know if something I changed
> is not right:
> 
> https://wiki.gnome.org/Projects/GnomeCommon/Migration

This is probably bikeshedding, but it's easier to remove lines than
adding lines, after copying the template.

--
Sébastien

> On 09/02/17 15:03, Emmanuele Bassi wrote:
> > On 9 February 2017 at 13:57, Sebastian Geiger (Lanoxx)  
> > wrote:
> >> What confuses me is that this paragraph starts with the phrase "it does
> >> not need any modifications made".
> >>
> >>> It does not need any modifications made, unless you need to run
> >>> another tool before configure, or do not use one of glib-gettextize,
> >>> gtkdocize or intltoolize. (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.)
> >> It might be more helpful to provide a autogen.sh listing that omits both
> >> glib-gettextize and intltoolize and then add a paragraph explaining to
> >> add these for project that use either of these tools. If I understand
> >> right both a deprecated anyway and should not be needed for
> >> state-of-the-art projects.
> >>
> >> Maybe write something like this:
> >>
> >> If 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
> > Those look like good changes, indeed. Feel free to update the wiki.
> >
> > Ciao,
> >  Emmanuele.
> >
> >> On 09/02/17 11:45, Philip Withnall wrote:
> >>> 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.
> >>
> >> ___
> >> desktop-devel-list mailing list
> >> desktop-devel-list@gnome.org
> >> https://mail.gnome.org/mailman/listinfo/desktop-devel-list
> >
> >
> 
> ___
> desktop-devel-list mailing list
> desktop-devel-list@gnome.org
> https://mail.gnome.org/mailman/listinfo/desktop-devel-list
___
desktop-devel-list mailing list
desktop-devel-list@gnome.org
https://mail.gnome.org/mailman/listinfo/desktop-devel-list