diff --git a/en/gnome/docs/gnome_porting.sgml b/en/gnome/docs/gnome_porting.sgml index 8239a59258..842201acbe 100644 --- a/en/gnome/docs/gnome_porting.sgml +++ b/en/gnome/docs/gnome_porting.sgml @@ -1,115 +1,121 @@ - + %gnomeincludes; %includes; ]> &header;

To see how to utilize these components, please examine the example Makefile.

COMPONENT ASSOCIATED PROGRAM IMPLIED COMPONENTS
esound audio/esound  
gnomehack gnomehack makes common GNOME Makefile substitutions that nearly every GNOME port requires to fit into the proper mtree structure.
gnomehier gnomehier installs all the directories needed for both the GNOME 1 and 2 desktops. Only include this option if your port calls @dirrm on one of the directories listed in the plist for gnomehier.
gnomemimedata misc/gnomemimedata gnomehier pkgconfig
gnomeprefix gnomeprefix sets some CONFIGURE_ARGS to ensure data is placed properly within the GNOME hierarchy. gnomehier
gnometarget gnometarget sets ${CONFIGURE_TARGET} for ports whose configure script does not figure it out automatically.  
intlhack intlhack registers a dependency upon textproc/intltool and patches broken intltool-merge.in implementations. intltool
intltool intltool registers a BUILD_DEPENDS on textproc/intltool.  
lthack lthack prevents the installation of .la files and ensures that ${PTHREAD_LIBS} will be passed to the linker. + NOTE: lthack is DEPRECATED, + and USE_LIBTOOL_VER=15 should be + used instead. See the libtool + section of the porting guide for more + details.  
pkgconfig pkgconfig registers a dependency upon devel/pkgconfig to make sure it is installed.  

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; diff --git a/en/gnome/docs/porting.sgml b/en/gnome/docs/porting.sgml index 1882ece740..1857226cb1 100644 --- a/en/gnome/docs/porting.sgml +++ b/en/gnome/docs/porting.sgml @@ -1,364 +1,349 @@ - + %gnomeincludes; %includes; ]> &header;

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.

Example Makefile

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 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:

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

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.

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: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.

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

You can use this script to add these entries automatically.

GConf Schema Installation

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 entries automatically.

+

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_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.

+ shared libraries, and includes an ltmain.sh script + in its ${WRKSRC} directory, you should add + USE_LIBTOOL_VER=15 to your port's Makefile. + However, if your port uses custom LIBTOOLFLAGS, you + must use USE_INC_LIBTOOL_VER=13 instead. If you have + to use USE_INC_LIBTOOL_VER, you must also add + lthack to USE_GNOME. In general, though, + lthack is deprecated, and should only be used if + absolutely necessary.

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.

&footer;