Gnome applets with Python
Prev		Next

7. Autotools : a brief introduction to the installation process

Ok, we have our shiny brand new applet running and we are pretty proud of ourselves. Now it's time to learn how to distribute it so the world can be proud too. You may think 'hey, this is Python code, no compilation it's needed, we can just send them the .py files and the applet will work'. Well, it won't because all the paths are absolute to our own machine configuration, icons are needed and .glade files and .server files as well, so we need to distribute them somehow. In UNIX world, this task is commonly done with the ./configure --prefix=PATH --other-options command, but it's not so common to know the process of having all the correct files working. I did this task with version 1.7 of automake and aclocal and autoconf 2.58, because some Python macros weren't in 1.4 version. This section is based on some documents on the net (look at bibliography) and my own experience. There is a really good document from German Po in Spanish here so If you can read this language it's your lucky day.

So, besides giving the user the facility to install our applet, the nice feature of doing the configure process, is that we can refer to our application files relative to a prefix previously defined.

7.1. The project structure: directories and files needed

Each time we make a pyGTK applet we need to have some files in our project. This is an example of what our project directory should contain:

            |-- AUTHORS 
            |-- COPYING -> /usr/share/automake-1.7/COPYING 
            |-- ChangeLog 
            |-- INSTALL -> /usr/share/automake-1.7/INSTALL 
            |-- Makefile
            |-- Makefile.am 
            |-- Makefile.in 
            |-- NEWS 
            |-- README 
            |-- aclocal.m4 
            |-- config.log
            |-- config.status
            |-- configure
            |-- configure.in 
            |-- images    
            |   |-- Makefile
            |   |-- Makefile.am
            |   |-- Makefile.in
            |   |-- bug-buddy.png
            |   |-- centrino.gif
            |   |-- centrino.jpg
            |   |-- green_led_0.gif
            |   |-- green_led_1.gif
            |   |-- green_led_2.gif
            |   |-- green_led_3.gif
            |   |-- green_led_4.gif
            |   |-- green_led_5.gif
            |   |-- green_led_6.gif
            |   |-- green_led_7.gif
            |   |-- green_led_8.gif
            |   `-- green_led_9.gif
            |-- install-sh -> /usr/share/automake-1.7/install-sh
            |-- missing -> /usr/share/automake-1.7/missing
            |-- mkinstalldirs -> /usr/share/automake-1.7/mkinstalldirs
            |-- py-compile -> /usr/share/automake-1.7/py-compile
            |-- servers (11)
            |   |-- GNOME_SampleApplet.server
            |   |-- Makefile
            |   |-- Makefile.am
            |   `-- Makefile.in
            `-- src             (12)
                |-- Makefile
                |-- Makefile.am
                |-- Makefile.in
                |-- sample.glade
                |-- sample.gladep
                |-- sample.py
                |-- sample.pyc
                |-- sample_globals.py
                |-- sample_globals.py.in (13)
                |-- sample_globals.pyc

: It contains the names of who have been working on the application.
: It specifies the copy and distribution permissions of the application. It's a good idea allowing automake command generate this file, if you want it GPL.
: It keep all the changes made to the source and the application itself.
: It contains instalation instructions for our application. automake provides us with a generic file, but you should personalize for your application.
: It's a file with recent changes of the application.
: It contains a general description of the package, and it's possible to include some aditional instructions.
(11)(12): This directories will contain the images and icons for our application, the bonobo .server files and the source code and glade files.
: It contains the verification and construction rules of the project. It is the base for creating the configure script. The rules are written in m4 language.
: It's the file that automake command will use to generate the Makefile file, needed to construct the application. It must exists a Makefile.am file for every directory in our project.
: aclocal.m4 will be used by autoconf to search for automake macros. It is generated by aclocal-1.7 command.
(13): sample_globals.py.in in the src/ directory, will contain references to @PREFIX@ and @VERSION@ variables, to define others variables, like image_dir, glade_dir, etc...at the final final, without the .in extension

7.2. Creating these files

When creating these files commented in the previous section, we need to put them on this order:

Place a NEWS and AUTHORS file at the root directory. Makefile.am will search for them.
The Makefile.am in every directory, the project root directory included. The Makefile.am at the root directory will contain only the subdirs that we need to explore looking for others .am files.
The configure.in at the root directory.
The aclocal.m4, that we'll obtain by running aclocal-1.7 command at the root directory.
Running the command automake-1.7 --add-missing at the root directory will create some files more we'll need: COPYING, INSTALL and some links to other utilities, install.sh, mkinstalldirs, py-compile... It will create also the Makefile.in, that next command, autoconf will need.
Running autoconf at the root directory we will have the final configure script.
We can have some .in files at the src directory, that could be use to generate them without the .in at 'configure' runtime, like a sample_globals.py.in that contains some variables like version, programname, or image_dir that will be used in execution time by the applet to find the files it needs.

7.3. Editing the files Makefile.am and configure.in

So we need to edit these files to get things working. If we look at step 2, we need some Makefile.am files. The one at the root directory will contain this:

          SUBDIRS = src images servers

It's what we need to explore this directories for others Makefile.am files in order to generate Makefiles files correctly.

The file at the src/ directory contains:

            bin_SCRIPTS = sample.py

            sampledir = $(prefix)/bin

            sample_PYTHON = \
                    sample_globals.py

            uidir = $(datadir)/sample
            ui_DATA = sample.glade

            DISTCLEANFILES = \
                   $(ui_DATA) \         
                   $(bin_SCRIPTS)         

            EXTRA_DIST =  \
                    $(bin_SCRIPTS) \
                    $(sample_PYTHON) \
                    $(ui_DATA)

These are the variables needed to our simple applet. Look at the gnome-blog source code (bibliography) if you want to do anything out of the scope of this tutorial, like adding gconf support or gettext.

Now we must edit the configure.in file at the root directory. It use m4 macros to check the software our application will need. This is the code for our simple applet. However, look at gnome-blog or some others GNU applications to have an idea of how to do it more complicated, or the m4 manual at bibliography section:

                AC_INIT(src/sample.py)
                AM_INIT_AUTOMAKE(sample, 0.2)

                AM_MAINTAINER_MODE

                dnl check for python -- 'dnl' is used for comments
                AM_PATH_PYTHON

                PKG_CHECK_MODULES(PYGTK, pygtk-2.0)
                AC_SUBST(PYGTK_CFLAGS)
                AC_SUBST(PYGTK_LIBS)

                AC_OUTPUT([
                Makefile
                src/Makefile
                src/sample_globals.py
                images/Makefile
                servers/Makefile
                ])

We have some macros to check the .py and init the automake process, and the check if we have the python interpreter and python modules installed correctly.

Prev	Home	Next
The callback methods		Example applet