diff --git a/en/gnome/docs/Makefile b/en/gnome/docs/Makefile index 7ff4a88beb..7ecc1ad460 100644 --- a/en/gnome/docs/Makefile +++ b/en/gnome/docs/Makefile @@ -1,20 +1,21 @@ -# $FreeBSD: www/en/gnome/docs/Makefile,v 1.11 2003/12/27 23:03:10 marcus Exp $ +# $FreeBSD: www/en/gnome/docs/Makefile,v 1.12 2003/12/28 03:06:00 adamw Exp $ .if exists(../Makefile.conf) .include "../Makefile.conf" .endif .if exists(../Makefile.inc) .include "../Makefile.inc" .endif DOCS= faq2.sgml DOCS+= gnome_porting.sgml +DOCS+= gnome1_porting.sgml DOCS+= gnome2_porting.sgml DOCS+= porting.sgml DOCS+= bugging.sgml DOCS+= volunteer.sgml DOCS+= knownissues.sgml DOCS+= develfaq.sgml DOCS+= example-Makefile.sgml .include "${WEB_PREFIX}/share/mk/web.site.mk" diff --git a/en/gnome/docs/gnome_porting.sgml b/en/gnome/docs/gnome1_porting.sgml similarity index 74% copy from en/gnome/docs/gnome_porting.sgml copy to en/gnome/docs/gnome1_porting.sgml index 7b09ae816c..9e2b00c602 100644 --- a/en/gnome/docs/gnome_porting.sgml +++ b/en/gnome/docs/gnome1_porting.sgml @@ -1,195 +1,155 @@ - + %gnomeincludes; %includes; ]> &header; - - - - - - - - - - - - - - - - - - - - - - - - - - -
COMPONENT ASSOCIATED PROGRAM IMPLIED COMPONENTS
bonobo devel/bonobo oaf gnomeprint
esoundaudio/esound 
gal x11-toolkits/gal libglade
gconf devel/gconf oaf
gdkpixbuf graphics/gdk-pixbuf gtk12
glib12 devel/glib12 pkgconfig
glibwww www/glibwww gnomelibs
gnomecanvas graphics/gnomecanvas gnomelibs gdkpixbuf
gnomedb databases/gnomedb libgda
gnomehackgnomehack makes common GNOME - Makefile substitutions that nearly every GNOME port - requires to fit into the proper mtree structure. Note: - Including this option adds a pre-patch target to - your Makefile. Therefore, only explicitly define - post-patch. -
gnomehiergnomehier 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. -
gnomelibs x11/gnomelibs esound imlib libxml orbit
gnomemimedatamisc/gnomemimedatagnomehier pkgconfig
gnomeprefixgnomeprefix sets some CONFIGURE_ARGS - to ensure data is placed properly within the GNOME hierarchy. -
gnomeprint print/gnomeprint gnomelibs gnomecanvas
gnomevfs devel/gnomevfs gnomemimedata gconf gnomelibs
gtk12 x11-toolkits/gtk12 glib12
gtkhtml www/gtkhtml glibwww gal libghttp libcapplet
imlib graphics/imlib gtk12
libcapplet x11/libcapplet gnomelibs
libgda databases/libgda gconf bonobo
libghttp www/libghttp  
libglade devel/libglade gnomedb
libxml textproc/libxml glib12
oaf devel/oaf orbit libxml
orbit devel/ORBit glib12

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/gnome2_porting.sgml b/en/gnome/docs/gnome2_porting.sgml index d47564a131..3b44bf7265 100644 --- a/en/gnome/docs/gnome2_porting.sgml +++ b/en/gnome/docs/gnome2_porting.sgml @@ -1,311 +1,263 @@ - + %gnomeincludes; %includes; ]> &header; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
COMPONENT ASSOCIATED PROGRAM IMPLIED COMPONENTS
atk devel/atk glib20
atspi x11-toolkits/at-spi gail libbonobo
eel2 x11-toolkits/eel2 gnomevfs2 libgnomeui gail
esoundaudio/esound 
gail x11-toolkits/gail libgnomecanvas
gal2 x11-toolkits/gal2 gnomeui libgnomeprintui
gconf2 devel/gconf2 orbit2 libxml2 gtk20 linc
glib20 devel/glib20 gnometarget pkgconfig
gnomecontrolcenter2 sysutils/gnomecontrolcenter2 gnomedesktop metacity nautilus2
gnomedesktop x11/gnomedesktop libgnomeui
gnomehackgnomehack makes common GNOME - Makefile substitutions that nearly every GNOME port - requires to fit into the proper mtree structure. Note: - Including this option adds a pre-patch target to - your Makefile. Therefore, only explicitly define - post-patch. -
gnomehiergnomehier 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. -
gnomepanel x11/gnomepanel libwnck gnomedesktop
gnomeprefixgnomeprefix sets some CONFIGURE_ARGS - to ensure data is placed properly within the GNOME hierarchy. -
gnometargetgnometarget sets - CONFIGURE_TARGET to - --build=${MACHINE_ARCH}-portbld-freebsd${OSREL}. -
gnomevfs2 devel/gnomevfs2 gconf2 libbonobo gnomemimedata
gtk20 x11-toolkits/gtk20 atk pango
gtksourceview x11-toolkits/gtksourceview libgnome libgnomeprintui
libartlgpl2 graphics/libartlgpl2 pkgconfig
libbonobo devel/libbonobo libxml2 orbit2
libbonoboui x11-toolkits/libbonoboui libgnomecanvas libgnome
libgailgnome x11-toolkits/libgail-gnome libgnomeui atspi
libgda2 databases/libgda2 glib20 libxslt
libglade2 devel/libglade2 libxml2 gtk20
libgnome x11/libgnome libxslt gnomevfs2 esound
libgnomeui x11-toolkits/libgnomeui libbonoboui
libgnomecanvas graphics/libgnomecanvas libglade2 libartlgpl2
libgnomedb databases/libgnomedb libgnomeui libgda2
libgnomeprint print/libgnomeprint libbonobo libartlgpl2 gtk20
libgnomeprintui x11-toolkits/libgnomeprintui libgnomeprint libgnomecanvas
libgsf devel/libgsf gnomevfs2 libbonobo
libgtkhtml www/libgtkhtml libxslt gnomevfs2 gail
libidl devel/libIDL glib20
libwnck x11-toolkits/libwnck gtk20
librsvg2 graphics/librsvg2 gtk20 libgsf
libxml2 textproc/libxml2 pkgconfig
libxslt textproc/libxslt libxml2
libzvt x11-toolkits/libzvt gtk20
linc net/linc glib20
nautilus2 x11-fm/nautilus librsvg2 eel2 gnomedesktop
metacity x11-wm/metacity gconf2 glade2
orbit2 devel/ORBit2 libidl
pango x11-toolkits/pango glib20
pkgconfigdevel/pkgconfig 
vte x11-toolkits/vte gtk20

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/gnome_porting.sgml b/en/gnome/docs/gnome_porting.sgml index 7b09ae816c..ea1095a5c8 100644 --- a/en/gnome/docs/gnome_porting.sgml +++ b/en/gnome/docs/gnome_porting.sgml @@ -1,195 +1,108 @@ - - + + %gnomeincludes; %includes; ]> &header; - +
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + - - - - - - - - - + + + - - - + + + - - - + + +
COMPONENT ASSOCIATED PROGRAM IMPLIED COMPONENTS
bonobodevel/bonobooaf gnomeprint
esound audio/esound  
galx11-toolkits/gallibglade
gconfdevel/gconfoaf
gdkpixbufgraphics/gdk-pixbufgtk12
glib12devel/glib12pkgconfig
glibwwwwww/glibwwwgnomelibs
gnomecanvasgraphics/gnomecanvasgnomelibs gdkpixbuf
gnomedbdatabases/gnomedblibgda
gnomehack gnomehack makes common GNOME Makefile substitutions that nearly every GNOME port requires to fit into the proper mtree structure. Note: Including this option adds a pre-patch target to your Makefile. Therefore, only explicitly define post-patch.
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.
gnomelibsx11/gnomelibsesound imlib libxml orbit
gnomemimedata misc/gnomemimedata gnomehier pkgconfig
gnomeprefixgnomeprefix sets some CONFIGURE_ARGS + gnomeprefix sets some CONFIGURE_ARGS to ensure data is placed properly within the GNOME hierarchy. gnomehier
gnomeprintprint/gnomeprintgnomelibs gnomecanvas
gnomevfsdevel/gnomevfsgnomemimedata gconf gnomelibs
gtk12x11-toolkits/gtk12glib12
gtkhtmlwww/gtkhtmlglibwww gal libghttp libcapplet
imlibgraphics/imlibgtk12
libcappletx11/libcappletgnomelibs
libgdadatabases/libgdagconf bonobo
libghttpwww/libghttplthacklthack prevents the installation of .la + files and ensures that ${PTHREAD_LIBS} will be passed + to the linker. NOTE: Only available for the GNOME + &gnomedevelver; tree. +  
libgladedevel/libgladegnomedb
libxmltextproc/libxmlglib12gnometargetgnometarget sets + ${CONFIGURE_TARGET} for ports whose + configure script does not figure it out automatically. +  
oafdevel/oaforbit libxmlpkgconfigpkgconfig registers a dependency upon + devel/pkgconfig to make sure it is installed. +  
orbitdevel/ORBitglib12intlhackintlhack registers a dependency upon + textproc/intltool and patches broken + intltool-merge.in implementations. + NOTE: Only available for the GNOME &gnomedevelver; + tree. +  

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 546f2d1a3f..c703b0be40 100644 --- a/en/gnome/docs/porting.sgml +++ b/en/gnome/docs/porting.sgml @@ -1,305 +1,307 @@ - + %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

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.

&footer;