367 lines
14 KiB
Text
367 lines
14 KiB
Text
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
|
|
<!ENTITY base CDATA "../..">
|
|
<!ENTITY date "$FreeBSD: www/en/gnome/docs/porting.sgml,v 1.45 2004/11/16 07:35:53 mezz Exp $">
|
|
<!ENTITY title "FreeBSD GNOME Project: How To Make a Port">
|
|
<!ENTITY % gnomeincludes SYSTEM "../includes.sgml"> %gnomeincludes;
|
|
<!ENTITY % includes SYSTEM "../../includes.sgml"> %includes;
|
|
]>
|
|
<html>
|
|
&header;
|
|
|
|
<p>This document assumes that you already know how the port system works,
|
|
and therefore only provides GNOME-specific hints and tips. General
|
|
instructions can be found in the
|
|
<a href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/porters-handbook/index.html">FreeBSD Porter's Handbook</a>.
|
|
</p>
|
|
|
|
<h2>Example Makefile</h2>
|
|
<p>There is an <a href="example-Makefile.html">example Makefile</a> for a GNOME
|
|
port, which uses many of the tricks outlined in this document. Please feel free to
|
|
use it as a guide for creating your own ports.</p>
|
|
|
|
<h2>GNOME Makefile Macros</h2>
|
|
<p>GNOME applications under FreeBSD use the <b>USE_GNOME</b>
|
|
infrastructure. To specify which components of the GNOME
|
|
system your port needs in order to build, simply list them
|
|
all as a space-separated list. For example:</p>
|
|
|
|
<pre>
|
|
USE_X_PREFIX= yes
|
|
USE_GNOME= gnomeprefix gnomehack libgnomeui
|
|
</pre>
|
|
|
|
|
|
<p>The <b>USE_GNOME</b> components are divided into the following two lists:</p>
|
|
|
|
<ul>
|
|
<li><p><a href="gnome_porting.html">GNOME desktop-version-independent
|
|
components</a></p></li>
|
|
<li><p><a href="gnome2_porting.html">GNOME 2 components</a></p></li>
|
|
<li><p><a href="gnome1_porting.html">GNOME 1 components</a></p></li>
|
|
</ul>
|
|
|
|
<!-- I'm not sold on the utility of this section -->
|
|
<p>If your port needs only <b>GTK2</b> libraries, the following is
|
|
the shortest way to define this:</p>
|
|
|
|
<pre>
|
|
USE_X_PREFIX= yes
|
|
USE_GNOME= gtk20
|
|
</pre>
|
|
|
|
<p>If your port needs only <b>GTK1</b> libraries, the following is
|
|
the shortest way to define this:</p>
|
|
|
|
<pre>
|
|
USE_X_PREFIX= yes
|
|
USE_GNOME= gtk12
|
|
</pre>
|
|
|
|
<p>Even if your application needs only the GTK libraries, other
|
|
<b>USE_GNOME</b> components may be useful. Please scan the entire
|
|
list to make sure your port uses all relevant components.</p>
|
|
<!-- end questionable section -->
|
|
|
|
<p>Once you have finished with your port, it is a good idea to
|
|
verify that your port depends on the correct list of components.
|
|
To see a list of what packages your port will actually require,
|
|
use the command <tt>make package-depends</tt> from within
|
|
your port's directory.</p>
|
|
|
|
<p>To aid in creating the list of necessary components,
|
|
it can be helpful to examine the output of <tt>make configure</tt>.
|
|
At the end of the <tt>checking for...</tt> list, there will be a line
|
|
similar to this:</p>
|
|
|
|
<pre>
|
|
checking for libgnomeui-2.0 >= 2.0.0 cspi-1.0 >= 1.1.7
|
|
libspi-1.0 >= 1.1.7 libbonobo-2.0 >= 2.0.0 atk >= 1.0.0
|
|
gtk+-2.0 >= 2.0.0 gail libwnck-1.0 esound... yes
|
|
</pre>
|
|
|
|
<p>This is a list of the components upon which this application relies
|
|
to build. Pay close attention to the hierarchical layout of the
|
|
<b>USE_GNOME</b> system; many components are implied from other
|
|
<b>USE_GNOME</b> directives. In the above example,
|
|
<tt>USE_GNOME= libgnomeui</tt> implies use of <tt>libbonoboui</tt>,
|
|
which implies <tt>libgnomecanvas</tt>, which implies
|
|
<tt>libglade2</tt>, which implies <tt>gtk20</tt>. Thus, even
|
|
though <tt>gtk+-2.0</tt> appears in the list of requisite
|
|
components, <tt>gtk20</tt> can be eliminated from the
|
|
<b>USE_GNOME</b> list. There are a number of other such
|
|
redundancies that can be eliminated from this list.</p>
|
|
|
|
<p>For the above list (taken from <tt>sysutils/gok</tt>), the
|
|
following is defined in the <tt>Makefile</tt>:
|
|
|
|
<pre>
|
|
USE_GNOME= gnomehack gnomeprefix libgnomeui atspi libwnck
|
|
</pre>
|
|
|
|
<h2>GNOME 1 Desktop vs. GNOME 2 Desktop</h2>
|
|
|
|
<p>In the beginning, there was only <tt>GNOME 1</tt>. When the
|
|
<tt>GNOME 2</tt> desktop came around, maximum backwards compatability
|
|
was ensured, within reason. <tt>GNOME 1</tt> applications can run
|
|
fine under the <tt>GNOME 2</tt> desktop, provided that the
|
|
applications do not utilize functionality specific to the
|
|
<tt>GNOME 1</tt> desktop environment.</p>
|
|
|
|
<p>The <tt>GNOME 1</tt> desktop, and all applications that will not
|
|
run under the <tt>GNOME 2</tt> desktop, have been removed from the
|
|
ports tree.</p>
|
|
|
|
<p>What this means for you, as an application porter, is simply that
|
|
you should not add <tt>GNOME 1</tt>-specific applications to the
|
|
ports tree.</p>
|
|
|
|
<p>If you wish to determine which version of the GNOME desktop
|
|
environment is present on a user's machine, you can check the value
|
|
of <b>GNOME_DESKTOP_VERSION</b>. This variable is set to either
|
|
<tt>"1"</tt> or <tt>"2"</tt> depending upon whether the
|
|
<tt>GNOME 1</tt> or <tt>GNOME 2</tt> desktop is installed.</p>
|
|
|
|
<h2>Optional GNOME Dependencies</h2>
|
|
|
|
<p>If your port can optionally use GNOME, you must set
|
|
<tt>WANT_GNOME= yes</tt> in your Makefile, then check to see if
|
|
<tt>HAVE_GNOME</tt> is set for each component from the list
|
|
above that your port can use. Since this is a conditional
|
|
evaluation, you need to stick it between <tt>bsd.port.pre.mk</tt>
|
|
and <tt>bsd.port.post.mk</tt>. For example:</p>
|
|
|
|
<pre>
|
|
WANT_GNOME= yes
|
|
|
|
.include <bsd.port.pre.mk>
|
|
|
|
.if ${HAVE_GNOME:Mgnomepanel}!=""
|
|
USE_GNOME+= gnomeprefix gnomepanel
|
|
CONFIGURE_ARGS+= --with-gnome
|
|
PKGNAMESUFFIX= -gnome
|
|
PLIST_SUB= DATADIR="share/gnome"
|
|
.else
|
|
CONFIGURE_ARGS+= --without-gnome
|
|
PLIST_SUB= DATADIR="share"
|
|
.endif
|
|
|
|
.include <bsd.port.post.mk>
|
|
</pre>
|
|
|
|
<p>Here, <tt>WANT_GNOME</tt> tells the ports system
|
|
to check for the existence of the various GNOME components
|
|
listed above. For each component found, its name is appended
|
|
to <tt>HAVE_GNOME</tt>. Since this port can use
|
|
<tt>gnomepanel</tt>, we check <tt>HAVE_GNOME</tt> to see if it
|
|
contains <tt>gnomepanel</tt> (for more on the :M<tt>pattern</tt>
|
|
make syntax, please refer to the
|
|
<a href="http://www.FreeBSD.org/cgi/man.cgi?query=make&apropos=0&sektion=0&manpath=FreeBSD+4.6-stable&format=html">make(1)</a> manpage).
|
|
If <tt>gnomepanel</tt> is found, then it is added the list of
|
|
<tt>USE_GNOME</tt> dependencies, and the port-specific
|
|
<tt>--with-gnome</tt> <tt>CONFIGURE_ARG</tt> is passed.
|
|
In an old GNOME infrastructure, <tt>PKGNAMESUFFIX</tt> was
|
|
automatically adjusted by the proper <tt>USE_*</tt> macro.
|
|
Now it is up to the individual porter to do this.
|
|
Our example port appends <tt>-gnome</tt> to the port name
|
|
to indicate it has been built with GNOME support. The same is
|
|
true for the <tt>DATADIR</tt> <tt>PLIST_SUB</tt>. The
|
|
individual porter must decide when do the <tt>DATADIR</tt>
|
|
substitution. A good rule of thumb is to add the <tt>DATADIR</tt>
|
|
<tt>PLIST_SUB</tt> when using the <tt>gnomeprefix</tt>
|
|
component.
|
|
</p>
|
|
|
|
<p><b>Note:</b> You cannot add extra default <tt>USE_GNOME</tt>
|
|
components after the <tt>.include <bsd.port.pre.mk></tt>.
|
|
That is, the following is <font color="#FF0000"><b>wrong</b>
|
|
</font>:</p>
|
|
|
|
<pre>
|
|
.include <bsd.port.pre.mk>
|
|
|
|
.if ${HAVE_GNOME:Mgnomelibs}!=""
|
|
USE_GNOME+= libgnome
|
|
.else
|
|
USE_GNOME+= gtk12 # WRONG!
|
|
.endif
|
|
</pre>
|
|
|
|
<p>This will make the build system think that GNOME <em>is</em>
|
|
desired, and mark the <tt>pkg-plist</tt> accordingly, thus
|
|
breaking package builds. If you need to add default
|
|
<tt>USE_GNOME</tt> components, do so <b>above</b> the
|
|
<tt> .include <bsd.port.pre.mk></tt> line.
|
|
</p>
|
|
|
|
<p>To enforce use of optional GNOME dependencies unconditionally,
|
|
you can add <tt>WITH_GNOME= yes</tt> to <tt>/etc/make.conf</tt>
|
|
or on the make command line. This will always return
|
|
true when checking for optional GNOME dependencies. If you
|
|
want the system to always return false when checking for optional
|
|
GNOME dependencies, you can add <tt>WITHOUT_GNOME= yes</tt>
|
|
to <tt>/etc/make.conf</tt> or to the make command line.
|
|
</p>
|
|
|
|
<p>More information on the USE_GNOME infrastructure can be found
|
|
by looking at the source and comments of
|
|
<tt>${PORTSDIR}/Mk/bsd.gnome.mk</tt>.</p>
|
|
|
|
<!-- End GNOME-related Makefile macros -->
|
|
|
|
<!-- Begin GNOME OMF -->
|
|
<a name="omf"></a>
|
|
<h2>OMF Installation</h2>
|
|
|
|
<p>A large number of GNOME applications (especially GNOME 2
|
|
applications) install Open Source Metadata Framework (OMF)
|
|
files which contain the help file information for those
|
|
applications. These OMF files require special processing
|
|
by ScrollKeeper in order for applications like Yelp to
|
|
find help documentation. In order to accomplish proper
|
|
registry of these OMF files when installing GNOME applications
|
|
from packages, you should make sure your <tt>Makefile</tt> has
|
|
this defined:</p>
|
|
|
|
<pre>
|
|
INSTALLS_OMF=yes
|
|
</pre>
|
|
<!-- End GNOME OMF -->
|
|
|
|
<!-- Begin GConf schemas -->
|
|
<h2>GConf Schema Installation</h2>
|
|
|
|
<p>GConf is the XML-based database that virtually all GNOME
|
|
applications use for storing their settings. This
|
|
database is defined by installed schema files that are
|
|
used to generate <tt>%gconf.xml</tt> key files. Previously,
|
|
these schema files and <tt>%gconf.xml</tt> key files were
|
|
listed in the port's <tt>pkg-plist</tt>. Since this proved
|
|
to be problematic, handling of GConf schemas was changed to
|
|
something similar to that of <a href="http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/porting-manpages.html">MAN<i>n</i></a>
|
|
files. That is, for each schema file installed by your port,
|
|
you must have the following listed in the <tt>Makefile</tt>:</p>
|
|
|
|
<pre>
|
|
GCONF_SCHEMAS= my_app.schemas my_app2.schemas my_app3.schemas
|
|
</pre>
|
|
|
|
<p>For example in <tt>audio/gnomemedia2</tt>:</p>
|
|
|
|
<pre>
|
|
GCONF_SCHEMAS= CDDB-Slave2.schemas gnome-audio-profiles.schemas \
|
|
gnome-cd.schemas gnome-sound-recorder.schemas
|
|
</pre>
|
|
|
|
<p>The schema files and <tt>%gconf.xml</tt> key files should
|
|
not be in the <tt>pkg-plist</tt>. If you notice that the
|
|
port doesn't has any <tt>%gconf.xml</tt> key files, but
|
|
has schema files then you should not be use
|
|
<tt>GCONF_SCHEMAS</tt>. It means, this port has broke
|
|
either schema files or installtion of GConf.</p>
|
|
<!-- End GConf schemas -->
|
|
|
|
<!-- Begin Shared MIME database -->
|
|
<h2>Shared MIME database</h2>
|
|
|
|
<p>If your port install files like <tt>application/x-portname.xml</tt>
|
|
in <tt>share/mime</tt>, you have to add these two lines at the
|
|
end of the <tt>pkg-plist</tt>:</p>
|
|
|
|
<pre>
|
|
@exec update-mime-database %D/share/mime
|
|
@unexec update-mime-database %D/share/mime
|
|
</pre>
|
|
|
|
<p>Also make sure <tt>shared-mime-info</tt> is among the dependencies
|
|
of your port. If your port use <tt>gtk20</tt>, you will have
|
|
<tt>shared-mime-info</tt> indirectly. You can check indirect
|
|
dependencies with <tt>make describe</tt>.</p>
|
|
|
|
<p>Example port to look at: <a href="http://www.freebsd.org/cgi/cvsweb.cgi/ports/deskutils/drivel/"><tt>deskutils/drivel</tt></a></p>
|
|
<!-- End Shared MIME database -->
|
|
|
|
<!-- Begin Desktop database -->
|
|
<h2>Desktop database</h2>
|
|
|
|
<p>Some ports provide MIME definitions in their <tt>.desktop</tt>
|
|
files. If your port install <tt>.desktop</tt> file into
|
|
<tt>share/gnome/applications</tt> and there is a line starting
|
|
with <tt>MimeType</tt> in it, you need to update desktop
|
|
database after install and deinstall. This database is represented
|
|
by <tt>share/gnome/applications/mimeinfo.cache</tt> file. Add
|
|
dependency on GNOME component <tt>desktopfileutils</tt> and
|
|
these lines to the end of <tt>pkg-plist</tt>:</p>
|
|
|
|
<pre>
|
|
@exec update-desktop-database > /dev/null || /usr/bin/true
|
|
@unexec update-desktop-database > /dev/null || /usr/bin/true
|
|
</pre>
|
|
|
|
<p>Also add following to the <tt>post-install</tt> target in port's
|
|
Makefile:</p>
|
|
|
|
<pre>
|
|
-@update-desktop-database
|
|
</pre>
|
|
|
|
<p>Example port to look at: <a href="http://www.freebsd.org/cgi/cvsweb.cgi/ports/editors/leafpad/"><tt>editors/leafpad</tt></a></p>
|
|
<!-- End Desktop database -->
|
|
|
|
<!-- Begin GNOME libtool -->
|
|
<a name="libtool"></a>
|
|
<h2>Libtool Issues</h2>
|
|
|
|
<p>Most, if not all, GNOME applications depend on GNU's libtool.
|
|
They also use the GNU configure system. If your port installs
|
|
shared libraries, and includes an <tt>ltmain.sh</tt> script
|
|
in its <tt>${WRKSRC}</tt> directory, you should add
|
|
<tt>USE_LIBTOOL_VER=15</tt> to your port's Makefile.
|
|
However, if your port uses custom <tt>LIBTOOLFLAGS</tt>, you
|
|
must use <tt>USE_INC_LIBTOOL_VER=13</tt> instead. If you have
|
|
to use <tt>USE_INC_LIBTOOL_VER</tt>, you must also add
|
|
<tt>lthack</tt> to <tt>USE_GNOME</tt>. In general, though,
|
|
<tt>lthack</tt> is deprecated, and should only be used if
|
|
absolutely necessary.</p>
|
|
<!-- End GNOME libtool -->
|
|
|
|
<!-- Begin GNOME distfiles -->
|
|
<h2>Distfiles</h2>
|
|
|
|
<p>To separate GNOME 2 distfiles from the GNOME 1 distfiles, and to
|
|
keep the distfiles directory clean, GNOME 1 ports that
|
|
download their distfiles from <tt>${MASTER_SITE_GNOME}</tt> must
|
|
add the following to their
|
|
Makefile:</p>
|
|
|
|
<pre>
|
|
DIST_SUBDIR= gnome
|
|
</pre>
|
|
|
|
<p>GNOME 2 ports that download their distfiles from
|
|
<tt>${MASTER_SITE_GNOME}</tt> must include the following in their
|
|
Makefile:</p>
|
|
|
|
<pre>
|
|
DIST_SUBDIR= gnome2
|
|
</pre>
|
|
|
|
<p>Some GNOME distfiles come in both tar gzip as well as tar bzip2
|
|
format. To save time when downloading distfiles over slow links,
|
|
you should use the bzip2 distfiles whenever possible. To do this,
|
|
add the following to your port's Makefile:</p>
|
|
|
|
<pre>
|
|
USE_BZIP2= yes
|
|
</pre>
|
|
|
|
<!-- End GNOME distfiles -->
|
|
|
|
|
|
<p>If you still need help with your port, have a look at some of
|
|
the <a href="/ports/gnome.html">existing ports</a> for examples.
|
|
The <a href="mailto:&email;@FreeBSD.org">freebsd-gnome mailing
|
|
list</a> is also there for you.</p>
|
|
|
|
&footer;
|
|
</body>
|
|
</html>
|