Index: en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
===================================================================
--- en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
+++ en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
@@ -1401,11 +1401,847 @@
Using GNOME
- The &os;/GNOME project uses its own set of variables to
- define which GNOME components a particular port uses. A comprehensive
- list of these variables exists within the
- &os;/GNOME project's homepage.
+
+ Introduction
+
+ This chapter explains the GNOME
+ framework as used by ports. The framework can be loosely
+ divided into the base components, GNOME
+ desktop components, and a few special macros that simplify the
+ work of port maintainers.
+
+ While developing a port or changing one, please set
+ DEVELOPER=yes
+ in the environment or in /etc/make.conf.
+ This causes the ports framework to enable additional
+ checks.
+
+
+
+ Using <varname>USE_GNOME</varname>
+
+ Adding this variable to the port allows the use of
+ the macros and components defined in
+ bsd.gnome.mk. The code in
+ bsd.gnome.mk adds the needed
+ build-time, run-time or library dependencies
+ or the handling of special files.
+ GNOME applications under &os; use the
+ USE_GNOME infrastructure. Include all the
+ needed components as a space-separated list. The
+ USE_GNOME components are divided into
+ these virtual lists: basic components, GNOME 3 components
+ and legacy components. If the port needs only GTK3 libraries,
+ this is the shortest way to define it:
+
+ USE_GNOME= gtk30
+
+ USE_GNOME components automatically
+ add the dependencies they need. Please see
+ page for an exhaustive list of
+ all USE_GNOME components and which other
+ components they imply and their dependencies.
+
+ Here is an example Makefile for a
+ GNOME port that uses many of the techniques outlined in this
+ document. Please use it as a guide for creating new
+ ports.
+
+ # $FreeBSD$
+
+PORTNAME= regexxer
+PORTVERSION= 0.10
+CATEGORIES= devel textproc gnome
+MASTER_SITES= GNOME
+
+MAINTAINER= kwm@FreeBSD.org
+COMMENT= Interactive tool for performing search and replace operations
+
+USES= gettext gmake pathfix pkgconfig tar:xz
+GNU_CONFIGURE= yes
+USE_GNOME= gnomeprefix intlhack gtksourceviewmm3
+CPPFLAGS+= -I${LOCALBASE}/include
+LDFLAGS+= -L${LOCALBASE}/lib
+INSTALLS_ICONS= yes
+
+GLIB_SCHEMAS= org.regexxer.gschema.xml
+
+.include <bsd.port.mk>
+
+
+ The USE_GNOME macro without any
+ arguments does not add any dependencies to the port. And
+ USE_GNOME can not be set after
+ bsd.port.pre.mk.
+
+
+
+
+ Variables
+
+ This section explains which macros are available and how they
+ are used. Like they are used in the above example. The
+ has a more in-depth
+ explanation. USE_GNOME has to be set for
+ these macro's to be of use.
+
+
+
+ INSTALLS_ICONS
+
+
+ GTK+ ports which install
+ Freedesktop-style icons to
+ ${LOCALBASE}/share/icons should use
+ this macro to ensure that the icons are cached and will
+ display correctly. The cache file is named
+ icon-theme.cache. Do not include
+ that file in pkg-plist. This macro
+ handles that automatically. This macro is not needed
+ for Qt, which use a
+ internal method.
+
+
+
+
+ GLIB_SCHEMAS
+
+
+ List of all the glib schema files the port installs.
+ The macro will add the files to the port plist and
+ handle the registration of these files on install and
+ deinstall.
+
+ The glib schema files are written in
+ XML and end with the
+ gschema.xml extension. They are
+ installed in the
+ share/glib-2.0/schemas/ directory.
+ These schema files contain all application config values
+ with there default settings. The actual database used
+ by the applications is built by
+ glib-compile-schema, which is
+ run by the GLIB_SCHEMAS macro.
+
+ GLIB_SCHEMAS=foo.gschema.xml
+
+
+ Do not add glib schemas to the
+ pkg-plist. If they are listed in
+ pkg-plist, they will not be
+ registered and the applications might not work
+ properly.
+
+
+
+
+
+ GCONF_SCHEMAS
+
+
+ List all the gconf schema files. The macro will add
+ the schema files to the port plist and will handle their
+ registration on install and deinstall.
+
+ GConf is the XML-based database
+ that virtually all GNOME applications use for storing
+ their settings. These files are installed into the
+ etc/gconf/schemas directory. This
+ database is defined by installed schema files that are
+ used to generate %gconf.xml key
+ files. For each schema file installed by the port,
+ there be an entry in the
+ Makefile:
+
+ GCONF_SCHEMAS=my_app.schemas my_app2.schemas my_app3.schemas
+
+
+ Gconf schemas are listed in the
+ GCONF_SCHEMAS macro rather than
+ pkg-plist. If they are listed in
+ pkg-plist, they will not be
+ registered and the applications might not work
+ properly.
+
+
+
+
+
+ INSTALLS_OMF
+
+
+ Open Source Metadata Framework
+ (OMF) files are commonly used by
+ GNOME 2 applications. These files contain the
+ application help file information, and require special
+ processing by ScrollKeeper/rarian. To properly register
+ OMF files when installing GNOME
+ applications from packages, make sure that
+ omf files are listed in
+ pkg-plist and that the port
+ Makefile has
+ INSTALLS_OMF defined:
+
+ INSTALLS_OMF=yes
+
+ When set, bsd.gnome.mk
+ automatically scans pkg-plist and
+ adds appropriate @exec and
+ @unexec directives for each
+ .omf file to track in the
+ OMF registration database.
+
+
+
+
+
+
+
+ GNOME Components
+
+ For further help with a GNOME port, look at some of the
+ existing
+ ports for examples. The
+ &os; GNOME
+ page has contact information if more help is
+ needed.
+
+ The components are divided into GNOME components that are
+ currently in use and legacy components.
+
+ The Implies colomn lists other
+ USE_GNOME dependencies the port depends
+ on as a run dependency. If the component supports argument,
+ they are listed between parenthesis in the
+ description. The first is the default. "Both" is shown if the
+ component defaults to adding to both build and run
+ dependencies.
+
+
+ GNOME Components
+
+
+
+
+ Component
+ Associated program
+ Description
+
+
+
+
+
+ atk
+ accessibility/atk
+ Accessibility toolkit (ATK)
+
+
+
+ atkmm
+ accessibility/atkmm
+ c++ bindings for atk
+
+
+
+ cairo
+ graphics/cairo
+ Vector graphics library with cross-device output support
+
+
+
+ cairomm
+ graphics/cairomm
+ c++ bindings for cairo
+
+
+
+ dconf
+ devel/dconf
+ Configuration database system (both, build, run)
+
+
+
+ evolutiondataserver3
+ databases/evolution-data-server
+ Data backends for the Evolution integrated mail/PIM suite
+
+
+
+ gdkpixbuf2
+ graphics/gdk-pixbuf2
+ Graphics library for GTK+
+
+
+
+ glib20
+ devel/glib20
+ GNOME core library glib20
+
+
+
+ glibmm
+ devel/glibmm
+ c++ bindings for glib20
+
+
+
+ gnomecontrolcenter3
+ sysutils/gnome-control-center
+ GNOME 3 Control Center
+
+
+
+ gnomedesktop3
+ x11/gnome-desktop
+ GNOME 3 desktop UI library
+
+
+
+ gsound
+ audio/gsound
+ GObject library for playing system sounds
+ (both, build, run)
+
+
+
+ gtk-update-icon-cache
+ graphics/gtk-update-icon-cache
+ Gtk-update-icon-cache utility from the Gtk+
+ toolkit
+
+
+
+ gtk20
+ x11-toolkits/gtk20
+ Gtk+ 2 toolkit
+
+
+
+ gtk30
+ x11-toolkits/gtk30
+ Gtk+ 3 toolkit
+
+
+
+ gtkmm20
+ x11-toolkits/gtkmm20
+ c++ bindings 2.0 for the gtk20 toolkit
+
+
+
+ gtkmm24
+ x11-toolkits/gtkmm24
+ c++ bindings 2.4 for the gtk20 toolkit
+
+
+
+ gtkmm30
+ x11-toolkits/gtkmm30
+ c++ bindings 3.0 for the gtk30 toolkit
+
+
+
+ gtksourceview2
+ x11-toolkits/gtksourceview2
+ Widget that adds syntax highlighting to
+ GtkTextView
+
+
+
+ gtksourceview3
+ x11-toolkits/gtksourceview3
+ Text widget that adds syntax highlighting to
+ the GtkTextView widget
+
+
+
+ gtksourceviewmm3
+ x11-toolkits/gtksourceviewmm3
+ c++ bindings for the gtksourceview3 library
+
+
+
+ gvfs
+ devel/gvfs
+ GNOME virtual file system
+
+
+
+ intltool
+ textproc/intltool
+ Tool for internationalization (also see
+ intlhack)
+
+
+
+ introspection
+ devel/gobject-introspection
+ Basic introspection bindings and tools to
+ generate introspection bindings. Most of the time
+ :build is enough, :both/:run is only need for
+ applications that use introspection bindings.
+ (both, build, run)
+
+
+
+ libgda5
+ databases/libgda5
+ Provides uniform access to different kinds of
+ data sources
+
+
+
+ libgda5-ui
+ databases/libgda5-ui
+ UI library from the libgda5 library
+
+
+
+ libgdamm5
+ databases/libgdamm5
+ c++ bindings for the libgda5 library
+
+
+
+ libgsf
+ devel/libgsf
+ Extensible I/O abstraction for dealing with
+ structured file formats
+
+
+
+ librsvg2
+ graphics/librsvg2
+ Library for parsing and rendering SVG
+ vector-graphic files
+
+
+
+ libsigc++20
+ devel/libsigc++20
+ Callback Framework for C++
+
+
+
+ libxml++26
+ textproc/libxml++26
+ c++ bindings for the libxml2 library
+
+
+
+ libxml2
+ textproc/libxml2
+ XML parser library (both, build, run)
+
+
+
+ libxslt
+ textproc/libxslt
+ XSLT C library (both, build, run)
+
+
+
+ metacity
+ x11-wm/metacity
+ Window manager from GNOME
+
+
+
+ nautilus3
+ x11-fm/nautilus
+ GNOME file manager
+
+
+
+ pango
+ x11-toolkits/pango
+ Open-source framework for the layout and
+ rendering of i18n text
+
+
+
+ pangomm
+ x11-toolkits/pangomm
+ c++ bindings for the pango library
+
+
+
+ py3gobject3
+ devel/py3-gobject3
+ Python 3, GObject 3.0 bindings
+
+
+
+ pygobject3
+ devel/py-gobject3
+ Python 2, GObject 3.0 bindings
+
+
+
+ vte3
+ x11-toolkits/vte3
+ Terminal widget with improved accessibility and
+ I18N support
+
+
+
+
+
+
+ GNOME Macro Components
+
+
+
+
+ Component
+ Description
+
+
+
+
+
+ gnomeprefix
+ Supply configure with
+ some default locations.
+
+
+
+ intlhack
+ Same as intltool, but patches to make sure
+ share/locale/ is used. Please only
+ use when intltool alone is not
+ enough.
+
+
+
+ referencehack
+ This macro is there to help splitting of the API or
+ reference documentation into its own port.
+
+
+
+
+
+
+ GNOME Legacy Components
+
+
+
+
+ Component
+ Associated program
+ Description
+
+
+
+
+
+ atspi
+ accessibility/at-spi
+ Assistive Technology Service Provider
+ Interface
+
+
+
+ esound
+ audio/esound
+ Enlightenment sound package
+
+
+
+ gal2
+ x11-toolkits/gal2
+ Collection of widgets taken from GNOME 2
+ gnumeric
+
+
+
+ gconf2
+ devel/gconf2
+ Configuration database system for GNOME 2
+
+
+
+ gconfmm26
+ devel/gconfmm26
+ c++ bindings for gconf2
+
+
+
+ gdkpixbuf
+ graphics/gdk-pixbuf
+ Graphics library for GTK+
+
+
+
+ glib12
+ devel/glib12
+ glib 1.2 core library
+
+
+
+ gnomedocutils
+ textproc/gnome-doc-utils
+ GNOME doc utils
+
+
+
+ gnomemimedata
+ misc/gnome-mime-data
+ MIME and Application database for GNOME 2
+
+
+
+ gnomesharp20
+ x11-toolkits/gnome-sharp20
+ GNOME 2 interfaces for the .NET runtime
+
+
+
+ gnomespeech
+ accessibility/gnome-speech
+ GNOME 2 text-to-speech API
+
+
+
+ gnomevfs2
+ devel/gnome-vfs
+ GNOME 2 Virtual File System
+
+
+
+ gtk12
+ x11-toolkits/gtk12
+ Gtk+ 1.2 toolkit
+
+
+
+ gtkhtml3
+ www/gtkhtml3
+ Lightweight HTML rendering/printing/editing
+ engine
+
+
+
+ gtkhtml4
+ www/gtkhtml4
+ Lightweight HTML rendering/printing/editing
+ engine
+
+
+
+ gtksharp20
+ x11-toolkits/gtk-sharp20
+ GTK+ and GNOME 2 interfaces for the .NET
+ runtime
+
+
+
+ gtksourceview
+ x11-toolkits/gtksourceview
+ Widget that adds syntax highlighting to
+ GtkTextView
+
+
+
+ libartgpl2
+ graphics/libart_lgpl
+ Library for high-performance 2D graphics
+
+
+
+ libbonobo
+ devel/libbonobo
+ Component and compound document system for
+ GNOME 2
+
+
+
+ libbonoboui
+ x11-toolkits/libbonoboui
+ GUI frontend to the libbonobo component of
+ GNOME 2
+
+
+
+ libgda4
+ databases/libgda4
+ Provides uniform access to different kinds of
+ data sources
+
+
+
+ libglade2
+ devel/libglade2
+ GNOME 2 glade library
+
+
+
+ libgnome
+ x11/libgnome
+ Libraries for GNOME 2, a GNU desktop
+ environment
+
+
+
+ libgnomecanvas
+ graphics/libgnomecanvas
+ Graphics library for GNOME 2
+
+
+
+ libgnomekbd
+ x11/libgnomekbd
+ GNOME 2 keyboard shared library
+
+
+
+ libgnomeprint
+ print/libgnomeprint
+ Gnome 2 print support library
+
+
+
+ libgnomeprintui
+ x11-toolkits/libgnomeprintui
+ Gnome 2 print support library
+
+
+
+ libgnomeui
+ x11-toolkits/libgnomeui
+ Libraries for the GNOME 2 GUI, a GNU desktop
+ environment
+
+
+
+ libgtkhtml
+ www/libgtkhtml
+ Lightweight HTML rendering/printing/editing
+ engine
+
+
+
+ libgtksourceviewmm
+ x11-toolkits/libgtksourceviewmm
+ c++ binding of GtkSourceView
+
+
+
+ libidl
+ devel/libIDL
+ Library for creating trees of CORBA IDL file
+
+
+
+ libsigc++12
+ devel/libsigc++12
+ Callback Framework for C++
+
+
+
+ libwnck
+ x11-toolkits/libwnck
+ Library used for writing pagers and
+ taskslists
+
+
+
+ libwnck3
+ x11-toolkits/libwnck3
+ Library used for writing pagers and
+ taskslists
+
+
+
+ orbit2
+ devel/ORBit2
+ High-performance CORBA ORB with support for the
+ C language
+
+
+
+ pygnome2
+ x11-toolkits/py-gnome2
+ Python bindings for GNOME 2
+
+
+
+ pygobject
+ devel/py-gobject
+ Python 2, GObject 2.0 bindings
+
+
+
+ pygtk2
+ x11-toolkits/py-gtk2
+ Set of Python bindings for GTK+
+
+
+
+ pygtksourceview
+ x11-toolkits/py-gtksourceview
+ Python bindings for GtkSourceView 2
+
+
+
+ vte
+ x11-toolkits/vte
+ Terminal widget with improved accessibility and
+ I18N support
+
+
+
+
+
+
+ Deprecated Components: Do Not Use
+
+
+
+
+ Component
+ Description
+
+
+
+
+
+ HAVE_GNOME
+ Deprecated, do not use. Was used to check if a
+ component was installed. This was used for ports
+ that did not have
+ --enable/--disable
+ switches for their configure script. But the building of
+ parts of a port without a implicit request is
+ discouraged.
+
+
+
+ WANT_GNOME
+ Deprecated, do not use. Was used by ports that
+ needed USE_GNOME for optional
+ dependencies, which where defined after
+ bsd.port.pre.mk. Since
+ USE_GNOME can be used after the
+ inclusion of bsd.port.options.mk,
+ there is little need for this macro any more.
+
+
+
+ pangox-compat
+ pangox support provided by x11-toolkits/pangox-compat.
+ Which is deprecated and split off from the pango package.
+
+
+
+
+