All posts by Javier Jardón

gnome, gtk+

Help improve Glib/GTK+ documentation

1 Comment

Update: Before start working in a module, check that It’s not already deprecated (like CList or CTree): these modules will be removed in GTK+3 so the doc migration is not needed

One of the tasks to improve the GTK+/Glib docs maintenance is to convert the documentation from templates (*.sgml) files into source-comments. This is a easy tasks that everybody can do.

All the process is documented here: [1]

Here a step-by-step example to help new contributors 😉

  1. Download GTK+ and gtk-doc source code:

    cd ~/git
    git clone git://git.gnome.org/gtk-doc
    git clone git://git.gnome.org/gtk+

  2. Execute gtk-doc script to convert the documentation

    cd gtk+/docs/reference/gtk
    ~/git/gtk-doc/tools/migratetmpl.pl –module=gtk

    This creates a “src” directory containing “*.c” files with all the comments.

  3. Copy and paste them to the right place.

    The section docs are best placed in the *.c file. Put them below the copyright header and the main includes (if there is no *.c file use the appropriate *.h file).
    All other comment blocks should be put directly above the definition of the symbol.

    For example, for GtkAccelGroup, we’d move the comments from gtk+/docs/reference/gtk/src/gtkaccelgroup.c to gtk+/gtkaccelgroup.c and gtk+/gtkaccelgroup.h

  4. Remove the template file:

    git rm docs/reference/gtk/tmpl/gtkaccelgroup.sgml

  5. Check that the documentation is correctly generated with:

    ./autogen –enable-gtk-doc
    make

    then go with a browser to docs/reference/gtk/html

  6. Send a patch to bugzilla and make it block 599599 for GTK+ or 589775 for Glib documentation.
  7. Update the wiki page [1] to avoid duplicate work

When adding the source code comment, its a good opportunity to review it a bit. Have a look on spelling and style. Is it really giving a helpful explanation what the function does, etc. Also improve cross references. The gtk-doc syntax of the comments is described in the gtk-doc manual [2].

You can take a look to the gtkwidget.h [3] and gtkwidget.c [4] code as an example.

[1] http://live.gnome.org/GTK+/TaskAPIDocMigration

[2] http://library.gnome.org/devel/gtk-doc-manual/unstable/documenting_syntax.html.en

[3] http://git.gnome.org/browse/gtk+/tree/gtk/gtkwidget.h

[4] http://git.gnome.org/browse/gtk+/tree/gtk/gtkwidget.c

gnome

Modernize your autotools build system

11 Comments

Update: I converted this post in a new GnomeGoal, see here

Update 2: Added some more tips

Autotools is the most common system to build programs in GTK+/GNOME projects.

Remove deprecated macros for our configure.ac file and use the new syntax will do our build system more legible and portable

The Autotools comes with a program to make the work for us, simply run

autoupdate

in you source tree and you have a new updated configure.ac. (Checks the result for possibles errors)

Some more tips:

  • Respect the standard configure.ac layout
  • Try to avoid the use of AM_MAINTAINER_MODE. AM_MAINTAINER_MODE (called like that) disables dependency-checking for autotools-generated stuff. AM_MAINTAINER_MODE([enabled]) retains the default behavior, but lets users pass a configure option to disable the dependency checking. So, if you really need this macro, use AM_MAINTAINER_MODE([enabled]). See the automake manual for a extended explanation
  • Use all the parameters of AC_INIT() (for the fifth parameter you need autoconf >= 2.64):
AC_INIT([Glom],[1.13.2],[http://bugzilla.gnome.org/enter_bug.cgi?product=Glom],[glom],[http://www.glom.org/])
  • Use updated versions of the programs (all of these versions (and newer) are present in Debian stable):
    • automake >= 1.11.1 (AM_INIT_AUTOMAKE([1.11.1])) (or 1.10.3, Automake < 1.10.3 and 1.11 are known to be suffering from critical security issues)
    • autoconf >= 2.64 (AC_PREREQ(2.64))
    • libtool >= 2.2.6 (LT_PREREQ([2.2.6]))
    • intltool >= 0.40.0 (IT_PROG_INTLTOOL([0.40.0]))
  • Take a look to all AM_INIT_AUTOMAKE() posible parameters. For example, to use 1.11.1 automake version and generate bzip2 distribution tarballs in addition to the gzip’ed:
AM_INIT_AUTOMAKE([1.11.1 dist-bzip2])
  • Use LT_INIT() syntax for libtool (needs libtool >= 2.2.0). More info about LT_INIT(). For example, change this:
AC_LIBTOOL_DLOPEN
AC_LIBTOOL_WIN32_DLL
AC_DISABLE_STATIC
AM_PROG_LIBTOOL

For this:

LT_PREREQ([2.2.6])
LT_INIT([dlopen win32-dll disable-static])
  • Don’t use GNOME_COMMON_INIT, as it does not work with autoreconf. Simply add this to your Makefile.am. (You have to define the macros dir in your configure.ac, in this case: AC_CONFIG_MACRO_DIR([m4]))
ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS}
  • Use gnome-common macros for compile warnings macros instead custom ones. Also use GNOME_MAINTAINER_MODE_DEFINES to get warnings when using deprecated symbols:
GNOME_COMPILE_WARNINGS([maximum])
GNOME_CXX_WARNINGS([yes])
GNOME_MAINTAINER_MODE_DEFINES

Other tips

Feel free to suggest more tips in the comments!

Some documentation:


Flattr this

gnome

Help cleaning GNOME Bugzilla

Leave a comment

Do you want to help cleaning GNOME Bugzilla?

Are you afraid because you are a newbie? Or you don’t know where to start?

In a recent Bugsquad meeting [1], a new initiative was propossed: the BugsquadGoals [2] .

This is the objective: Setting small concrete goals to clean some kind of bugs from the database.

For example: Search for bugs about a crash without the correct value in severity field (critical). Also, set the keyword STACKTRACE if the bug has a decent Stacktrace with line numbers and symbols.

You have more info and the bugzilla queries in the BugsquadGoals page [2]. Also, any suggestion for other queries are always welcomed.

If you have any problem or you want to request some Bugzilla permissions, we are in irc channel on irc.gnome.org.

See you there!

[1] http://live.gnome.org/Bugsquad/Meetings/20091009

[2] http://live.gnome.org/Bugsquad/BugsquadGoals

gnome

2009: My GNOME year

Leave a comment

2009 was a great year: I started to contribute to GNOME this year for the first time.

I’ve worked in Gnome 3 cleanup tasks, bugsquad, GnomeGoals and finally I’ve done some GTK+ patches.

After reading Andre Annual GNOME Bugzilla statistics for 2009, I’ve recollected some of my statistics since my first bug report in 2009-04-26 (255 days ago): [1]

  • 201 Bugs reported (4th position)
  • 300 patches (2th position)

Although some of the patches are quite trivial, I think that they are good numbers for a newbie like me 😉

But the best thing was meet great people in the GNOME community; Thank you to all the people that help me this year, was great work with you 😉

Looking forward to 2010!

[1] https://bugzilla.gnome.org/page.cgi?id=weekly-bug-summary.html;days=255

gnome, gtk+

Adapt your module to GNOME3 / GTK+3

Leave a comment

Hello all!

I’ve been working in GNOME3 “cleaning” tasks for some time and I’d like to share this mini-guide to make your library/application GNOME3 / GTK+3-compilant. The process is quite easy:

GNOME 3:

Don’t use deprecated libraries:

GTK+ 3:

When you finish, use GNOME_MAINTAINER_MODE_DEFINES macro ( included in gnome-common ) in your configure.ac files, so you will be notified when you use a new deprecated symbol.

Also, take a look to the awesome Frederic Peters graphs to track the status of your module: http://www.gnome.org/~fpeters/299.html