f1e5f71e41
* Fix spelling nits * Promote consistant use of <tt> tags * Re-word those things that in their current state may to some appear in some ways as possibly overly wordy * Note the applicability of some GNOMENG options for GNOME 2 ports * Move the discussion of the deprecated USE_* macros from the top to the bottom Approved by: pat
381 lines
15 KiB
Text
381 lines
15 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.24 2002/09/19 21:45:36 marcus 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;
|
|
<table border="0">
|
|
<tr>
|
|
<td>
|
|
<p>This document assumes that you already know how 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>GNOME Makefile Macros</h2>
|
|
<p>Recently, the GNOME porting infrastructure underwent some
|
|
changes so that GNOME 1 applications can coexist with the GNOME
|
|
2 desktop and vice versa. This new infrastructure is called
|
|
<b>GNOMENG</b>. The GNOME team is working to port
|
|
applications using the old infrastructure over to GNOMENG.
|
|
Nearly every GNOME 1 port has been converted.</p>
|
|
|
|
<p>The majority of this section applies to GNOME 1 ports.
|
|
GNOME 2 ports still have not been fully brought under GNOMENG.
|
|
For those ports, simply listing out the <tt>BUILD_</tt>,
|
|
<tt>RUN_</tt>, and <tt>LIB_</tt> <tt>DEPENDS</tt> is sufficient
|
|
for the time being. GNOME 2 ports can still benefit from certain
|
|
GNOMENG options, such as <tt>gnomehack</tt>, <tt>gnomeprefix</tt>,
|
|
and <tt>gnomehier</tt>.</p>
|
|
|
|
<p>In GNOMENG, the list of GNOME components your port requires
|
|
is added to your port's Makefile:</p>
|
|
|
|
<pre>
|
|
USE_X_PREFIX= yes
|
|
USE_GNOMENG= yes
|
|
USE_GNOME= <list of GNOME components>
|
|
</pre>
|
|
|
|
<p>The list of GNOME components consists of one or more of
|
|
the following, each separated by a single space:</p>
|
|
|
|
<!-- Begin GNOMENG components list -->
|
|
<ul>
|
|
<li><p><tt>gnomehack</tt> : This is a collection of common
|
|
GNOME Makefile substitutions that is almost required for
|
|
every GNOME port to fit into the proper mtree structure.
|
|
For a specific list, please refer to
|
|
<tt>${PORTSDIR}/Mk/bsd.gnomeng.mk</tt>. <b>Note:</b>
|
|
Including this option adds a <tt>pre-patch</tt> target to
|
|
your Makefile. Therefore, if you already have a
|
|
<tt>pre-patch</tt> target in your Makefile, you must
|
|
change it to <tt>post-patch</tt>.</p></li>
|
|
|
|
<li><p><tt>gnomeprefix</tt> : This is a collection of
|
|
<tt>CONFIGURE_ARGS</tt> needed for every GNOME port that
|
|
has to have its data placed under the GNOME hierarchy. It
|
|
also includes some useful arguments that allow GNOME ports
|
|
to build in the presence of gtk-doc, and maintain
|
|
<tt>PREFIX</tt> safety.</p></li>
|
|
|
|
<li><p><tt>gnomehier</tt> : This adds a dependency on
|
|
<tt>misc/gnomehier</tt>. <tt>gnomehier</tt> installs all the
|
|
directories needed for both the GNOME 1 and 2 desktops. Only
|
|
include this option if your port calls <tt>@dirrm</tt> on
|
|
one of the directories listed in the plist for
|
|
<tt>gnomehier</tt>.</p></li>
|
|
|
|
<li><p><tt>gnomeaudio</tt> : This adds a dependency on
|
|
<tt>audio/gnomeaudio</tt>.</p></li>
|
|
|
|
<li><p><tt>esound</tt> : This adds a dependency on
|
|
<tt>audio/esound</tt> (replaces <tt>USE_ESOUND</tt>).</p></li>
|
|
|
|
<li><p><tt>libghttp</tt> : This adds a dependency on
|
|
<tt>www/libghttp</tt>.</p></li>
|
|
|
|
<li><p><tt>glib12</tt> : This adds a dependency on
|
|
<tt>devel/glib12</tt> (replaces <tt>USE_GLIB</tt>).</p></li>
|
|
|
|
<li><p><tt>gtk12</tt> : This adds a dependency on
|
|
<tt>x11-toolkits/gtk12</tt> (replaces <tt>USE_GTK</tt>).<br>
|
|
<i>Implies</i>: <tt>glib12</tt></p></li>
|
|
|
|
<li><p><tt>libxml</tt> : This adds a dependency on
|
|
<tt>textproc/libxml</tt>.<br>
|
|
<i>Implies</i>: <tt>glib12</tt></p></li>
|
|
|
|
<li><p><tt>gdkpixbuf</tt> : This adds a dependency on
|
|
<tt>graphics/gdk-pixbuf</tt>.<br>
|
|
<i>Implies</i>: <tt>gtk12</tt></p></li>
|
|
|
|
<li><p><tt>imlib</tt> : This adds a dependency on
|
|
<tt>graphics/imlib</tt> (replaces <tt>USE_IMLIB</tt>).<br>
|
|
<i>Implies</i>: <tt>gtk12</tt></p></li>
|
|
|
|
<li><p><tt>orbit</tt> : This adds a dependency on
|
|
<tt>devel/ORBit</tt>.<br>
|
|
<i>Implies</i>: <tt>glib12</tt></p></li>
|
|
|
|
<li><p><tt>gnomelibs</tt> : This adds a dependency on
|
|
<tt>x11/gnomelibs</tt> (replaces <tt>USE_GNOMELIBS</tt>).<br>
|
|
<i>Implies</i>: <tt>esound</tt> <tt>imlib</tt> <tt>libxml</tt>
|
|
<tt>orbit</tt></p></li>
|
|
|
|
<li><p><tt>gnomecanvas</tt> : This adds a dependency on
|
|
<tt>graphics/gnomecanvas</tt>.<br>
|
|
<i>Implies</i>: <tt>gnomelibs</tt> <tt>gdkpixbuf</tt></p></li>
|
|
|
|
<li><p><tt>oaf</tt> : This adds a dependency on
|
|
<tt>devel/oaf</tt>.<br>
|
|
<i>Implies</i>: <tt>orbit</tt> <tt>libxml</tt></p></li>
|
|
|
|
<li><p><tt>gnomemimedata</tt> : This adds a dependency on
|
|
<tt>misc/gnomemimedata</tt>.<br>
|
|
<i>Implies</i>: <tt>gnomehier</tt></p></li>
|
|
|
|
<li><p><tt>gconf</tt> : This adds a dependency on
|
|
<tt>devel/gconf</tt>.<br>
|
|
<i>Implies</i>: <tt>oaf</tt></p></li>
|
|
|
|
<li><p><tt>gnomevfs</tt> : This adds a dependency on
|
|
<tt>devel/gnomevfs</tt>.<br>
|
|
<i>Implies</i>: <tt>gnomemimedata</tt> <tt>gconf</tt>
|
|
<tt>gnomelibs</tt></p></li>
|
|
|
|
<li><p><tt>libcapplet</tt> : This adds a dependency on
|
|
<tt>x11/libcapplet</tt> (replaces <tt>USE_GNOMECTRL</tt>).
|
|
If your port installs a configuration applet (or capplet),
|
|
you must include this option.<br>
|
|
<i>Implies</i>: <tt>gnomelibs</tt></p></li>
|
|
|
|
<li><p><tt>gnomeprint</tt> : This adds a dependency on
|
|
<tt>print/gnomeprint</tt>.<br>
|
|
<i>Implies</i>: <tt>gnomelibs</tt> <tt>gnomecanvas</tt></p></li>
|
|
|
|
<li><p><tt>bonobo</tt> : This adds a dependency on
|
|
<tt>devel/bonobo</tt>.<br>
|
|
<i>Implies</i>: <tt>oaf</tt> <tt>gnomeprint</tt></p></li>
|
|
|
|
<li><p><tt>libgda</tt> : This adds a dependency on
|
|
<tt>databases/libgda</tt>.<br>
|
|
<i>Implies</i>: <tt>gconf</tt> <tt>bonobo</tt></p></li>
|
|
|
|
<li><p><tt>gnomedb</tt> : This adds a dependency on
|
|
<tt>databases/gnomedb</tt>.<br>
|
|
<i>Implies</i>: <tt>libgda</tt></p></li>
|
|
|
|
<li><p><tt>libglade</tt> : This adds a dependency on
|
|
<tt>devel/libglade</tt>.<br>
|
|
<i>Implies</i>: <tt>gnomedb</tt></p></li>
|
|
|
|
<li><p><tt>gal</tt> : This adds a dependency on
|
|
<tt>x11-toolkits/gal</tt>.<br>
|
|
<i>Implies</i>: <tt>libglade</tt></p></li>
|
|
|
|
<li><p><tt>glibwww</tt> : This adds a dependency on
|
|
<tt>www/glibwww</tt>.<br>
|
|
<i>Implies</i>: <tt>gnomelibs</tt></p></li>
|
|
|
|
<li><p><tt>gtkhtml</tt> : This adds a dependency on
|
|
<tt>www/gtkhtml</tt>.<br>
|
|
<i>Implies</i>: <tt>glibwww</tt> <tt>gal</tt> <tt>libghttp</tt>
|
|
<tt>libcapplet</tt></p></li>
|
|
|
|
<li><p><tt>libpanel</tt> : This adds a dependency on
|
|
<tt>x11/libpanel</tt>. Use this if your port installs
|
|
an applet that can be placed in the GNOME 1 panel. <b>Note:</b>
|
|
even though you can have GNOME 1 applets in a
|
|
GNOME 2 desktop environment, they will <b>not</b> work
|
|
with the GNOME 2 panel.<br>
|
|
<i>Implies</i>: <tt>gnomelibs</tt></p></li>
|
|
</ul>
|
|
|
|
<p>Let us take an example:</p>
|
|
|
|
<pre>
|
|
USE_X_PREFIX= yes
|
|
USE_GNOMENG= yes
|
|
USE_GNOME= gnomeprefix gnomehack gnomelibs bonobo libglade gal
|
|
|
|
post-patch:
|
|
@${REINPLACE_CMD} -e 's|-lpthread|${PTHREAD_LIBS}|g ; \
|
|
s|DATADIRNAME=lib|DATADIRNAME=share|g' ${WRKSRC}/configure
|
|
</pre>
|
|
|
|
<p>This port makes use of the new GNOMENG infrastructure. It
|
|
installs into the GNOME mtree, and uses the <tt>gnomehack</tt> to
|
|
remove some common Makefile Linuxisms. Since it uses <tt>gnomehack</tt>,
|
|
the <tt>pre-install</tt> target has been changed to a
|
|
<tt>post-install</tt> target. If this is not done, then the
|
|
<tt>pre-install</tt> target from <tt>gnomehack</tt> will be overwritten.
|
|
The port also requires gnomelibs, bonobo, libglade, and gal.
|
|
</p>
|
|
|
|
<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:Mlibpanel}!=""
|
|
USE_GNOME+= gnomeprefix libpanel
|
|
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>libpanel</tt>,
|
|
we check <tt>HAVE_GNOME</tt> to see if it contains
|
|
<tt>libpanel</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>libpanel</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 the old GNOME infrastructure, <tt>PKGNAMESUFFIX</tt> was
|
|
automatically adjusted by the proper <tt>USE_*</tt> macro.
|
|
In GNOMENG, 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>. In GNOMENG,
|
|
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+= gnomelibs
|
|
.else
|
|
USE_GNOME+= gtk12 # WRONG!
|
|
.endif
|
|
</pre>
|
|
|
|
<p>This will make GNOMENG 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 makes GNOMENG always return
|
|
true when checking for optional GNOME dependencies. If you
|
|
want GNOMENG 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>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>More information on GNOMENG can be found by looking at the source
|
|
and comments of <tt>${PORTSDIR}/Mk/bsd.gnomeng.mk</tt>.</p>
|
|
|
|
<p><b>Note:</b> GNOMENG is temporary. That is, it was put
|
|
in place so that ports could be gradually migrated from the old
|
|
infrastructure to the new one. Once all ports have been
|
|
migrated, the old porting infrastructure as well as the
|
|
<tt>USE_GNOMENG</tt> macro will be removed.</p>
|
|
|
|
<p>The old infrastructure used the following Makefile macros
|
|
for building GNOME or GTK+ ports:</p>
|
|
|
|
<pre>
|
|
USE_ESOUND
|
|
USE_GLIB
|
|
USE_GNOMECTRL
|
|
USE_GNOMELIBS
|
|
USE_GTK
|
|
USE_IMLIB
|
|
|
|
WANT_ESOUND
|
|
WANT_GLIB
|
|
WANT_GNOMECTRL
|
|
WANT_GNOMELIBS
|
|
WANT_GTK
|
|
WANT_IMLIB
|
|
</pre>
|
|
|
|
<p>These are now deprecated.</p>
|
|
<!-- End GNOME-related Makefile macros -->
|
|
|
|
<!-- 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>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
&footer;
|
|
</body>
|
|
</html>
|