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.
There is an example Makefile 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.
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:
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
In the beginning, there was only GNOME 1. When the GNOME 2 desktop came around, maximum backwards compatability was ensured, within reason. GNOME 1 applications can run fine under the GNOME 2 desktop, provided that the applications do not utilize functionality specific to the GNOME 1 desktop environment.
The GNOME 1 desktop, and all applications that will not run under the GNOME 2 desktop, have been removed from the ports tree.
What this means for you, as an application porter, is simply that you should not add GNOME 1-specific applications to the ports tree.
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 GNOME_DESKTOP_VERSION. This variable is set to either "1" or "2" depending upon whether the GNOME 1 or GNOME 2 desktop is installed.
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: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>
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 gnomepanel, we check HAVE_GNOME to see if it contains gnomepanel (for more on the :Mpattern make syntax, please refer to the make(1) manpage). If gnomepanel 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+= libgnome
.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.
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
You can use this script to add these entries automatically.
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 %gconf.xml key files. Previously, these %gconf.xml key files were listed in plists. However, this proved to be problematic. Therefore, a new solution has been devised. GConf schema files are now handled similarly to OMF files. That is, for each schema file installed by your port, you must have the following entries listed in the pkg-plist:
@unexec env GCONF_CONFIG_SOURCE=xml::%D/etc/gconf/gconf.xml.defaults \ gconftool-2 --makefile-uninstall-rule \ %D/etc/gconf/schemas/my_app.schemas > /dev/null || /usr/bin/true @exec env GCONF_CONFIG_SOURCE=xml::%D/etc/gconf/gconf.xml.defaults \ gconftool-2 --makefile-install-rule \ %D/etc/gconf/schemas/my_app.schemas > /dev/null || /usr/bin/true
For example:
@unexec env GCONF_CONFIG_SOURCE=xml::%D/etc/gconf/gconf.xml.defaults \ gconftool-2 --makefile-uninstall-rule \ %D/etc/gconf/schemas/file-roller.schemas > /dev/null || /usr/bin/true @exec env GCONF_CONFIG_SOURCE=xml::%D/etc/gconf/gconf.xml.defaults \ gconftool-2 --makefile-install-rule \ %D/etc/gconf/schemas/file-roller.schemas > /dev/null || /usr/bin/true
You can use this script to - add these entrie automatically.
+ add these entries automatically.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_VER= 13 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 lthack to USE_GNOME line in port Makefile. This prevents the installation of .la files and ensures that ${PTHREAD_LIBS} will be passed to the linker.
Some applications may use newer versions of libtool, and lthack may not be sufficient. This is usually apparent during the linking phase where errors such as the following are thrown:
libtool: ../../libsomelib.la not found
In this case, you should replace USE_LIBTOOL_VER=13 with GNU_CONFIGURE=yes, and patch the port's ltmain.sh script directly. Unfortunately, there is not one patch for ltmain.sh that will work for every port. Therefore, you should adapt one of the existing patch-ltmain.sh files to work with your port.
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.
&footer;