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,844 @@
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 will explain 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 will cause 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/LIB/RUN 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 the
+ following 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
+
+ The above USE_GNOME component will automatically add other
+ USE_GNOME components it needs. Please see
+ the USE_GNOME
+ components page for the full list of all
+ USE_GNOME components and which other
+ components they imply.
+
+ Here is an example Makefile for a
+ GNOME port that uses many of the tricks outlined in this
+ document. Please use it as a guide for creating your own
+ 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 dependacies to the port.
+ USE_GNOME can be set after
+ bsd.port.options.mk has been
+ included, but not after
+ bsd.port.pre.mk.
+
+
+
+
+ Variables
+
+ This section explains which macros are available and what
+ their usage. The next section has a more in-depth explanation
+ and an example Makefile.
+
+
+
+ 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-based applications which use a
+ different 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 colon lists other USE_GNOME
+ dependencies the port depends on as a run dependency. If
+ the components supports arguments it listed
+ between () in the description. The first is what is defaulted
+ to. "Both" is used if the component defaults to adding to
+ build and run dependency.
+
+
+ GNOME Components
+
+
+
+
+ Component
+ Associated program
+ Implies
+ Description
+
+
+
+
+ atk
+ accessibility/atk
+ glib20
+ Accessibility toolkit (ATK)
+
+
+ atkmm
+ accessibility/atkmm
+ atk glibmm
+ c++ bindings for atk
+
+
+ cairo
+ graphics/cairo
+
+ Vector graphics library with cross-device output support
+
+
+ cairomm
+ graphics/cairomm
+ cairo libxml++26
+ c++ bindings for cairo
+
+
+ dconf
+ devel/dconf
+ glib20
+ Configuration database system (both,build,run)
+
+
+ evolutiondataserver3
+ databases/evolution-data-server
+ gtk30 libxml2
+ Data backends for the Evolution integrated mail/PIM suite
+
+
+ gdkpixbuf2
+ graphics/gdk-pixbuf2
+ glib20
+ Graphics library for GTK+
+
+
+ glib20
+ devel/glib20
+
+ GNOME core library glib20
+
+
+ glibmm
+ devel/glibmm
+ glib20 libsigc++20
+ c++ bindings for glib20
+
+
+ gnomecontrolcenter3
+ sysutils/gnome-control-center
+ gnomedesktop3 gnomemenus3 libxml2
+ GNOME 3 Control Center
+
+
+ gnomedesktop3
+ x11/gnome-desktop
+ gtk30
+ GNOME 3 desktop UI library
+
+
+ gsound
+ audio/gsound
+ glib20
+ GObject library for playing system sounds
+ (both,build,run)
+
+
+ gtk-update-icon-cache
+ graphics/gtk-update-icon-cache
+ atk gdkpixbuf2 pango
+ Gtk-update-icon-cache utility from the Gtk+
+ toolkit
+
+
+ gtk20
+ x11-toolkits/gtk20
+ atk gdkpixbuf2
+ Gtk+ 2 toolkit
+
+
+ gtk30
+ x11-toolkits/gtk30
+ glib20
+ Gtk+ 3 toolkit
+
+
+ gtkmm20
+ x11-toolkits/gtkmm20
+ gtk20
+ c++ bindings 2.0 for the gtk20 toolkit
+
+
+ gtkmm24
+ x11-toolkits/gtkmm24
+ atkmm gtk20 pangomm
+ c++ bindings 2.4 for the gtk20 toolkit
+
+
+ gtkmm30
+ x11-toolkits/gtkmm30
+ atkmm cairomm glibmm gtk30 pangomm
+ c++ bindings 3.0 for the gtk30 toolkit
+
+
+ gtksourceview2
+ x11-toolkits/gtksourceview2
+ gconf2 gtk20 libxml2
+ Widget that adds syntax highlighting to
+ GtkTextView
+
+
+ gtksourceview3
+ x11-toolkits/gtksourceview3
+ gtk30 libxml2
+ Text widget that adds syntax highlighting to
+ the GtkTextView widget
+
+
+ gtksourceviewmm3
+ x11-toolkits/gtksourceviewmm3
+ gtkmm30 gtksourceview3
+ c++ bindings for the gtksourceview3 library
+
+
+ gvfs
+ devel/gvfs
+ glib20
+ GNOME virtual file system
+
+
+ intltool
+ textproc/intltool
+
+ Tool for internationalization (also see
+ intlhack)
+
+
+ introspection
+ devel/gobject-introspection
+ glib20
+ 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
+ glib20 libxslt
+ Provides uniform access to different kinds of
+ data sources
+
+
+ libgda5-ui
+ databases/libgda5-ui
+ gnomedocutils gtk30 libgda5
+ UI library from the libgda5 library
+
+
+ libgdamm5
+ databases/libgdamm5
+ glibmm libgda5
+ c++ bindings for the libgda5 library
+
+
+ libgsf
+ devel/libgsf
+ gdkpixbuf2 libxml2
+ Extensible I/O abstraction for dealing with
+ structured file formats
+
+
+ librsvg2
+ graphics/librsvg2
+ gdkpixbuf2 libgsf libxml2 pango
+ Library for parsing and rendering SVG
+ vector-graphic files
+
+
+ libsigc++20
+ devel/libsigc++20
+
+ Callback Framework for C++
+
+
+ libxml++26
+ textproc/libxml++26
+ glibmm libxml2
+ c++ bindings for the libxml2 library
+
+
+ libxml2
+ textproc/libxml2
+
+ XML parser library (both,build,run)
+
+
+ libxslt
+ textproc/libxslt
+ libxml2
+ XSLT C library (both,build,run)
+
+
+ metacity
+ x11-wm/metacity
+ gtk30
+ Window manager from GNOME
+
+
+ nautilus3
+ x11-fm/nautilus
+ gnomedesktop3 gvfs libxml2
+ GNOME file manager
+
+
+ pango
+ x11-toolkits/pango
+ cairo glib20
+ Open-source framework for the layout and
+ rendering of i18n text
+
+
+ pangomm
+ x11-toolkits/pangomm
+ cairomm glibmm pango
+ c++ bindings for the pango library
+
+
+ py3gobject3
+ devel/py3-gobject3
+ glib20 introspection
+ Python 3, GObject 3.0 bindings
+
+
+ pygobject3
+ devel/py-gobject3
+ glib20 introspection
+ Python 2, GObject 3.0 bindings
+
+
+ vte3
+ x11-toolkits/vte3
+ gtk30
+ 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
+ Implies
+ Description
+
+
+
+
+ atspi
+ accessibility/at-spi
+ gconf2 gtk20 libbonobo
+ Assistive Technology Service Provider
+ Interface
+
+
+ esound
+ audio/esound
+
+ Enlightenment sound package
+
+
+ gal2
+ x11-toolkits/gal2
+ libgnomeprintui libgnomeui
+ Collection of widgets taken from GNOME 2
+ gnumeric
+
+
+ gconf2
+ devel/gconf2
+ gtk20 libxml2 orbit2
+ Configuration database system for GNOME 2
+
+
+ gconfmm26
+ devel/gconfmm26
+ gconf2 glibmm
+ c++ bindings for gconf2
+
+
+ gdkpixbuf
+ graphics/gdk-pixbuf
+ gtk12
+ Graphics library for GTK+
+
+
+ glib12
+ devel/glib12
+
+ glib 1.2 core library
+
+
+ gnomedocutils
+ textproc/gnome-doc-utils
+ libxslt
+ GNOME doc utils
+
+
+ gnomemimedata
+ misc/gnome-mime-data
+
+ MIME and Application database for GNOME 2
+
+
+ gnomesharp20
+ x11-toolkits/gnome-sharp20
+ gnomevfs2 gtksharp20 libgnomeprintui libgnomeui
+ librsvg2 vte
+ GNOME 2 interfaces for the .NET runtime
+
+
+ gnomespeech
+ accessibility/gnome-speech
+ libbonobo
+ GNOME 2 text-to-speech API
+
+
+ gnomevfs2
+ devel/gnome-vfs
+ gconf2 gnomemimedata
+ GNOME 2 Virtual File System
+
+
+ gtk12
+ x11-toolkits/gtk12
+ glib12
+ Gtk+ 1.2 toolkit
+
+
+ gtkhtml3
+ www/gtkhtml3
+ gconf2 gtk20
+ Lightweight HTML rendering/printing/editing
+ engine
+
+
+ gtkhtml4
+ www/gtkhtml4
+ gtk30
+ Lightweight HTML rendering/printing/editing
+ engine
+
+
+ gtksharp20
+ x11-toolkits/gtk-sharp20
+ gtk20 libglade2
+ GTK+ and GNOME 2 interfaces for the .NET
+ runtime
+
+
+ gtksourceview
+ x11-toolkits/gtksourceview
+ libgnome libgnomeprintui
+ Widget that adds syntax highlighting to
+ GtkTextView
+
+
+ libartgpl2
+ graphics/libart_lgpl
+
+ Library for high-performance 2D graphics
+
+
+ libbonobo
+ devel/libbonobo
+ libxml2 orbit2
+ Component and compound document system for
+ GNOME 2
+
+
+ libbonoboui
+ x11-toolkits/libbonoboui
+ libgnome libgnomecanvas
+ GUI frontend to the libbonobo component of
+ GNOME 2
+
+
+ libgda4
+ databases/libgda4
+ glib20 libxslt
+ Provides uniform access to different kinds of
+ data sources
+
+
+ libglade2
+ devel/libglade2
+ gtk20 libxml2
+ GNOME 2 glade library
+
+
+ libgnome
+ x11/libgnome
+ esound gnomevfs2 libbonobo
+ Libraries for GNOME 2, a GNU desktop
+ environment
+
+
+ libgnomecanvas
+ graphics/libgnomecanvas
+ libartlgpl2 libglade2
+ Graphics library for GNOME 2
+
+
+ libgnomekbd
+ x11/libgnomekbd
+ gtk30 libxml2
+ GNOME 2 keyboard shared library
+
+
+ libgnomeprint
+ print/libgnomeprint
+ glib20 libartlgpl2 libxml2 pango
+ Gnome 2 print support library
+
+
+ libgnomeprintui
+ x11-toolkits/libgnomeprintui
+ libgnomecanvas libgnomeprint
+ Gnome 2 print support library
+
+
+ libgnomeui
+ x11-toolkits/libgnomeui
+ libbonoboui gvfs
+ Libraries for the GNOME 2 GUI, a GNU desktop
+ environment
+
+
+ libgtkhtml
+ www/libgtkhtml
+ gnomevfs2 libxslt
+ Lightweight HTML rendering/printing/editing
+ engine
+
+
+ libgtksourceviewmm
+ x11-toolkits/libgtksourceviewmm
+ gtkmm24 gtksourceview2
+ c++ binding of GtkSourceView
+
+
+ libidl
+ devel/libIDL
+ glib20
+ Library for creating trees of CORBA IDL file
+
+
+ libsigc++12
+ devel/libsigc++12
+
+ Callback Framework for C++
+
+
+ libwnck
+ x11-toolkits/libwnck
+ gtk20
+ Library used for writing pagers and
+ taskslists
+
+
+ libwnck3
+ x11-toolkits/libwnck3
+ gtk30
+ Library used for writing pagers and
+ taskslists
+
+
+ orbit2
+ devel/ORBit2
+ libidl
+ High-performance CORBA ORB with support for the
+ C language
+
+
+ pangox-compat
+ x11-toolkits/pangox-compat
+ glib20 pango
+ Deprecated pangoX support that was split off
+ from the main pango package.
+
+
+ pygnome2
+ x11-toolkits/py-gnome2
+ libgnomeui pygtk2
+ Python bindings for GNOME 2
+
+
+ pygobject
+ devel/py-gobject
+ glib20 introspection
+ Python 2, GObject 2.0 bindings
+
+
+ pygtk2
+ x11-toolkits/py-gtk2
+ libglade2 pygobject
+ Set of Python bindings for GTK+
+
+
+ pygtksourceview
+ x11-toolkits/py-gtksourceview
+ gtksourceview2 pygtk2
+ Python bindings for GtkSourceView 2
+
+
+ vte
+ x11-toolkits/vte
+ gtk20
+ 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 is installed. This can be used for ports
+ that do 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 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.
+
+
+
+