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 FreeBSD Porter's Handbook.

GNOME Makefile Macros

GNOME applications under FreeBSD use the USE_GNOME 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:

USE_X_PREFIX=	yes
USE_GNOME=	gnomeprefix gnomehack libgnomeui
	  

The USE_GNOME components are divided into the following two lists:

• GNOME 2 components

• GNOME 1 components

If your port needs only GTK2 libraries, the following is the shortest way to define this:

USE_X_PREFIX=	yes
USE_GNOME=	gtk20
	  

If your port needs only GTK1 libraries, the following is the shortest way to define this:

USE_X_PREFIX=	yes
USE_GNOME=	gtk12
	  

Even if your application needs only the GTK libraries, other USE_GNOME components may be useful. Please scan the entire list to make sure your port uses all relevant components.

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 make package-depends from within your port's directory.

To aid in creating the list of necessary components, it can be helpful to examine the output of make configure. At the end of the checking for... list, there will be a line similar to this:

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

This is a list of the components upon which this application relies to build. Pay close attention to the hierarchical layout of the USE_GNOME system; many components are implied from other USE_GNOME directives. In the above example, USE_GNOME= libgnomeui implies use of libbonoboui, which implies libgnomecanvas, which implies libglade2, which implies gtk20. Thus, even though gtk+-2.0 appears in the list of requisite components, gtk20 can be eliminated from the USE_GNOME list. There are a number of other such redundancies that can be eliminated from this list.

For the above list (taken from sysutils/gok), the following is defined in the Makefile:

USE_GNOME=	gnomehack gnomeprefix libgnomeui atspi libwnck

GNOME 1 Desktop vs. GNOME 2 Desktop

Certain aspects of the GNOME 1 desktop environment are incompatible with certain aspects of the GNOME 2 desktop environment. To ensure that a user does not compile a GNOME 2 component against their GNOME 1 environment (or vice versa), the user may set GNOME_DESKTOP_VERSION in their /etc/make.conf. Even if a user has not explicitly set GNOME_DESKTOP_VERSION, the FreeBSD GNOME architecture will attempt to automatically deduce the desktop currently installed by examining which components are already installed.

If compilation of a GNOME 2 port is attempted on a GNOME_DESKTOP_VERSION=1 system, the compilation will immediately abort and the user will be informed of the incompatability.

If your application can handle both GNOME 1 and GNOME 2 compilation, you may check the value of GNOME_DESKTOP_VERSION to determine for which desktop your port is compiling. For example:

USE_X_PREFIX=	yes
USE_GNOME=	gnomeprefix gnomehack

.if (${GNOME_DESKTOP_VERSION} == "1")
	CONFIGURE_ARGS+=		--with-gnome
	USE_GNOME+=		gtk12 libpanel
.else
	CONFIGURE_ARGS+=		--with-gnome2
	USE_GNOME+=		gtk20 gnomepanel
.endif
	

In this example, specific CONFIGURE_ARGS and USE_GNOME components are set depending upon which GNOME_DESKTOP_VERSION is installed or preferred by the user.

Optional GNOME Dependencies

If your port can optionally use GNOME, you must set WANT_GNOME= yes in your Makefile, then check to see if HAVE_GNOME 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 bsd.port.pre.mk and bsd.port.post.mk. For example:

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>
          

Here, WANT_GNOME 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 HAVE_GNOME. Since this port can use libpanel, we check HAVE_GNOME to see if it contains libpanel (for more on the :Mpattern make syntax, please refer to the make(1) manpage). If libpanel is found, then it is added the list of USE_GNOME dependencies, and the port-specific --with-gnome CONFIGURE_ARG is passed. In an old GNOME infrastructure, PKGNAMESUFFIX was automatically adjusted by the proper USE_* macro. Now it is up to the individual porter to do this. Our example port appends -gnome to the port name to indicate it has been built with GNOME support. The same is true for the DATADIR PLIST_SUB. The individual porter must decide when do the DATADIR substitution. A good rule of thumb is to add the DATADIR PLIST_SUB when using the gnomeprefix component.

Note: You cannot add extra default USE_GNOME components after the .include <bsd.port.pre.mk>. That is, the following is wrong :

.include <bsd.port.pre.mk>

.if ${HAVE_GNOME:Mgnomelibs}!=""
	USE_GNOME+=	gnomelibs
.else
	USE_GNOME+=	gtk12  # WRONG!
.endif
	  

This will make the build system think that GNOME is desired, and mark the pkg-plist accordingly, thus breaking package builds. If you need to add default USE_GNOME components, do so above the .include <bsd.port.pre.mk> line.

To enforce use of optional GNOME dependencies unconditionally, you can add WITH_GNOME= yes to /etc/make.conf 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 WITHOUT_GNOME= yes to /etc/make.conf or to the make command line.

More information on the USE_GNOME infrastructure can be found by looking at the source and comments of ${PORTSDIR}/Mk/bsd.gnome.mk.

OMF Installation

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 pkg-plist has the following for each OMF file listed.

@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
            

For example:

@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
            

Libtool Issues

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 USE_LIBTOOL= yes 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 configure script directly below the line LIBTOOL_DEPS="$ac_aux_dir/ltmain.sh":

$ac_aux_dir/ltconfig $LIBTOOL_DEPS
	    

This prevents the installation of .la files and ensures that ${PTHREAD_LIBS} will be passed to the linker.

Distfiles

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 ${MASTER_SITE_GNOME} must add the following to their Makefile:

DIST_SUBDIR=    gnome
          

GNOME 2 ports that download their distfiles from ${MASTER_SITE_GNOME} must include the following in their Makefile:

DIST_SUBDIR=    gnome2
	  

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:

USE_BZIP2=  yes
	  

If you still need help with your port, have a look at some of the existing ports for examples. The freebsd-gnome mailing list is also there for you.