5aa60996d6
Now there are three separate lists: GNOME 1 components, GNOME 2 components, and thingies that aren't in the other things with the stuff, like the hacks. This now mirrors the division present in bsd.gnome.mk in the development tree.
307 lines
12 KiB
Text
307 lines
12 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.35 2003/12/28 03:06:00 adamw 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 -->
|
|
<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 port's
|
|
<tt>pkg-plist</tt> has the following for <em>each</em> OMF file
|
|
listed.</p>
|
|
|
|
<pre>
|
|
@exec scrollkeeper-install -q \
|
|
%D/path/to/help_file.omf \
|
|
2>/dev/null || /usr/bin/true
|
|
@unexec scrollkeeper-uninstall -q \
|
|
%D/path/to/help_file.omf \
|
|
2>/dev/null || /usr/bin/true
|
|
</pre>
|
|
|
|
<p>For example:</p>
|
|
|
|
<pre>
|
|
@exec scrollkeeper-install -q \
|
|
%D/share/gnome/bug-buddy/bug-buddy-C.omf \
|
|
2>/dev/null || /usr/bin/true
|
|
@unexec scrollkeeper-uninstall -q \
|
|
%D/share/gnome/bug-buddy/bug-buddy-C.omf \
|
|
2>/dev/null || /usr/bin/true
|
|
</pre>
|
|
|
|
<!-- End GNOME OMF -->
|
|
|
|
<!-- Begin GNOME libtool -->
|
|
<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, you should add <tt>USE_LIBTOOL= yes</tt> to
|
|
your port's Makefile. This takes care of most of the libtool
|
|
requirements, but will not prevent things such as .la files
|
|
from being installed. To ensure a proper shared library
|
|
installation, also consider adding the following line to your
|
|
port's <tt>configure</tt> script directly below the line
|
|
<tt>LIBTOOL_DEPS="$ac_aux_dir/ltmain.sh"</tt>:</p>
|
|
|
|
<pre>
|
|
$ac_aux_dir/ltconfig $LIBTOOL_DEPS
|
|
</pre>
|
|
|
|
<p>This prevents the installation of .la files and
|
|
ensures that <tt>${PTHREAD_LIBS}</tt> will be passed to the
|
|
linker.</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>
|