Документ взят из кэша поисковой машины. Адрес
оригинального документа
: http://www.sao.ru/cats/~satr/GGAD/z72.html
Дата изменения: Wed Jul 12 23:54:36 2000 Дата индексирования: Mon Oct 1 23:59:14 2012 Кодировка: Поисковые слова: п п п п п п п п п п п п п п п п п п п п п п п |
GTK+ / Gnome Application Development | |||
---|---|---|---|
<<< Previous | Home | Next >>> |
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.
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.
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.
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.)
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.
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.