989d921f5d
I'm very pleased to announce the release of our new website and documentation using the new toolchain with Hugo and AsciiDoctor. To get more information about the new toolchain please read the FreeBSD Documentation Project Primer[1], Hugo docs[2] and AsciiDoctor docs[3]. Acknowledgment: Benedict Reuschling <bcr@> Glen Barber <gjb@> Hiroki Sato <hrs@> Li-Wen Hsu <lwhsu@> Sean Chittenden <seanc@> The FreeBSD Foundation [1] https://docs.FreeBSD.org/en/books/fdp-primer/ [2] https://gohugo.io/documentation/ [3] https://docs.asciidoctor.org/home/ Approved by: doceng, core
199 lines
11 KiB
Text
199 lines
11 KiB
Text
---
|
|
title: "FreeBSD GNOME Project: How To Make a Port"
|
|
sidenav: gnome
|
|
---
|
|
|
|
include::shared/en/urls.adoc[]
|
|
|
|
= FreeBSD GNOME Project: How To Make a Port
|
|
|
|
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 link:{porters-handbook}[FreeBSD Porter's Handbook].
|
|
|
|
== Example Makefile
|
|
|
|
There is an link:../example-makefile/[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_XLIB= yes
|
|
USE_GNOME= gnomeprefix gnomehack libgnomeui
|
|
....
|
|
|
|
The *USE_GNOME* components are divided into the following two lists:
|
|
|
|
* link:../gnome_porting/[GNOME desktop-version-independent components]
|
|
* link:../gnome2_porting/[GNOME 2 components]
|
|
* link:../gnome1_porting/[GNOME 1 components]
|
|
|
|
If your port needs only *GTK2* libraries, the following is the shortest way to define this:
|
|
|
|
....
|
|
USE_GNOME= gtk20
|
|
....
|
|
|
|
If your port needs only *GTK1* libraries, the following is the shortest way to define this:
|
|
|
|
....
|
|
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 compatibility 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
|
|
.else
|
|
CONFIGURE_ARGS+= --without-gnome
|
|
.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 :M`pattern` make syntax, please refer to the link:https://www.freebsd.org/cgi/man.cgi?query=make&sektion=0&format=html[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`.
|
|
|
|
[[prefix]]
|
|
== GNOME PREFIX
|
|
|
|
Since the release of 2.16, GNOME now lives in `LOCALBASE` instead of `X11BASE`. To make it easier for GNOME ports that must also be installed into the same PREFIX as GNOME, a hack has been added to `bsd.gnome.mk` to force the PREFIX to `LOCALBASE` whenever the `gnomeprefix` component is used. This can be overridden by manually specifying `PREFIX` in your port's `Makefile` or on the command line.
|
|
|
|
[[omf]]
|
|
== 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 that `omf` files are listed in `pkg-plist` and that your `Makefile` has this defined:
|
|
|
|
....
|
|
INSTALLS_OMF="yes"
|
|
....
|
|
|
|
== 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 schema files and `%gconf.xml` key files were listed in the port's `pkg-plist`. Since this proved to be problematic, handling of GConf schemas was changed to something similar to that of link:{porters-handbook}[MANn] files. That is, for each schema file installed by your port, you must have the following listed in the `Makefile`:
|
|
|
|
....
|
|
GCONF_SCHEMAS= my_app.schemas my_app2.schemas my_app3.schemas
|
|
....
|
|
|
|
For example in `audio/gnome-media`:
|
|
|
|
....
|
|
GCONF_SCHEMAS= CDDB-Slave2.schemas gnome-audio-profiles.schemas \
|
|
gnome-cd.schemas gnome-sound-recorder.schemas
|
|
....
|
|
|
|
The schema files and `%gconf.xml` key files should not be in the `pkg-plist`. If you notice that the port doesn't has any `%gconf.xml` key files, but has schema files then you should not be use `GCONF_SCHEMAS`. It means, this port has broke either schema files or installation of GConf.
|
|
|
|
== Shared MIME database
|
|
|
|
If your port install files like `application/x-portname.xml` in `share/mime`, you have to add these two lines at the end of the `pkg-plist`:
|
|
|
|
....
|
|
@exec %%LOCALBASE%%/bin/update-mime-database %D/share/mime
|
|
@unexec %%LOCALBASE%%/bin/update-mime-database %D/share/mime
|
|
....
|
|
|
|
Also make sure `shared-mime-info` is among the dependencies of your port. If your port use `gtk20`, you will have `shared-mime-info` indirectly. You can check indirect dependencies with `make describe`.
|
|
|
|
Example port to look at: https://svnweb.FreeBSD.org/ports/head/deskutils/drivel/[`deskutils/drivel`]
|
|
|
|
== Desktop database
|
|
|
|
Some ports provide MIME definitions in their `.desktop` files. If your port install `.desktop` file into `share/applications` and there is a line starting with `MimeType` in it, you need to update desktop database after install and deinstall. This database is represented by `share/applications/mimeinfo.cache` file. Add dependency on GNOME component `desktopfileutils` and these lines to the end of `pkg-plist`:
|
|
|
|
....
|
|
@exec %%LOCALBASE%%/bin/update-desktop-database > /dev/null || /usr/bin/true
|
|
@unexec %%LOCALBASE%%/bin/update-desktop-database > /dev/null || /usr/bin/true
|
|
....
|
|
|
|
Also add following to the `post-install` target in port's Makefile:
|
|
|
|
....
|
|
-@update-desktop-database
|
|
....
|
|
|
|
Example port to look at: https://svnweb.FreeBSD.org/ports/head/editors/leafpad/[`editors/leafpad`]
|
|
|
|
[[libtool]]
|
|
== 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, and includes an `ltmain.sh` script in its `${WRKSRC}` directory, you should add `USES=libtool` to your port's Makefile.
|
|
|
|
== 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 mailto:freebsd-gnome@FreeBSD.org[freebsd-gnome mailing list] is also there for you.
|