diff --git a/en/gnome/docs/porting.sgml b/en/gnome/docs/porting.sgml index b448c9c0e5..2e660c6ab9 100644 --- a/en/gnome/docs/porting.sgml +++ b/en/gnome/docs/porting.sgml @@ -1,358 +1,380 @@ - + %gnomeincludes; %includes; ]> &header;

This document assumes that you already know how 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

Recently, the GNOME porting infrastructure has undergone some changes so that GNOME 1 applications can coexist with the GNOME 2 desktop and vice versa. This new infrastructure is called GNOMENG. The GNOME team is working to port the applications using the old infrastructure over to GNOMENG. Currently, all of the GNOME 1 desktop and the GNOME Fifth Toe have been ported.

The majority of this section applies to GNOME 1 ports. GNOME 2 ports still have not bee fully brought under GNOMENG. For those ports, simply listing out the BUILD, RUN, and LIB DEPENDS is sufficient for the time being.

The old infrastructure used the following Makefile macros for building GNOME or GTK+ ports:

 USE_ESOUND
 USE_GLIB
 USE_GNOMECTRL
 USE_GNOMELIBS
 USE_GTK
 USE_IMLIB
 
 WANT_ESOUND
 WANT_GLIB
 WANT_GNOMECTRL
 WANT_GNOMELIBS
 WANT_GTK
 WANT_IMLIB

These are now deprecated. In GNOMENG, the way the specify which GNOME components your port requires is to add the following to your port's Makefile:

 USE_X_PREFIX=	yes
 USE_GNOMENG=	yes
 USE_GNOME=	<list of GNOME components>

The list of GNOME components consists of one or more of the following separated by a single space:

  • gnomehack : This is a collection of common GNOME Makefile substitutions that is almost required for every GNOME port to fit into the proper mtree structure. For a specific list, please refer to ${PORTSDIR}/Mk/bsd.gnomeng.mk. Note: Including this option adds a pre-patch target to your Makefile. Therefore, if you already have a pre-patch target in your Makefile, you must change it to post-patch.

  • gnomeprefix : This is a collection of CONFIGURE_ARGS needed for every GNOME port that has to have its data placed under the GNOME hierarchy. It also includes some useful arguments that allow GNOME ports to build in the presence of gtk-doc, and maintain PREFIX safety.

  • gnomehier : This adds a dependency on misc/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.

  • gnomeaudio : This adds a dependency on audio/gnomeaudio.

  • esound : This adds a dependency on audio/esound (replaces USE_ESOUND).

  • libghttp : This adds a dependency on www/libghttp.

  • glib12 : This adds a dependency on devel/glib12 (replaces USE_GLIB).

  • gtk12 : This adds a dependency on x11-toolkits/gtk12 (replaces USE_GTK).
    Implies: glib12

  • libxml : This adds a dependency on textproc/libxml.
    Implies: glib12

  • gdkpixbuf : This adds a dependency on graphics/gdk-pixbuf.
    Implies: gtk12

  • imlib : This adds a dependency on graphics/imlib (replaces USE_IMLIB).
    Implies: gtk12

  • orbit : This adds a dependency on devel/ORBit.
    Implies: glib12

  • gnomelibs : This adds a dependency on x11/gnomelibs (replaces USE_GNOMELIBS).
    Implies: esound imlib libxml orbit

  • gnomecanvas : This adds a dependency on graphics/gnomecanvas.
    Implies: gnomelibs gdkpixbuf

  • oaf : This adds a dependency on devel/oaf.
    Implies: orbit libxml

  • gnomemimedata : This adds a dependency on misc/gnomemimedata.
    Implies: gnomehier

  • gconf : This adds a dependency on devel/gconf.
    Implies: oaf

  • gnomevfs : This adds a dependency on devel/gnomevfs.
    Implies: gnomemimedata gconf gnomelibs

  • libcapplet : This adds a dependency on x11/libcapplet (replaces USE_GNOMECTRL). If your port installs a configuration applet (or capplet), you must include this option.
    Implies: gnomelibs

  • gnomeprint : This adds a dependency on print/gnomeprint.
    Implies: gnomelibs gnomecanvas

  • bonobo : This adds a dependency on devel/bonobo.
    Implies: oaf gnomeprint

  • libgda : This adds a dependency on databases/libgda.
    Implies: gconf bonobo

  • gnomedb : This adds a dependency on databases/gnomedb.
    Implies: libgda

  • libglade : This adds a dependency on devel/libglade.
    Implies: gnomedb

  • gal : This adds a dependency on x11-toolkits/gal.
    Implies: libglade

  • glibwww : This adds a dependency on www/glibwww.
    Implies: gnomelibs

  • gtkhtml : This adds a dependency on www/gtkhtml.
    Implies: glibwww gal libghttp libcapplet

  • libpanel : This adds a dependency on x11/libpanel. Use this if your port installs an applet that can be placed in the GNOME 1 panel. Note: - that even though you can have GNOME 1 applets in a + even though you can have GNOME 1 applets in a GNOME 2 desktop environment, they will not work with the GNOME 2 panel.
    Implies: gnomelibs

Let us take an example:

 USE_X_PREFIX=	yes
 USE_GNOMENG=	yes
 USE_GNOME=	gnomeprefix gnomehack gnomelibs bonobo libglade gal
 
 post-patch:
 	@${REINPLACE_CMD} -e 's|-lpthread|${PTHREAD_LIBS}|g ; \
 		s|DATADIRNAME=lib|DATADIRNAME=share|g' ${WRKSRC}/configure

This port makes use of the new GNOMENG infrastructure. It installs into the GNOME mtree, and uses the gnomehack to remove some common Makefile Linuxisms. Since it uses gnomehack, the pre-install target has been changed to a post-install target. If this is not done, then the pre-install target from gnomehack will be overwritten. The port also requires gnomelibs, bonobo, libglade, and gal.

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>

What happens here is 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 the old GNOME infrastructure, PKGNAMESUFFIX was automatically adjusted by the proper USE_* macro. In GNOMENG, 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. In GNOMENG, 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 GNOMENG 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 no matter what, you can add WITH_GNOME= yes to /etc/make.conf or on the make command line. This makes GNOMENG always return true when checking for optional GNOME dependencies. If you want GNOMENG 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.

Once you have finished with your port, it is a good idea to verify 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.

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

Note: GNOMENG is temporary. That is, it was put in place so that ports could be gradually migrated from the old infrastructure to the new one. Once all ports have been migrated, the old porting infrastructure as well as the USE_GNOMENG macro will be removed.

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

Things must be done to sort out the new GNOME 2 distfiles from the GNOME 1 distfiles, as well as do our part to keep the distfiles directory clean. To do this, 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;