<!DOCTYPE HTML PUBLIC "-//FreeBSD//DTD HTML 4.01 Transitional-Based Extension//EN" [
<!ENTITY base CDATA "../..">
<!ENTITY date "$FreeBSD$">
<!ENTITY title "FreeBSD GNOME Project: How To Make a Port">
<!ENTITY email "freebsd-gnome">
<!ENTITY % navinclude.gnome "INCLUDE">
]>
<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_XLIB=	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_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_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 compatibility
	  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 &lt;bsd.port.pre.mk&gt;

.if ${HAVE_GNOME:Mgnomepanel}!=""
	USE_GNOME+=	gnomeprefix gnomepanel
	CONFIGURE_ARGS+=	--with-gnome
	PKGNAMESUFFIX=	-gnome
.else
	CONFIGURE_ARGS+=	--without-gnome
.endif

.include &lt;bsd.port.post.mk&gt;
          </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&amp;apropos=0&amp;sektion=0&amp;manpath=FreeBSD+4.6-stable&amp;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 &lt;bsd.port.pre.mk&gt;</tt>.
	    That is, the following is <font color="#FF0000"><b>wrong</b>
	    </font>:</p>

	  <pre>
.include &lt;bsd.port.pre.mk&gt;

.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 &lt;bsd.port.pre.mk&gt;</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 PREFIX -->
	  <a name="prefix"></a>
	  <h2>GNOME PREFIX</h2>

	  <p>Since the release of 2.16, GNOME now lives in
	    <tt>LOCALBASE</tt> instead of <tt>X11BASE</tt>.  To make
	    it easier for GNOME ports that must also be installed into
	    the same PREFIX as GNOME, a hack has been added to
	    <tt>bsd.gnome.mk</tt> to force the PREFIX to
	    <tt>LOCALBASE</tt> whenever the <tt>gnomeprefix</tt>
	    component is used.  This can be overridden by manually
	    specifying <tt>PREFIX</tt> in your port's
	    <tt>Makefile</tt> or on the command line.</p>
<!-- End GNOME PREFIX -->

<!-- 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 that <tt>omf</tt> files are
	    listed in <tt>pkg-plist</tt> and that 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/gnome-media</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 installation 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 %%LOCALBASE%%/bin/update-mime-database %D/share/mime
@unexec %%LOCALBASE%%/bin/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/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/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 %%LOCALBASE%%/bin/update-desktop-database > /dev/null || /usr/bin/true
@unexec %%LOCALBASE%%/bin/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_AUTOTOOLS=libtool:15</tt> to your port's Makefile.
	    However, if your port uses custom <tt>LIBTOOLFLAGS</tt>, you
	    must use <tt>USE_AUTOTOOLS=libtool:13:inc</tt> instead. If you have
	    to use <tt>libtool:X:inc</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>
