GNOME Developer Documentation
Brent Smith GNOME Developer Documentation
GNOME Developer Documentation by Brent Smith This is 2.13.0 version of this document.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later revision published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found here.
Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps. Dedication
Dedication
This book is dedicated to the community that makes great free software like GNOME possible.
i GNOME Developer Documentation
Table of Contents
Foreward ...... iv 1. What is GNOME? ...... 5 The History of the GNOME Desktop ...... 5 What defines the GNOME Desktop? ...... 6 GNOME Application Requirements ...... 7 The Software “Stack” ...... 7 2. Getting Started Developing for GNOME ...... 9 Requirements ...... 9 First Application ...... 9 Using Callback Functions ...... 10 3. Using Glade to Design User Interfaces ...... 11 Designing with glade-2 ...... 11 Using libglade2 to Parse Glade Files ...... 11 A. GNOME Platform ...... 12 GNOME Developer Platform ...... 12 GNOME Desktop ...... 14 GNOME Platform Bindings ...... 18 B. Building and Installing the GNOME platform ...... 20 Using GARNOME ...... 20 Using Jhbuild ...... 20
ii GNOME Developer Documentation
List of Tables
A.1. Libraries and Applications in the GNOME Developer Platform ...... 12 A.2. Libraries and Applications in the GNOME Desktop ...... 14 A.3. Bindings for C++ ...... 18 A.4. Bindings for Java ...... 18 A.5. Bindings for Perl ...... 19 A.6. Bindings for Python ...... 19
iii Foreward
Foreward
This document is meant as an introduction to the GNOME Desktop and Platform for new developers. The goals of the book are to help the reader understand the GNOME platform and guide them through the development of a full fledged application. It intends to be a complete reference for all required components of a GNOME application, including HIG compliance, internationalization, help document support, MIME support, etc.
iv Chapter 1. What is GNOME?
GNOME is known to as a desktop environment for UNIX/Linux operating systems. It strives to be a simple to use graphical environment with sane defaults. It is completely free and open source, developed by hundreds of people around the world. It has seen amazing growth and had been adapted as a platform by many companies including Sun Microsystems, Novell, IBM and others.
GNOME is also a community of users and developers who design, code, translate, QA and have fun together. If you are interested in joining a thriving community of developers, then GNOME just might be for you. For more information about
The History of the GNOME Desktop
GNOME was born out of the desire for a completely free desktop environment that was not encumbered by restrictive licensing schemes. During its infancy, there were other efforts at creating a desktop environment (namely KDE), however these efforts were based on a library whose licensing scheme was, at the time, not compatible with the ideals of free software.
There are other reasons that GNOME was born, although none of them quite as important as the licensing reasons. GNOME sought to attack some of the stagnation that was happening in UNIX by fostering the concepts of code reuse and code sharing. Innovation was slowed by the fact that code was not allowed to be modified and redistributed freely. Therefore, it was decided that GNOME should be developed from a shared code base. GNOME also recognized that people used computers to simplify their lives by automating daily tasks and have fun, and therefore sought to make a desktop environment that was easy and provided sensible defaults.
GNOME's early years were spent at the Red Hat Advanced Development Labs where it was worked on by a handful of developers. The first official version was released in March 1999, but adoption was slow due to instability issues. A much improved version was released in October 1999 which proved to be a much greater success and enjoyed wide deployment. Two companies were founded around developing different aspects of the GNOME desktop. Eazel was founded in 1999 and worked heavily on the nautilus file manager. Helix Code was also founded and involved in many of the infrastructural aspects of the developer platform as well the now popular Evolution mail client. Involvement from industry grew even further after the announcement of the GNOME Foundation at the Linux World Expo in August of 2000. Sun Microsystems adopted the platform as well other companies such as HP and IBM. Sun Microsystems proceeded to be very generous in their feedback in terms of the accessibility and documentation aspects of the GNOME platform.
GNOME 2.0, the first in the GNOME 2.X series, was the result of a tremendous amount of work yielding a new version of the GTK+ widget set. GTK+ 2.0 was the culmination of three years of work integrating and improving the technology that was present in GTK+ 1.4. The GObject framework was added into glib which allowed for bindings to nearly any programming language. Full support for unicode and internationalized text through Pango was integrated. New widgets were introduced and a port to of GDK 1 to Microsoft Windows™ was added. From the GTK+ 2.0 release announcement itself:
The huge feature set of GTK+ 2.0 more than doubles the size of GTK+ 1.2, moving from 230,000 lines of code to 620,000 lines of code. Over the last three years a line of code was added to GTK+ every 5 minutes. Nonetheless a statically-linked version of gtk-demo can still fit on a 1.4M floppy disk.
1GDK is the drawing abstraction library used by GTK+
5 Chapter 1. What is GNOME? What defines the GNOME Desktop?
—GTK+ Development Team
The most obvious change being a new, attractive look to the widget set as well as support for anti-aliased text, it was clear that a new version of GNOME was required to take advantage of these features. GNOME 2.0 was released a few months after GTK+ on June 26th, 2002. It was extremely well received and many distributions shipped it in their next release.
Today, the stable version of the GNOME Desktop is 2.12 while the development series is 2.13. Many changes have been made since the initial release of GNOME, such as the recent addition of the Cairo library to the software stack. Since it is often hard to distinguish the new features present in each version of the desktop, a summary of changes can be found in the release notes at http://live.gnome.org/ReleaseNotes What defines the GNOME Desktop?
GNOME is... Free GNOME is free software and part of the GNU project, dedicated to giving users and developers the ultimate level of control over their desktops, their software, and their data. Usable GNOME understands that usability is about creating software that is easy for everyone to use, not about piling on features. GNOME's community of professional and volunteer usability experts have created Free Software's first and only Human Interface Guidelines, and all core GNOME software is adopting these principles. Find out more about GNOME and usability at the GNOME Usability Project. Accessible Free Software is about enabling software freedom for everyone, including users and developers with disabilities. GNOME's Accessibility framework is the result of several years of effort, and makes GNOME the most accessible desktop for any Unix platform. Find out more at the GNOME Accessibility Project. International GNOME is used, developed and documented in dozens of languages, and we strive to ensure that every piece of GNOME software can be translated into all languages. Find out more at the GNOME Translation Project. Developer-friendly Developers are not tied to a single language with GNOME. You can use C, C++, Python, Perl, Java, even C#, to produce high-quality applications that integrate smoothly into the rest of your Unix or Linux desktop. Organized GNOME strives to be an organized community, with a foundation of several hundred members, usability, accessibility, and QA teams, and an elected board. GNOME releases are defined by the GNOME Release Team and are scheduled to occur every six months. Supported Beyond the worldwide GNOME Community, GNOME is supported by the leading companies in Linux and Unix, including HP, MandrakeSoft, Novell, Red Hat, and Sun. Find out more at foundation.gnome.org. A Community Perhaps more than anything else, GNOME is a worldwide community of volunteers who hack, translate, design, QA, and generally have fun together. Find out more at GNOME Developer's site.
6 Chapter 1. What is GNOME? GNOME Application Requirements
Look familiar?
That's probably because all this was shamelessly stolen from the http://www.gnome.org/ about webpage. Is this OK? GNOME Application Requirements
Although there is no official certification for GNOME applications (yet), there is an expectation that applications follow some rules, like using the GTK+ widget set, and don't link against deprecated libraries. Below is a unfinished list of some of the rules that GNOME apps should follow. • GTK+ 2.0 should be used as the widget set • HIG compliance - Human Interface Guidelines • No use of deprecated libraries The Software “Stack”
You will often hear the term “software stack” from developers when they are referring to the libraries and APIs2 that make up the GNOME platform. In this section we will try to present a brief overview of the libraries and their dependencies. For a more in depth review of the libraries, please see Appendix A, GNOME Platform. GTK+, GDK, Pango, Cairo, Xft and Glib
GTK+ GTK+ provides a widget set implementation based on all the following libraries. GTK+ is used by all GNOME applications for user interface elements. GDK GDK is a drawing abstraction library used by GTK+. GDK depends on Pango. Pango Pango is a library for layout and internationalization of text. Pango can be used with different font backends, including cairo, the freetype and fontconfig libraries, or the native Win32 API. As can be seen in the diagram, Pango depends on the presence of glib, cairo and Xft. Cairo Cairo is a 2D drawing library that supports multiple output devices.
2Application Programming Interfaces - the set of functions that are exported by a library that allow developers to perform specific functions without knowing the specifics of the implementation
7 Chapter 1. What is GNOME? The Software “Stack”
Xft Xft is a library that provides an API for rendering text and also supports configuration and naming. Glib Glib is a utility library that is the lowest in the software stack, meaning it has no dependencies itself but is a dependency for a lot of other programs. Glib provides data types, macros, type conversions, string utilities, file utilities, a main loop abstraction, memory management, singly and doubly linked lists, hash tables, threads, binary trees, and so on. Glib also contains the gobject type system. It works on many UNIX-like platforms, Windows, OS/2 and BeOS. libgnomeui, libgnome, libbonobo, gnome-vfs, GConf, esound, libxml2, libxslt
libgnomeui Libgnomeui provides support for additional widgets including Druids and the GnomeApp widget. libgnome Libgnome provides an API for application initialization, playing sounds, accessing configuration settings and displaying external information such as the help system and opening urls. libbonobo Libbonobo is an C-based implementation of the Bonobo component architecture for creating reusable and distributed software components. GConf GConf is a key/value registry for storing basic data types such as booleans, integers, strings, lists and pairs3. The gconfd-2 daemon starts when the user logs into GNOME and handles requests from client applications and performs notifications when a key is changed. Libgnome uses the gconf library for providing an API to access keys set by the library itself. esound An audio mixer daemon. Since many soundcards do not support hardware mixing, esound provides a software based solution that allows multiples sounds to be played at once. Libgnome uses the esound library to provide an API for playing sounds. libxslt Libxslt is the XSLT4 C library developed for the GNOME project. This allows the conversion of XML documents into other XML documents. libxml2 Libxml2 is the XML C parser and toolkit developed for the GNOME project. It provides API for both SAX and DOM interfaces and has complete implementations for XPath, XInclude and XPointer. Language bindings are available for a number of different languages.
3Pairs are very rarely used... 4XSLT - XML Stylesheet Language Transformations
8 Chapter 2. Getting Started Developing for GNOME
Requirements
Before you get started writing applications for GNOME, there are some requirements which you must meet. First, you must have the GNOME Developer Platform installed. This contains all the modules necessary to compile and run a GNOME application. If you are not sure whether or not you have the support libraries installed, then don't worry; if you are running GNOME chances are everything will be fine. If you are not, then please refer to Appendix B, Building and Installing the GNOME platform for instructions on how to build and install GNOME.
Second, it is assumed you are familiar with developing applications in C. We can't possibly cover all the basics of the language, so you must be somewhat comfortable with the language otherwise you won't make any progress. You must also be familiar with using a compiler such as gcc and should be familiar with the concept of a Makefile.
Finally, blah blah blah. First Application
The following example creates a very simple GNOME application that opens up a window on your screen. The source code for the application is available in the gnome-dev-docs modules, in the gnome2-developer-guide/examples/example1/first-program.c file. A simple Makefile is included to compile the application.
1 /* This is a simple first program for new GNOME Developers */ 2 #include
Let's start at the beginning. After the function declaration for main, a variable of type GtkWidget is declared. If you are familiar with object oriented programming, GtkWidget is a base class that all GTK+
9 Chapter 2. Getting Started Developing for GNOME Using Callback Functions
widgets derive from. Next, a call is made to the gnome_program_init function. This function does most of the dirty work of loading all the GNOME specific libraries and parsing any command line options that may have been specified on the command line. Note that it will only handle certain options which relate to the GNOME library. 1
Next, main_window is assigned the return value from the call to the gnome_new_app function. 2 This function does all the dirty work of creating a window. To actually get the window to be shown however, we need to call gtk_window_show.
Using Callback Functions
If you compiled and ran the first example from a terminal, you will notice that it doesn't actually terminate when you click on the close button in the titlebar. This is because we did not provide a callback function for the “destroy” signal.
So what is a callback function? Callback functions are meant to process events, usually related to some kind of input such as key presses and mouse clicks. In this case, the destroy signal is activated when you click on the close button. To handle this, we need to “connect” the signal with a callback function. To do this, we use the g_signal_connect function.
1If you are curious what command line options it handles, run
$ first-program --help from the command line. It should print out all the options that are available through the GNOME library. 2The actual type returned by this function is GnomeApp, however this is a derived class of GtkWidget. If you are familiar with object oriented programming, you'll realize that casting a derived class to a broader type (a superclass) is perfectly fine.
10 Chapter 3. Using Glade to Design User Interfaces
Creating a user interface using C is often a verious tedious process and can be detrimental to rapid development of an application. Glade is a user interface design tool that allows you to create an interface and save it as an XML file. The XML file is usually given the extension .glade. For that reason we will refer to these files as “glade” files.
Glade also supports code generation, although it is not recommended that you use this feature since the code that it generates can be out of date and have other problems. Designing with glade-2
Introduction to glade-2 Using libglade2 to Parse Glade Files
blah blah blah
11 Appendix A. GNOME Platform
Appendix A. GNOME Platform
Unfortunately, due to the distributed way that GNOME is developed by people all over the world, it has been difficult in the past to figure out what certain libraries or applications do as a new developer. This section is an attempt to provide a single resource for information about each module of the desktop. You can browse through it now to get familiar with some of the modules, or use it as a reference when you encounter an unknown further along in the book.
The GNOME desktop has been split up into two primary module sets. There is also a third module which contains all the language bindings for GNOME. Most of the information that follows has been gathered from various sources such as the modules' README files and project websites to aid the reader in understanding the big picture™ of the GNOME platform.
Now we will dive into some of the gory details of what GNOME is today. The following tables provide a detailed, if not comprehensive, list of all the modules that make up GNOME. The Component column lists each module by its name in the official GNOME cvs repository. As mentioned above, the Description column has been gathered from various sources. GNOME Developer Platform
This module set consists of all the libraries and applications that provide core functionality to GNOME. These modules are all subject to the GNOME Developer Platform API/ABI rules.
Table A.1. Libraries and Applications in the GNOME Developer Platform Component Description GConf Provides a key/value configuration system reminiscent of the Windows registry, but with added support for notifications to client applications, and other features that make it more powerful ORBit2 This is a CORBA implementation that facilitates IPC (interprocess communication) between applications at-spi The GNOME accessibility infrastructure. atk The Accessibility Toolkit is a set of interfaces created on top the gobject type system, that once implemented, allow GUI objects to be accessible. This library is toolkit independent; for actual implementation of the interfaces for GTK+ widgets, see libgail audiofile
12 Appendix A. GNOME Platform GNOME Developer Platform
Component Description A platform independent, low-level library that forms the basis for GTK+ and GNOME. Provides data structure handling for C, portability wrappers, and interfaces for such runtime functionality as an event loop, threads, dynamic loading, and an object system (gobject). gnome-mime-data Contains the MIME database that is used by GNOME to map file names and extensions to mime-types. Also contains database of applications, and the mime-types that each application can handle. Meant to be used with the MIME functions available in GnomeVFS. gnome-vfs File system abstraction library that has support for basic POSIX style file operations, asynchronous APIs, file monitoring, metadata, cancellation, and file transfers. gtk+ From the website, “GTK+ is a multi-platform toolkit for creating graphical user interfaces. Offering a complete set of widgets, GTK+ is suitable for projects ranging from small one-off projects to complete application suites.”. GTK+ is the basis for all the graphical applications in GNOME, and depends on the presence of the Pango, ATK, and glib libraries. gtk-doc A utility to generate DocBook XML files from source code. It was originally created to document the API for GTK+, however many other GNOME libraries now make use of it to document their APIs. intltool A tool for doing various translation related function. As explained in the REAMDE, intltool can “Extract translatable strings from various source files (.xml.in, .glade, .desktop.in, .server.in, .oaf.in)”, “Collect the extracted strings together with messages from traditional source files (.c, .h) in po/$(PACKAGE).pot.”, and “Merge back the translations from .po files into .xml, .desktop and .oaf files. This merge step will happen at build resp. installation time.” libIDL A library for creating trees of CORBA Interface Definition Language files. libart_lgpl This is the LGPL (Lesser GNU Public License) version of the libart library, which is a “High performance 2D graphics library”. It is currently used to provide the antialiasing support in GNOME canvas. libbonobo From the README, “Bonobo is a set of language and system independant CORBA interfaces for creating reusable components, controls and creating compound documents.” Bonobo also provides a per-system activation system. The UI components of bonobo are available in the libbonoboui module. libbonoboui The UI portion of the Bonobo framework. libglade Allows for rapid application development through the use of “glade interface files” which describe a particular user interface. Many applications create the user interface
13 Appendix A. GNOME Platform GNOME Desktop
Component Description independently of the source code, and then are able to use this library to load the interface at runtime. libgnome Originally developed as gnome-libs, the libgnome library provides an API for a number of different functions on the desktop. Some of these include initializing gnome applications, providing access to the gnome help system, opening urls in the user's preferred browser and more. This is the non-UI library. libgnomecanvas The GNOME canvas is an engine for structured graphics that offers a rich imaging model, high performance rendering, and a powerful, high-level API. It offers a choice of two rendering back-ends, one based on Xlib for extremely fast display, and another based on libart. libgnomeui This is the UI portion of the GNOME library, which provides support for session management, druids, and other custom miscellaneous widgets such as GnomeColorPicker. libxml2 Libxml2 is the XML C parser and toolkit developed for the GNOME project. It provides API for both SAX and DOM interfaces and has complete implementations for XPath, XInclude and XPointer. Language bindings are available for a number of different languages. libxslt Libxslt is the XSLT C library developed for the GNOME project. XSLT is a an XML language to define transformations for XML. This allows the conversion of XML documents into other XML documents. pango Pango is a library for layout and rendering of text, with an emphasis on internationalization. Pango forms the core of text and font handling for GTK+-2.x. pkgconfig Pkgconfig is a script to ease the construction of build flags when linking against certain libraries. It supports integration with autotools and the configure.in file. GNOME Desktop
This module set contains all the applications and libraries that do not yet conform to the core GNOME Developer Platform API/ABI rules. Table A.2. Libraries and Applications in the GNOME Desktop Component Description bug-buddy A graphical application that handles bug reporting due to crashes and abort errors. It can extract debugging information from core files or crashed applications via gnome_segv. control-center Collection of applications to control preferences of the GNOME Desktop. eel The Eazel extension library. Originally developed in conjunction with the Nautilus application, this code found more common use in the desktop and was
14 Appendix A. GNOME Platform GNOME Desktop
Component Description integrated as a shared library. Provides a “collection of widgets and extensions to many modules of the GNOME desktop” eog (Eye of GNOME) This is the standard image viewer that comes with the GNOME Desktop. By default Nautilus, the file manager, opens most images with this application. Epiphany Epiphany is a GNOME web browser based on the mozilla/gecko rendering engine. Epiphany's main principles are simplicity and standards compliance. evince A document image viewer. Supports PDF, Postscript, djvu, tiff and dvi formats. evolution-data-server
15 Appendix A. GNOME Platform GNOME Desktop
Component Description other programs. It can manage multiple keyrings, each with its own master password. gnome-keyring-manager A graphical application to manage a user's keyrings. The development of this program was a collaboration between new developers in the gnome-love group and experienced GNOME hackers who were willing to mentor them. gnome-netstatus An applet that provides network information for a particular interface on your panel. gnome-nettool A frontend to a collection of commandline networking tools, such as ping, netstat, traceroute, nmap (port scan), lookup, finger and whois. gnome-mag A screen magnification tool used in conjunction with gnopernicus and the GAIL Accessibility layer present in GNOME. gnome-media Collection of utilities related to Multimedia within GNOME. Includes cd player, CDDB daemon, volume meter, audio mixer, sound recorder and gstreamer preferences dialog. gnome-menus This package contains an implementation of the draft "Desktop Menu Specification" from freedesktop.org. gnome-panel An area on the desktop that allows the embedding of applets and applications, such as the Workspace Switcher, the Window List, the Window Selector, the Notification Area, the Clock and the infamous 'Wanda the Fish' gnome-session The GNOME session manager and related utilities. gnome-speech A Library providing a general API for text to speech output. gnome-system-monitor Should this be "procman" instead? gnome-system-tools A collection of utilities to configure users and groups, date and time network configuration, bootloaders and runlevels. Meant to ease administration tasks for the new user. gnome-terminal The GNOME terminal emulator. Provides tab support for multiple terminals, customizable profiles and themes. Note the this is simply a shell around a customized terminal emulation widget, which is provided by the vte module. gnome-themes A collection of themes for the GNOME Desktop. Includes GTK+ themes, icon themes, and Metacity (Window Manager) themes. gnome-user-docs A collection of documenation for the GNOME desktop. Contents are the GNOME Accessibilty Guide, GNOME System Administrator's guide, and the GNOME 2 User's Guide. Also includes an introduction to GNOME. gnome-utils Various utilities consisting of a dictionary, a search tool, a system log viewer, a screenshot utility and a floppy formatter.
16 Appendix A. GNOME Platform GNOME Desktop
Component Description gnome-volume-manager Daemon and control panel applet that enfore volume related policy. Works in conjunction with HAL (Hardware Abstraction Layer). gnomemeeting From the FAQ on the GNOME meeting web site, “GnomeMeeting is an H.323 compatible videoconferencing and VOIP/IP-Telephony application that allows you to make audio and video calls to remote users with H.323 hardware or software (such as Microsoft Netmeeting).” gnopernicus Gnopernicus provides Assistive Technologies (AT) for blind and visually impaired persons. It makes use of the screen magnifier, speech library and other tools to ease the use of the GNOME Desktop for these users. gok GNOME On-screen Keyboard. Allows the user to control their computer by using alternate input methods. gstreamer A framework for streaming media in GNOME. gst-plugins A collection of plugins that allow gstreamer to recognize and process different file formats. gtk-engines Contains a number of gtk-engines that customize the look of the GTK+ widget set. gtkhtml GtkHTML is a lightweight HTML rendering/printing/ editing engine. It is used in place of the Mozilla/Gecko engine in several applications because of its lightweight codebase. It was originally based on KHTMLW, part of the KDE project is now independently developed. gtksourceview An extension of the standard GtkTextView widget that supports syntax highlighting and other features typical of a source code editor. gucharmap A featureful unicode character map. libgail-gnome Accessibility implementations for the extended GTK+ widgets found in the libgnomeui library. libgnomeprint Printing API for GNOME applications that supports Postscript, a GnomeCanvas-based preview, and direct rendering to RGB. libgnomeprintui Graphical portion of the libgnomeprint library, with implementations for a print dialog, font selection dialog, print preview and other print related functions. libgtop A portability library for getting system specific data such as CPU and memory usage and information about running processes. librsvg A high performance SVG rendering library associated with the GNOME Project. libsoup An HTTP library implementation written in C. Features asynchronous operation, connection caching, SSL support, proxy support and authentication support for both client and server. libwnck From the README, “libwnck is Window Navigator Construction Kit, i.e. a library to use for writing pagers and taskslists and stuff.”
17 Appendix A. GNOME Platform GNOME Platform Bindings
Component Description metacity The standard window manager for the GNOME desktop. nautilus An extremely feature-rich file manager for the GNOME desktop. nautilus-cd-burner An extension for nautilus that allows the user to burn CDs. scrollkeeper sound-juicer A CD ripping tool that uses gstreamer. Also supports playing CDs. startup-notification A library and protocol for identifying when applications have started and finished initializing. totem A movie player that uses either gstreamer or xine as a backend. It features a playlist, a full-screen mode, seek and volume controls, as well as complete keyboard navigation. A mozilla plugin and nautilus thumbnailer are also included. vino An integrated VNC server that supports confirmation and password authentication. vte A implemenation of a terminal emulation widget. yelp The default help browser for the GNOME desktop. Yelp provides a simple graphical interface for viewing DocBook, HTML, man, and info formatted documentation. zenity A rewrite of gdialog, the GNOME port of dialog which allows you to display dialog boxes from the commandline and shell scripts. GNOME Platform Bindings
This module set contains the language bindings for C++, Java, Perl, and Python.
Table A.3. Bindings for C++
Component Description glibmm bindings for glib gtkmm bindings for gtk+, pango, atk libglademm bindings for libglade gconfmm bindings for GConf libgnomecanvasmm bindings for libgnomecanvas libgnome-vfsmm bindings for gnome-vfs libgnomemm bindings for libgnome libgnomeuimm bindings for libgnomeui libxml++ bindings for libxml
Table A.4. Bindings for Java
Component Description libgtk-java bindings for GTK+, glib, Pango, ATK
18 Appendix A. GNOME Platform GNOME Platform Bindings
Component Description libgnome-java bindings for libgnome, libgnomecanvas, and libgnomeui libgconf-java bindings for GConf libglade-java bindings for libglade
Table A.5. Bindings for Perl
Component Description Glib bindings for glib Gtk2 bindings for GTK+ Glade bindings for glade Gnome2-GConf bindings for GConf Gnome2-Canvas bindings for libgnomecanvas Gnome2-VFS bindings for gnome-vfs Gnome2 bindings for libgnome, and libgnomeui
Table A.6. Bindings for Python
Component Description pygtk bindings for glib, GTK+, ATK, pango, and libglade GnomePython bindings for libgnome, libgnomeui, gnome-vfs, GConf, libbonobo, and libbonoboui
19 Appendix B. Building and Installing the GNOME platform
Appendix B. Building and Installing the GNOME platform
Once upon a time, building and installing GNOME was not an easy task. There are literally hundreds of modules in the official GNOME CVS repositories. Understanding all the complex dependencies between each module is very difficult. Since testers and developers often compile from source, something was needed to maintain dependency information and make the compilation process easier. Two projects eventually filled this gap, GARNOME and jhbuild. Both help to automate the build and install process for users and developers.
GARNOME is a set of build scripts and tarballs1 that automate the build process. GARNOME is very widely used and has a strong community. Should you find yourself running into problems as you inevitably will, I would encourage you to look to the mailing list at [email protected] for help.
Jhbuild is the other method to building and installing the GNOME platform. Unlike GARNOME, jhbuild does not require you to download tarballs. Instead the GNOME modules are pulled directly from the CVS repositories at cvs.gnome.org. Jhbuild is used more often by core GNOME testers and developers, since it often provides access to the most recent development versions of GNOME modules.
Even though these automated tools exist, building and installing GNOME can still be a challenging task. There are many resources available to GNOME developers. Using GARNOME
Explain how to use GARNOME to build GNOME. Using Jhbuild
The official site for jhbuild is http://www.freedesktop.org/Software/jhbuild.
The main features of jhbuild are its dependency handling and error checking. Dependency information for each cvs module is included in an XML file in the modulesets directory in the source tree. This allows a set of modules to be defined for the gnome-2.10 desktop, the gnome-2.12 desktop, and so on. In the case of an error while building a module, jhbuild will give you the choose of rechecking out the source tree, dropping to a shell, re-running the configure stage and other options. If you choose to give up on the module, then any modules that explicitly depend on the unsuccessful one will not be built. At the end of the build process, a list of modules that were not built is printed. Prerequisites
The following are the prerequisites necessary to use the jhbuild system: • Python >= 2.2 • autoconf >= 2.58 • automake 1.4-p6, 1.7.x, 1.8.x and 1.9.x (these are parallel installable) • libtool >= 1.5
1The term tarball general refers to a versioned release of a certain GNOME cvs module as a compressed tar archive.
20 Appendix B. Building and Installing the GNOME platform Using Jhbuild
• gettext >= 0.10.40 • pkgconfig >=
You can determine whether or not you meet the requirements by running
$ jhbuild sanitycheck which will report any problems in your installation. If there are problems reported, then you basically have two options: • Install the tools from your distribution to satisfy the requirements. • Run the command jhbuild bootstrap in order to install a version of the necessary tools into your install root. You will need to setup a ~/.jhbuildrc configuration file in order to complete this command. If you choose to install the tools this way, then run the jhbuild sanitycheck command after the bootstrapping completes to ensure that everything was installed properly. Installing
There are no official releases of jhbuild in .tar.gz form, since the modulesets that define dependency and package information are frequently updated. Therefore, you must obtain the latest version from the GNOME cvs repository.
To get the latest version from GNOME cvs:
$ cvs -d :pserver:[email protected]:/cvs/gnome login Logging in to :pserver:[email protected]:2401/cvs/gnome CVS password:
$ cd jhbuild $ make $ make install Configuration
Before you start building GNOME, you have to setup a configuration file called .jhbuildrc in your home directory. Since there are many modulesets, some that are not even related to GNOME, you need to specify which module set to use. There is a sample.jhbuildrc that comes with jhbuild. We've provided a modified version that file to get you up and running below.
# edit this file to match your settings and copy it to ~/.jhbuildrc
# information about cvs server cvsroots['gnome.org'] = ':pserver:[email protected]:/cvs/gnome' cvsroots['cairo.freedesktop.org'] = ':pserver:[email protected]:/cvs/cairo'
# What module set should be used. The default at the moment is 'gnome28', # but it can be any of the files in the modulesets directory, or even # the URL of a module set file on a web server. moduleset = 'gnome-2.12'
# Modules to build (dependencies are also built); Defaults to GNOME Desktop and Developer Platform modules = [ 'meta-gnome-desktop' ]
# The directory where the modules from CVS are checked out to checkoutroot = '/opt/cvs/gnome2'
21 Appendix B. Building and Installing the GNOME platform Using Jhbuild
# the prefix to configure/install modules to (user must have write access) prefix = '/opt/gnome2'
# Extra arguments to pass to ./autogen.sh script # these options will speed builds, but API documentation will not be generated #autogenargs='--disable-static --disable-gtk-doc'
# Miscellaneous options for how to go about the build process # See the jhbuild manual for details. #alwaysautogen = True #makeclean = True
# option to set CFLAGS: #os.environ['CFLAGS'] = '-g -O2'
# On SMP systems you may use something like this to improve compilation time: # be aware that not all modules compile correctly with make -j2 #os.environ['MAKE'] = 'make -j2'
# a alternative install program to use. # The included install-check program won't update timestamps if the header hasn't changed os.environ['INSTALL'] = os.path.expanduser('~/bin/install-check') Using JHBuild
Using JHBuild
22