6.10. Using GNOME

6.10.1. Introduction

This chapter explains the GNOME framework as used by ports. The framework can be loosely divided into the base components, GNOME desktop components, and a few special macros that simplify the work of port maintainers.

6.10.2. Using USE_GNOME

Adding this variable to the port allows the use of the macros and components defined in bsd.gnome.mk. The code in bsd.gnome.mk adds the needed build-time, run-time or library dependencies or the handling of special files. GNOME applications under FreeBSD use the USE_GNOME infrastructure. Include all the needed components as a space-separated list. The USE_GNOME components are divided into these virtual lists: basic components, GNOME 3 components and legacy components. If the port needs only GTK3 libraries, this is the shortest way to define it:

USE_GNOME=	gtk30

USE_GNOME components automatically add the dependencies they need. Please see Section 6.11, “GNOME Components” for an exhaustive list of all USE_GNOME components and which other components they imply and their dependencies.

Here is an example Makefile for a GNOME port that uses many of the techniques outlined in this document. Please use it as a guide for creating new ports.

# $FreeBSD$

PORTNAME=	regexxer
CATEGORIES=	devel textproc gnome

COMMENT=	Interactive tool for performing search and replace operations

USES=		gettext gmake localbase:ldflags pathfix pkgconfig tar:xz
USE_GNOME=	gnomeprefix intlhack gtksourceviewmm3

GLIB_SCHEMAS=	org.regexxer.gschema.xml

.include <bsd.port.mk>


The USE_GNOME macro without any arguments does not add any dependencies to the port. USE_GNOME cannot be set after bsd.port.pre.mk.

6.10.3. Variables

This section explains which macros are available and how they are used. Like they are used in the above example. The Section 6.11, “GNOME Components” has a more in-depth explanation. USE_GNOME has to be set for these macros to be of use.


GTK+ ports which install Freedesktop-style icons to ${LOCALBASE}/share/icons should use this macro to ensure that the icons are cached and will display correctly. The cache file is named icon-theme.cache. Do not include that file in pkg-plist. This macro handles that automatically. This macro is not needed for Qt, which uses an internal method.


List of all the glib schema files the port installs. The macro will add the files to the port plist and handle the registration of these files on install and deinstall.

The glib schema files are written in XML and end with the gschema.xml extension. They are installed in the share/glib-2.0/schemas/ directory. These schema files contain all application config values with their default settings. The actual database used by the applications is built by glib-compile-schema, which is run by the GLIB_SCHEMAS macro.



Do not add glib schemas to the pkg-plist. If they are listed in pkg-plist, they will not be registered and the applications might not work properly.


List all the gconf schema files. The macro will add the schema files to the port plist and will handle their registration on install and deinstall.

GConf is the XML-based database that virtually all GNOME applications use for storing their settings. These files are installed into the etc/gconf/schemas directory. This database is defined by installed schema files that are used to generate %gconf.xml key files. For each schema file installed by the port, there must be an entry in the Makefile:

GCONF_SCHEMAS=my_app.schemas my_app2.schemas my_app3.schemas


Gconf schemas are listed in the GCONF_SCHEMAS macro rather than pkg-plist. If they are listed in pkg-plist, they will not be registered and the applications might not work properly.


Open Source Metadata Framework (OMF) files are commonly used by GNOME 2 applications. These files contain the application help file information, and require special processing by ScrollKeeper/rarian. To properly register OMF files when installing GNOME applications from packages, make sure that omf files are listed in pkg-plist and that the port Makefile has INSTALLS_OMF defined:


When set, bsd.gnome.mk automatically scans pkg-plist and adds appropriate @exec and @unexec directives for each .omf to track in the OMF registration database.

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.