diff --git a/en/gnome/docs/gnome2_porting.sgml b/en/gnome/docs/gnome2_porting.sgml new file mode 100644 index 0000000000..b59f940381 --- /dev/null +++ b/en/gnome/docs/gnome2_porting.sgml @@ -0,0 +1,316 @@ + + + + %gnomeincludes; + %includes; +]> + + &header; + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
COMPONENTASSOCIATED PROGRAMIMPLIED COMPONENTS
atkdevel/atkglib20
atspix11-toolkits/at-spigail libbonobo
bonoboactivationdevel/bonoboactivationlibxml2 orbit2
eel2x11-toolkits/eel2gnomevfs2 libgnomeui gail
esoundaudio/esound
gailx11-toolkits/gaillibgnomecanvas
gal2x11-toolkits/gal2gnomeui libgnomeprintui
gconf2devel/gconf2orbit2 libxml2 gtk20
glib20devel/glib20gnometarget
gnomeaudioaudio/gnomeaudio
gnomecontrolcenter2sysutils/gnomecontrolcenter2gnomedesktop metacity
gnomedesktopx11/gnomedesktoplibgnomeui
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. +
gnomepanelx11/gnomepanellibwnck 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}. +
gnomevfs2devel/gnomevfs2gconf2 libbonobo gnomemimedata
gtk20x11-toolkits/gtk20atk pango
libartlgpl2graphics/libartlgpl2
libbonobodevel/libbonobobonoboactivation
libbonobouix11-toolkits/libbonobouilibgnomecanvas libgnome
libgailgnomex11-toolkits/libgail-gnomelibgnomeui atspi
libgda2databases/libgda2glib20 libxslt
libghttpwww/libghttp
libglade2devel/libglade2libxml2 gtk20
libgnomex11/libgnomelibxslt gnomevfs2 esound
libgnomeuix11-toolkits/libgnomeuilibbonoboui
libgnomecanvasgraphics/libgnomecanvaslibglade2 libartlgpl2
libgnomedbdatabases/libgnomedblibgnomeui libgda2
libgnomeprintprint/libgnomeprintlibbonobo libartlgpl2 gtk20
libgnomeprintuix11-toolkits/libgnomeprintuilibgnomeprint libgnomecanvas
libgtkhtmlwww/libgtkhtmllibxslt gnomevfs2 gail
libidldevel/libIDLglib20
libwnckx11-toolkits/libwnckgtk20
librsvg2graphics/librsvg2gtk20
libxml2textproc/libxml2
libxslttextproc/libxsltlibxml2
libzvtx11-toolkits/libzvtgtk20
lincnet/lincglib20
nautilus2x11-fm/nautiluslibrsvg2 eel2 gnomedesktop gnomecontrolcenter
metacityx11-wm/metacitygconf2 glade2
orbit2devel/ORBit2libidl linc
pangox11-toolkits/pangoglib20
vtex11-toolkits/vtegtk20
+ + +

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 new file mode 100644 index 0000000000..1339df2e38 --- /dev/null +++ b/en/gnome/docs/gnome_porting.sgml @@ -0,0 +1,200 @@ + + + + %gnomeincludes; + %includes; +]> + + &header; + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
COMPONENTASSOCIATED PROGRAMIMPLIED COMPONENTS
bonobodevel/bonobooaf gnomeprint
esoundaudio/esound
galx11-toolkits/gallibglade
gconfdevel/gconfoaf
gdkpixbufgraphics/gdk-pixbufgtk12
glib12devel/glib12
glibwwwwww/glibwwwgnomelibs
gnomecanvasgraphics/gnomecanvasgnomelibs gdkpixbuf
gnomedbdatabases/gnomedblibgda
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. +
gnomelibsx11/gnomelibsesound imlib libxml orbit
gnomemimedatamisc/gnomemimedatagnomehier
gnomeprefixgnomeprefix sets some CONFIGURE_ARGS + to ensure data is placed properly within the GNOME hierarchy. +
gnomeprintprint/gnomeprintgnomelibs gnomecanvas
gnomevfsdevel/gnomevfsgnomemimedata gconf gnomelibs
gtk12x11-toolkits/gtk12glib12
gtkhtmlwww/gtkhtmlglibwww gal libghttp libcapplet
imlibgraphics/imlibgtk12
libcappletx11/libcappletgnomelibs
libgdadatabases/libgdagconf bonobo
libgladedevel/libgladegnomedb
libpanelx11/libpanelgnomelibs
libxmltextproc/libxmlglib12
oafdevel/oaforbit libxml
orbitdevel/ORBitglib12
+ + +

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 5584111bbd..8dd76f505f 100644 --- a/en/gnome/docs/porting.sgml +++ b/en/gnome/docs/porting.sgml @@ -1,409 +1,329 @@ - + %gnomeincludes; %includes; ]> &header;
-

This document assumes that you already know how port system works, +

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.

GNOME Makefile Macros

-

Recently, the GNOME porting infrastructure underwent 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 - applications using the old infrastructure over to GNOMENG. - Nearly every GNOME 1 port has been converted.

- -

The majority of this section applies to GNOME 1 ports. - GNOME 2 ports still have not been fully brought under GNOMENG. - For those ports, simply listing out the BUILD_, - RUN_, and LIB_ DEPENDS is sufficient - for the time being. GNOME 2 ports can still benefit from certain - GNOMENG options, such as gnomehack, gnomeprefix, - and gnomehier.

- -

In GNOMENG, the list of GNOME components your port requires - is added to your port's Makefile:

+

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_GNOMENG=	yes
-USE_GNOME=	<list of GNOME components>
+USE_GNOME=	gnomeprefix gnomehack libgnomeui
-

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

- +

The USE_GNOME components are divided into the following two lists:

+
    -

  • 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: - even though you can build 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:

+

  • GNOME 2 components

    • +

  • GNOME 1 components

    • + + + +

    If your port needs only GTK2 libraries, the following is + the shortest way to define this:

     USE_X_PREFIX=	yes
-USE_GNOMENG=	yes
-USE_GNOME=	gnomeprefix gnomehack gnomelibs bonobo libglade gal
+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.

    + +

    Many GNOME applications need the following to compile + properly and to look for components in the proper + locations:

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

    +

    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

    +

    Certain aspects of the GNOME 1 desktop environment are + incompatible with certain aspects of the GNOME 2 desktop + environment. To ensure that a user does not compile a GNOME 2 + component against their GNOME 1 environment (or vice versa), + the user may set GNOME_DESKTOP_VERSION in their + /etc/make.conf. Even if a user has not explicitly set + GNOME_DESKTOP_VERSION, the FreeBSD GNOME architecture will + attempt to automatically deduce the desktop currently installed by + examining which components are already installed.

    + +

    If compilation of a GNOME 2 port is attempted on a + GNOME_DESKTOP_VERSION=1 system, the compilation will + immediately abort and the user will be informed of the incompatability.

    + +

    If your application can handle both GNOME 1 and GNOME 2 + compilation, you may check the value of GNOME_DESKTOP_VERSION to + determine for which desktop your port is compiling. For example:

    + + 
    +USE_X_PREFIX=	yes
+USE_GNOME=	gnomeprefix gnomehack
+
+.if (${GNOME_DESKTOP_VERSION} == "1")
+	CONFIGURE_ARGS+=		--with-gnome
+	USE_GNOME+=		gtk12 libpanel
+.else
+	CONFIGURE_ARGS+=		--with-gnome2
+	USE_GNOME+=		gtk20 gnomepanel
+.endif
+
    + +

    In this example, specific CONFIGURE_ARGS and USE_GNOME + components are set depending upon which GNOME_DESKTOP_VERSION is + installed or preferred by the user.

    + +

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

    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 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 + In an old GNOME infrastructure, PKGNAMESUFFIX was automatically adjusted by the proper USE_* macro. - In GNOMENG, it is up to the individual porter to do this. + 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. In GNOMENG, - the individual porter must decide when do the DATADIR + 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+=	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. +

    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 makes GNOMENG always return + or on the make command line. This will always return true when checking for optional GNOME dependencies. If you - want GNOMENG to always return false when checking for optional + 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.

    -

    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.

    - -

    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.

    - -

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

    More information on the USE_GNOME infrastructure can be found + by looking at the source and comments of + ${PORTSDIR}/Mk/bsd.gnome.mk.

    -

    These are now deprecated.

    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
+@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
+@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;