Add porters-handbook for USE_GNOME.

This contains two chapters. The first chapter explains USE_GNOME and
the macro's and the second chapter which lists all the possible
components with a short description.

Loosely based on the old porting guide (http://freebsd.org/gnome) and
the Qt chapter. The old porting guide will stick around for now until
I get around to updating the gnome website.

Reviewed by:	mat@, wblock@
Approved by:	mat@
Differential Revision:	https://reviews.freebsd.org/D3577
This commit is contained in:
Koop Mast 2015-09-17 07:14:39 +00:00
parent ea8e130e3b
commit deca97db7e
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=47421

View file

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