Installing Support Files

Complete Gnome applications consist of more than just code. They have online help, are listed on the Gnome panel's menu, have translations, and have a desktop icon. They might come with pixmaps as well: a logo for the "about" dialog, a graphic for a "wizard," or a small icons to help the user rapidly distinguish menu items or list elements. This section tells you how to ship some of these files.

Installing Datafiles: Documentation and Pixmaps

Documentation and pixmaps are installed in much the same way; automake allows you to install datafiles to arbitrary locations, and you can use variables defined by configure to decide where they should go.

Pixmaps

To install datafiles from your Makefile.am you simply come up with a name for the install target---pixmap seems good---then create a variable for the directory and a corresponding variable for the files to install there. For example:


EXTRA_DIST = gnome-hello-logo.png

pixmapdir = $(datadir)/pixmaps

pixmap_DATA = gnome-hello-logo.png

The "pixmap" string connects the pixmapdir variable with the pixmap_DATA variable. automake interprets the _DATA suffix and generates appropriate rules in Makefile.in. This Makefile.am segment installs gnome-hello-logo.png into $(datadir)/pixmaps; $(datadir) is a variable filled in by configure. Typically $(datadir) is /usr/local/share (more precisely, $(prefix)/share), which is the standard location for architecture-independent data files (that is, files which can be shared between several systems with different binary file formats).

the section called EXTRA_DIST describes the EXTRA_DIST variable.

The standard location for Gnome pixmaps is $(datadir)/pixmaps, so we used that in the example. The Gnome Project encourages the use of PNG format for all pixmaps; this format is supported by gdk_imlib, the Gnome image-loading library. It is also small, fast, and unencumbered by patents.

Documentation

Installing documentation uses the same principles, with a little more complication. Gnome documentation is typically written in DocBook. DocBook is an SGML DTD ("Document Type Definition") just as HTML is. However, DocBook's tags are designed for technical documentation. Documentation written in DocBook can be converted to several other formats, including PostScript and HTML. Standardly, you want to install the HTML format so users can read it with their web browser or the Gnome help browser.

The Gnome libraries and help browser understand a file called topic.dat, which is simply a list of help topics with corresponding URLs. It serves as an index of help topics for your application. Here's an example, with only two entries:


gnome-hello.html        GnomeHello manual 
advanced.html           Advanced Topics

URLs are relative to the directory where you install your help files.

You should consider in advance that your documentation will be translated into other languages. It is nice to make a subdirectory in your source tree for each locale; for example, the default C locale or the es (Spanish) locale. That way translations don't cause clutter. Gnome expects help to be installed in a directory named after the locale, so this arrangement is convenient from that point of view as well. Your documentation directory might look like this one from the GnomeHello example application:


doc/
  Makefile.am
  C/
    Makefile.am
    gnome-hello.sgml
    topic.dat
  es/
    Makefile.am
    gnome-hello.sgml
    topic.dat

Here is doc/C/Makefile.am:


gnome_hello_helpdir = $(datadir)/gnome/help/gnome-hello/C

gnome_hello_help_DATA =         \
        gnome-hello.html        \
        topic.dat

SGML_FILES =                    \
        gnome-hello.sgml

# files that aren't in a binary/data/library target have to be listed here
# to be included in the tarball when you 'make dist'
EXTRA_DIST = \
        topic.dat               \
        $(SGML_FILES)


## The - before the command means to ignore it if it fails.  that way
## people can still build the software without the docbook tools

all: 

gnome-hello.html: gnome-hello/gnome-hello.html
    -cp gnome-hello/gnome-hello.html .

gnome-hello/gnome-hello.html: $(SGML_FILES)
    -db2html gnome-hello.sgml

## when we make dist, we include the generated HTML so people don't
## have to have the docbook tools
dist-hook:
    mkdir $(distdir)/gnome-hello
    -cp gnome-hello/*.html gnome-hello/*.css $(distdir)/gnome-hello
    -cp gnome-hello.html $(distdir)

install-data-local: gnome-hello.html
    $(mkinstalldirs) $(gnome_hello_helpdir)/images
    -for file in $(srcdir)/gnome-hello/*.html $(srcdir)/gnome-hello/*.css; do \
    basefile=`basename $$file`; \
    $(INSTALL_DATA) $(srcdir)/$$file $(gnome_hello_helpdir)/$$basefile; \
    done

gnome-hello.ps: gnome-hello.sgml
    -db2ps $<

gnome-hello.rtf: gnome-hello.sgml       
    -db2rtf $<



In particular notice the install directory for the generated HTML files: $(datadir)/gnome/help/gnome-hello/C. The Gnome libraries look for help here. Each application's help goes in its own directory under $(datadir)/gnome/help. Each locale's documentation is installed in its own subdirectory of the application directory. Other rules in Makefile.am run the DocBook-to-HTML converter, include HTML in the distribution tarball, and create PostScript and Rich Text Format targets. (Users can create PostScript by typing make gnome-hello.ps explicitly.)

.desktop Entries

Gnome programs come with ".desktop entries," which are simply small files describing how the application should appear in menus. Installing a .desktop entry causes your application to show up in the Gnome panel menu. Here is gnome-hello.desktop:


[Desktop Entry]
Name=Gnome Hello
Name[es]=Gnome Hola
Name[fi]=GNOME-hei
Name[gl]=Ola GNOME
Name[no]=Gnome hallo
Name[sv]=Gnome Hej
Name[pl]=Halo GNOME
Comment=Hello World
Comment[es]=Hola Mundo
Comment[fi]=Hei, maailma
Comment[gl]=Ola Mundo
Comment[sv]=Hej Världen
Comment[no]=Hallo verden
Comment[pl]=Witaj ¶wiecie
Exec=gnome-hello
Icon=gnome-hello-logo.png
Terminal=0
Type=Application


The file consists of key-value pairs. The Name key specifies the name of your application in the default (C) locale; any key can have translations with a locale appended in brackets, such as Name[es]. The Comment key is a "tooltip" or hint describing the application in more detail. Exec is the command line to use to execute the program. Terminal is a boolean value; if non-zero, the program will be run inside a terminal. Type should always be "Application" in this context.

Installing a .desktop entry is simple; here is the toplevel Makefile.am from GnomeHello again:


SUBDIRS = macros po intl src pixmaps doc

## We dist autogen.sh since this is an example program
## Real-world programs do not need to distribute autogen.sh
EXTRA_DIST = \
        gnome-hello.desktop \
    autogen.sh

Applicationsdir = $(datadir)/gnome/apps/Applications
Applications_DATA = gnome-hello.desktop


Notice that there is a directory tree under $(datadir)/gnome/apps/ with subdirectories that arrange programs into categories. GnomeHello installs itself in the "Applications" category; other programs might choose "Games," "Graphics," "Internet," or whatever is appropriate. Try to choose a category that already exists, rather than inventing your own.

EXTRA_DIST

The EXTRA_DIST variable in a Makefile.am lists files to be included in the distribution (tarball). Most important files are automatically included; for example, all files listed as source files for binaries or libraries. However, automake does not know about .desktop files, or SGML documentation; so these files must be listed in EXTRA_DIST. make distcheck's attempt to build the distribution will normally fail if you leave files out of EXTRA_DIST.