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,6 +1,6 @@ - + %gnomeincludes; %includes; @@ -10,193 +10,136 @@
-

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.

    • +

  • GNOME 2 components

    • +

  • GNOME 1 components

    • +
-

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

    + +

    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 @@ -233,13 +176,13 @@ PLIST_SUB= DATADIR="share" 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. @@ -260,57 +203,26 @@ 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 the USE_GNOME infrastructure can be found + by looking at the source and comments of + ${PORTSDIR}/Mk/bsd.gnome.mk.

    -

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

    These are now deprecated.

    @@ -328,15 +240,23 @@ WANT_IMLIB 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