Update the porting guide to include info on the new GNOMENG infrastructure.

This commit is contained in:
Joe Marcus Clarke 2002-08-21 18:50:38 +00:00
parent 6290fef206
commit bc951c7221
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/www/; revision=13969

View file

@ -1,16 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY base CDATA "../..">
<!ENTITY date "$FreeBSD: www/en/gnome/docs/porting.sgml,v 1.18 2002/04/16 15:53:52 marcus Exp $">
<!ENTITY date "$FreeBSD: www/en/gnome/docs/porting.sgml,v 1.19 2002/07/05 06:31:40 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;
<h1><font color="#FF0000">Note, this document is out-of-date. A new
porting process is in the works, and this document will be updated
when it is formalized.</font></h1>
<table border="0">
<tr>
<td>
@ -19,73 +15,198 @@
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>For ports that <i>require</i> GNOME, you should define the following
in your port's Makefile:</p>
<p>Recently, the GNOME porting infrastructure has undergone 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 the
applications using the old infrastructure over to GNOMENG.
Currently, all of the GNOME 1 desktop and the GNOME Fifth Toe
have been ported.</p>
<pre>
USE_GNOME= yes
<p>The majority of this section applies to GNOME 1 ports.
GNOME 2 ports still have not bee fully brought under GNOMENG.
For those ports, simply listing out the BUILD, RUN, and LIB
DEPENDS is sufficient for the time being.</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. In GNOMENG, the way the specify
which GNOME components your port requires is to add the
following to your port's Makefile:</p>
<pre>
USE_X_PREFIX= yes
</pre>
USE_GNOMENG= yes
USE_GNOME= &lt;list of GNOME components&gt;
</pre>
<p>These will take care of the install prefix and requiring all the
core GNOME dependencies. If your port can use GNOME, but it isn't
required, you can define the following in your Makefile:</p>
<p>The list of GNOME components consists of one or more of
the following separated by a single space:</p>
<pre>
WANT_GNOME= yes
</pre>
<p>If the ports system detects GNOME installed on the system
then GNOME components will be built. Other useful GNOME-related
macros that can be define in your port's Makefile include:</p>
<!-- Begin GNOME-related Makefile macros -->
<!-- Begin GNOMENG components list -->
<ul>
<li><p><tt>USE_GLIB (WANT_GLIB)</tt> : The application requires
(can use) Glib. Defining <tt>USE_GNOME</tt> or <tt>USE_GTK</tt>
takes care of this option automatically.</p></li>
<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>USE_GTK (WANT_GTK)</tt> : The application may not be
GNOME-compliant, but requires GTK+ widgets. This will take care of
those dependencies. Note, this option should <b>not</b> be defined
if <tt>USE_GNOME</tt> is defined.</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>USE_ESOUND (WANT_ESOUND)</tt> : The application requires
(can use) esound. Normally, esound support is added by specifying
<tt>USE_GNOME</tt>.</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>USE_IMLIB (WANT_IMLIB)</tt> : The application requires
(can use) the Imlib image library. This is not needed if
<tt>USE_GNOME</tt> is defined.</p></li>
<li><p><tt>gnomeaudio</tt> : This adds a dependency on
<tt>audio/gnomeaudio</tt>.</p></li>
<li><p><tt>USE_GNOMELIBS (WANT_GNOMELIBS)</tt> : The application
requires (can use) GNOME libraries. This does not import as many
dependencies as <tt>USE_GNOME</tt> and should be used for
applications that use GNOME, but do not need the GNOME Control
Center, the GNOME capplet library, or anything from the GNOME
Core.</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>USE_GNOMECTRL (WANT_GNOMECTRL)</tt> : The application
requires (can use) all the GNOME libraries and the GNOME Control
Center, but does not use anything from GNOME Core. This option is
usually used for backend APIs.</p></li>
</ul>
<li><p><tt>libghttp</tt> : This adds a dependency on
<tt>www/libghttp</tt>.</p></li>
<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. 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>
<li><p><tt>glib12</tt> : This adds a dependency on
<tt>devel/glib12</tt> (replaces <tt>USE_GLIB</tt>).</p></li>
<pre>
<li><p><tt>gtk12</tt> : This adds a dependency on
<tt>x11-toolkits/gtk12</tt> (replaces <tt>USE_GTK</tt>).</p></li>
<li><p><tt>libxml</tt> : This adds a dependency on
<tt>textproc/libxml</tt>.</p></li>
<li><p><tt>gdkpixbuf</tt> : This adds a dependency on
<tt>graphics/gdk-pixbuf</tt>.</p></li>
<li><p><tt>imlib</tt> : This adds a dependency on
<tt>graphics/imlib</tt> (replaces <tt>USE_IMLIB</tt>).</p></li>
<li><p><tt>orbit</tt> : This adds a dependency on
<tt>devel/ORBit</tt>.</p></li>
<li><p><tt>gnomelibs</tt> : This adds a dependency on
<tt>x11/gnomelibs</tt> (replaces <tt>USE_GNOMELIBS</tt>).</p></li>
<li><p><tt>gnomecanvas</tt> : This adds a dependency on
<tt>graphics/gnomecanvas</tt>.</p></li>
<li><p><tt>oaf</tt> : This adds a dependency on
<tt>devel/oaf</tt>.</p></li>
<li><p><tt>gnomemimedata</tt> : This adds a dependency on
<tt>misc/gnomemimedata</tt>.</p></li>
<li><p><tt>gconf</tt> : This adds a dependency on
<tt>devel/gconf</tt>.</p></li>
<li><p><tt>gnomevfs</tt> : This adds a dependency on
<tt>devel/gnomevfs</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.</p></li>
<li><p><tt>gnomeprint</tt> : This adds a dependency on
<tt>print/gnomeprint</tt>.</p></li>
<li><p><tt>bonobo</tt> : This adds a dependency on
<tt>devel/bonobo</tt>.</p></li>
<li><p><tt>libgda</tt> : This adds a dependency on
<tt>databases/libgda</tt>.</p></li>
<li><p><tt>gnomedb</tt> : This adds a dependency on
<tt>databases/gnomedb</tt>.</p></li>
<li><p><tt>libglade</tt> : This adds a dependency on
<tt>devel/libglade</tt>.</p></li>
<li><p><tt>gal</tt> : This adds a dependency on
<tt>x11-toolkits/gal</tt>.</p></li>
<li><p><tt>glibwww</tt> : This adds a dependency on
<tt>www/glibwww</tt>.</p></li>
<li><p><tt>gtkhtml</tt> : This adds a dependency on
<tt>www/gtkhtml</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>
that 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.</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 gnomehack to
remove some common Makefile Linuxisms. Since it uses gnomehack,
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 gnomehack 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 &lt;bsd.port.pre.mk&gt;
.if defined(HAVE_GNOME)
USE_GNOME= yes
.if ${HAVE_GNOME:Mlibpanel}!=""
USE_GNOME+= libpanel
CONFIGURE_ARGS+= --with-gnome
PKGNAMESUFFIX= -gnome
.else
CONFIGURE_ARGS+= --without-gnome
.endif
@ -93,120 +214,79 @@ CONFIGURE_ARGS+= --without-gnome
.include &lt;bsd.port.post.mk&gt;
</pre>
<p>What happens here is <tt>WANT_GNOME</tt> tells the ports system
to check for the existence of <tt>gnome-config</tt>. If it
exists, <tt>HAVE_GNOME</tt> is set. If not, <tt>HAVE_GNOME</tt>
remains unset. By setting <tt>USE_GNOME</tt> after checking for
<tt>HAVE_GNOME</tt> the port will register all the GNOME
dependencies properly.</p>
<p>What happens here is <tt>WANT_GNOME</tt> tells the ports system
to check for the existence of the various GNOME components
listed above. For each component found, <tt>HAVE_GNOME</tt>
is updated with the name of component. Since this port
specifically 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
<a href="http://www.freebsd.org/cgi/man.cgi?query=make&amp;apropos=0&amp;sektion=0&amp;manpath=FreeBSD+4.6-stable&amp;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.
</p>
<p>When building GNOME ports, remember that many applications
require shared directories in <tt>${PREFIX}/share/gnome</tt>. Ports
should be constructed in a way such that files placed in these
directories are removed before the package which created the
directories (i.e. the package that has an appropriate
<tt>@dirrm</tt> in its pkg-plist). For GNOME, the principle
parent port is <tt>gnomecore</tt>. If your port incudes
<tt>USE_GNOME= yes</tt> you should be fine. If you're
uncertain if you need to require any other packages, you can use
the script <tt>${PORTSDIR}/Tools/scripts/gnomedepends.py</tt>
to examine your port's pkg-plist:</p>
<p>To enforce use of optional GNOME dependencies no matter what,
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>
<pre>
# cd /usr/ports/x11/mygnomeport
# /usr/ports/Tools/scripts/gnomedepends.py
According to the contents of pkg-plist the port depends on the following GNOME
port(s):
<p>Once you have finished with your port, it is a good idea to
verify 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>
/usr/ports/mail/gmail, for directories:
share/gnome/help
share/gnome/apps
share/gnome
/usr/ports/sysutils/gnomecontrolcenter, for directories:
share/gnome/apps/Settings
share/gnome/apps
/usr/ports/textproc/scrollkeeper, for directories:
share/gnome/omf
share/gnome
/usr/ports/x11/gnomecore, for directories:
share/gnome/apps/System
/usr/ports/x11/gnomelibs, for directories:
share/gnome/pixmaps
share/gnome/help
</pre>
<p>To see a list of what packages your port will actually require,
use the command <tt>make package-depends</tt>.</p>
<p>More information on GNOMENG can be found my looking at the source
and comments of <tt>${PORTSDIR}/Mk/bsd.gnomeng.mk</tt>.</p>
<!-- End GNOME-related Makefile macros -->
<!-- Begine GNOME I18N -->
<h2>GNOME Internationalization</h2>
<p>GNOME relies on the <tt>gettext</tt> port to do
internationalization (I18N). FreeBSD currently supports two
versions of <tt>gettext</tt>: 0.10.35 and 0.11.1. Most ports can
use 0.11.1. However, if, when compiling your port, you get an
error building the .po translation files need to use the older
version of <tt>gettext</tt>.</p>
<p>To use the older <tt>gettext</tt>, add the following to your
port's Makefile:</p>
<pre>
BUILD_DEPENDS= msgfmt-old:${PORTSDIR}/devel/gettext-old
CONFIGURE_ENV+= MSGFMT=${LOCALBASE}/bin/msgfmt-old \
XGETTEXT=${LOCALBASE}/bin/xgettext-old
</pre>
<p>When installing GNOME applications, make sure the translation
files are put in <tt>/usr/X11R6/share/locale</tt> and
not <tt>/usr/X11R6/share/gnome/locale</tt>. To do this, add the
following to your port's Makefile's <tt>pre-patch:</tt> section:</p>
<pre>
pre-patch:
@find ${WRKSRC} -name "Makefile.in*" | xargs ${PERL} -pi -e \
's|\$\(datadir\)/gnome/|\$\(datadir\)/|g ; \
s|\$\(datadir\)/locale|\$\(prefix\)/share/locale|g'
</pre>
<p>Also, make sure the translation files are installed as .mo files and
not .gmo files. To do this, you can generally use this
<a href="../patches/patch-po::Makefile.in.in">patch</a>.</p>
<!-- End GNOME I18N -->
<!-- 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. Newer versions of libtool have
a problem with FreeBSD's <tt>USE_LIBTOOL</tt> macro. Use of this
macro should be avoided. Instead, set <tt>GNU_CONFIGURE= yes</tt>,
and use the following <a href="../patches/patch-ltmain.sh">patch</a>.
This patch prevents the installation of .la files, prevents
the building and installation of static archive libraries, and
ensures that -pthread will be passed to the linker.</p>
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 ${PTHREAD_LIBS} will be passed to the linker.</p>
<!-- End GNOME libtool -->
<!-- Begin GNOME distfiles -->
<h2>Distfiles</h2>
<p>As GNOME 2.0 gains developer momentum, things must be done to sort
out the new GNOME 2.0 distfiles from the GNOME 1.0 distfiles, as well
as do our part to keep the distfiles directory clean. To do
this, GNOME 1.0 ports that download their distfiles from
<tt>${MASTER_SITE_GNOME}</tt> must add the following to their
<p>Things must be done to sort out the new GNOME 2 distfiles from
the GNOME 1 distfiles, as well as do our part to keep the
distfiles directory clean. To do this, GNOME 1 ports that
download their distfiles from <tt>${MASTER_SITE_GNOME}</tt> must
add the following to their
Makefile:</p>
<pre>
<pre>
DIST_SUBDIR= gnome
</pre>
</pre>
<p>GNOME 2.0 ports that download their distfiles from
<p>GNOME 2 ports that download their distfiles from
<tt>${MASTER_SITE_GNOME}</tt> must include the following in their
Makefile:</p>
@ -227,9 +307,9 @@ USE_BZIP2= yes
<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>
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>