pkgsrc/doc/guide/files/gnome.xml

<!-- $NetBSD: gnome.xml,v 1.9 2009/04/03 01:52:24 snj Exp $ -->

<chapter id="gnome"> <?dbhtml filename="gnome.html"?>
<title>GNOME packaging and porting</title>

<para>Quoting <ulink url="http://www.gnome.org/">GNOME's web
site</ulink>:</para>

<blockquote>
  <para>The GNOME project provides two things: The GNOME desktop
  environment, an intuitive and attractive desktop for users, and the
  GNOME development platform, an extensive framework for building
  applications that integrate into the rest of the desktop.</para>
</blockquote>

<para>pkgsrc provides a seamless way to automatically build and install
a complete GNOME environment <emphasis>under many different
platforms</emphasis>.  We can say with confidence that pkgsrc is one of
the most advanced build and packaging systems for GNOME due to its
included technologies buildlink3, the wrappers and tools framework and
automatic configuration file management.  Lots of efforts are put into
achieving a completely clean deinstallation of installed software
components.</para>

<para>Given that pkgsrc is <ulink
url="http://www.NetBSD.org/">NetBSD</ulink>'s official packaging system,
the above also means that great efforts are put into making GNOME work
under this operating system.  Recently, <ulink
url="http://www.dragonflybsd.org/">DragonFly BSD</ulink> also adopted
pkgsrc as its preferred packaging system, contributing lots of
portability fixes to make GNOME build and install under it.</para>

<para>This chapter is aimed at pkgsrc developers and other people
interested in helping our GNOME porting and packaging efforts.  It
provides instructions on how to manage the existing packages and some
important information regarding their internals.</para>

<note>
  <title>We need your help!</title>

  <para>Should you have some spare cycles to devote to NetBSD, pkgsrc
  and GNOME and are willing to learn new exciting stuff, please jump
  straight to the <ulink
  url="http://www.NetBSD.org/contrib/projects.html#gnome">pending
  work</ulink> list!  There is still a long way to go to get a
  fully-functional GNOME desktop under NetBSD and we need your help to
  achieve it!</para>
</note>

<sect1 id="meta-packages">
<title>Meta packages</title>

<para>pkgsrc includes three GNOME-related meta packages:</para>

<itemizedlist>
  <listitem>
    <para><filename role="pkg">meta-pkgs/gnome-base</filename>: Provides
    the core GNOME desktop environment.  It only includes the necessary
    bits to get it to boot correctly, although it may lack important
    functionality for daily operation.  The idea behind this package is
    to let end users build their own configurations on top of this one,
    first installing this meta package to achieve a functional setup and
    then adding individual applications.</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">meta-pkgs/gnome</filename>: Provides a
    complete installation of the GNOME platform and desktop as defined
    by the GNOME project; this is based on the components distributed in
    the <filename>platform/x.y/x.y.z/sources</filename> and
    <filename>desktop/x.y/x.y.z/sources</filename> directories of the
    official FTP server.  Developer-only tools found in those
    directories are not installed unless required by some other
    component to work properly.  Similarly, packages from the bindings
    set (<filename>bindings/x.y/x.y.z/sources</filename>) are not pulled
    in unless required as a dependency for an end-user component.  This
    package "extends" <filename
    role="pkg">meta-pkgs/gnome-base</filename>.</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">meta-pkgs/gnome-devel</filename>:
    Installs all the tools required to build a GNOME component when
    fetched from the CVS repository.  These are required to let the
    <command>autogen.sh</command> scripts work appropriately.</para>
  </listitem>
</itemizedlist>

<para>In all these packages, the <varname>DEPENDS</varname> lines are
sorted in a way that eases updates: a package may depend on other
packages listed before it but not on any listed after it.  It is very
important to keep this order to ease updates so... <emphasis>do not
change it to alphabetical sorting!</emphasis></para>

</sect1>

<sect1 id="new-package">
<title>Packaging a GNOME application</title>

<para>Almost all GNOME applications are written in C and use a common
set of tools as their build system.  Things get different with the new
bindings to other languages (such as Python), but the following will
give you a general idea on the minimum required tools:</para>

<itemizedlist>
  <listitem>
    <para>Almost all GNOME applications use the GNU Autotools as their
    build system.  As a general rule you will need to tell this to your
    package:</para>

    <programlisting>
GNU_CONFIGURE=yes
USE_LIBTOOL=yes
USE_TOOLS+=gmake
</programlisting>
  </listitem>

  <listitem>
    <para>If the package uses pkg-config to detect dependencies, add this
    tool to the list of required utilities:</para>

    <programlisting>USE_TOOLS+=pkg-config</programlisting>

    <para>Also use <filename role="pkg">pkgtools/verifypc</filename> at
    the end of the build process to ensure that you did not miss to
    specify any dependency in your package and that the version
    requirements are all correct.</para>
  </listitem>

  <listitem>
    <para>If the package uses intltool, be sure to add
    <literal>intltool</literal> to the <varname>USE_TOOLS</varname>
    to handle dependencies and to force the package to use the latest
    available version.</para>
  </listitem>

  <listitem>
    <para>If the package uses gtk-doc (a documentation generation
    utility), do <emphasis>not</emphasis> add a dependency on it.  The
    tool is rather big and the distfile should come with pregenerated
    documentation anyway; if it does not, it is a bug that you ought to
    report.  For such packages you should disable gtk-doc (unless it is
    the default):</para>

    <programlisting>CONFIGURE_ARGS+=--disable-gtk-doc</programlisting>

    <para>The default location of installed HTML files
    (<filename>share/gtk-doc/&lt;package-name&gt;</filename>) is correct
    and should not be changed unless the package insists on installing
    them somewhere else.  Otherwise programs as
    <command>devhelp</command> will not be able to open them.  You can
    do that with an entry similar to:</para>

    <programlisting>CONFIGURE_ARGS+=--with-html-dir=${PREFIX}/share/gtk-doc/...</programlisting>
  </listitem>
</itemizedlist>

<para>GNOME uses multiple <emphasis>shared</emphasis> directories and
files under the installation prefix to maintain databases.  In this
context, shared means that those exact same directories and files are
used among several different packages, leading to conflicts in the
<filename>PLIST</filename>.  pkgsrc currently includes functionality to
handle the most common cases, so you have to forget about using
<literal>@unexec ${RMDIR}</literal> lines in your file lists and
omitting shared files from them.  If you find yourself doing those,
<emphasis>your package is most likely incorrect</emphasis>.</para>

<para>The following table lists the common situations that result in
using shared directories or files.  For each of them, the appropriate
solution is given.  After applying the solution be sure to
<emphasis>regenerate the package's file list</emphasis> with
<command>make print-PLIST</command> and ensure it is correct.</para>

<table id="plist-handling">
  <title>PLIST handling for GNOME packages</title>

  <tgroup cols="2">
    <thead>
      <row>
        <entry>If the package...</entry>
        <entry>Then...</entry>
      </row>
    </thead>

    <tbody>
      <row>
        <entry>Installs OMF files under <filename>share/omf</filename>.</entry>
        <entry>See <xref linkend="scrollkeeper-data-files" />.</entry>
      </row>

      <row>
        <entry>Installs icons under the
        <filename>share/icons/hicolor</filename> hierarchy or updates
        <filename>share/icons/hicolor/icon-theme.cache</filename>.</entry>
        <entry>See <xref linkend="hicolor-theme" />.</entry>
      </row>

      <row>
        <entry>Installs files under
        <filename>share/mime/packages</filename>.</entry>
        <entry>See <xref linkend="mime-database" />.</entry>
      </row>

      <row>
        <entry>Installs <filename>.desktop</filename> files under
        <filename>share/applications</filename> and these include MIME
        information.</entry>
        <entry>See <xref linkend="desktop-files" />.</entry>
      </row>
    </tbody>
  </tgroup>
</table>

</sect1>

<sect1 id="full-update">
<title>Updating GNOME to a newer version</title>

<para>When seeing GNOME as a whole, there are two kinds of
updates:</para>

<variablelist>
  <varlistentry>
    <term>Major update</term>

    <listitem>
      <para>Given that there is still a very long way for GNOME 3 (if it
      ever appears), we consider a major update one that goes from a
      <literal>2.X</literal> version to a <literal>2.Y</literal> one,
      where <literal>Y</literal> is even and greater than
      <literal>X</literal>.  These are hard to achieve because they
      introduce lots of changes in the components' code and almost all
      GNOME distfiles are updated to newer versions.  Some of them can
      even break API and ABI compatibility with the previous major
      version series.  As a result, the update needs to be done all at
      once to minimize breakage.</para>

      <para>A major update typically consists of around 80 package
      updates and the addition of some new ones.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>Minor update</term>

    <listitem>
      <para>We consider a minor update one that goes from a
      <literal>2.A.X</literal> version to a <literal>2.A.Y</literal>
      one where <literal>Y</literal> is greater than
      <literal>X</literal>.  These are easy to achieve because they do
      not update all GNOME components, can be done in an incremental way
      and do not break API nor ABI compatibility.</para>

      <para>A minor update typically consists of around 50 package
      updates, although the numbers here may vary a lot.</para>
    </listitem>
  </varlistentry>
</variablelist>

<para>In order to update the GNOME components in pkgsrc to a new stable
release (either major or minor), the following steps should be
followed:</para>

<orderedlist>
  <listitem>
    <para>Get a list of all the tarballs that form the new release by
    using the following commands.  These will leave the full list of the
    components' distfiles into the <filename>list.txt</filename>
    file:</para>

    <screen>&cprompt; <userinput>echo ls "*.tar.bz2" | \
    ftp -V ftp://ftp.gnome.org/pub/gnome/platform/x.y/x.y.z/sources/ | \
    awk '{ print $9 }' &gt;list.txt</userinput>
&cprompt; <userinput>echo ls "*.tar.bz2" | \
    ftp -V ftp://ftp.gnome.org/pub/gnome/desktop/x.y/x.y.z/sources/ | \
    awk '{ print $9 }' &gt;&gt;list.txt</userinput></screen>
  </listitem>

  <listitem>
    <para>Open each meta package's <filename>Makefile</filename> and
    bump their version to the release you are updating them to.  The
    three meta packages should be always consistent with versioning.
    Obviously remove any <varname>PKGREVISION</varname>s that might be
    in them.</para>
  </listitem>

  <listitem>
    <para>For each meta package, update all its
    <varname>DEPENDS</varname> lines to match the latest versions as
    shown by the above commands.  Do <emphasis>not</emphasis> list any
    newer version (even if found in the FTP) because the meta packages
    are supposed to list the exact versions that form a specific GNOME
    release.  Exceptions are permitted here if a newer version solves a
    serious issue in the overall desktop experience; these typically
    come in the form of a revision bump in pkgsrc, not in newer versions
    from the developers.</para>

    <para>Packages not listed in the <filename>list.txt</filename> file
    should be updated to the latest version available (if found in
    pkgsrc).  This is the case, for example, of the dependencies on the
    GNU Autotools in the <filename
    role="pkg">meta-pkgs/gnome-devel</filename> meta package.</para>
  </listitem>

  <listitem>
    <para>Generate a patch from the modified meta packages and extract the
    list of "new" lines.  This will provide you an outline on what
    packages need to be updated in pkgsrc and in what order:</para>

    <screen>&cprompt; <userinput>cvs diff -u gnome-devel gnome-base gnome | grep '^+D' &gt;todo.txt</userinput></screen>
  </listitem>

  <listitem>
    <para>For major desktop updates it is recommended to zap all your
    installed packages and start over from scratch at this point.</para>
  </listitem>

  <listitem>
    <para>Now comes the longest step by far: iterate over the contents
    of <filename>todo.txt</filename> and update the packages listed in
    it in order.  For major desktop updates none of these should be
    committed until the entire set is completed because there are chances
    of breaking not-yet-updated packages.</para>
  </listitem>

  <listitem>
    <para>Once the packages are up to date and working, commit them to
    the tree one by one with appropriate log messages.  At the end,
    commit the three meta package updates and all the corresponding
    changes to the <filename>doc/CHANGES-&lt;YEAR&gt;</filename> and
    <filename role="cvsweb">pkgsrc/doc/TODO</filename> files.</para>
  </listitem>
</orderedlist>

</sect1>

<sect1 id="patching">
<title>Patching guidelines</title>

<para>GNOME is a very big component in pkgsrc which approaches 100
packages.  Please, it is very important that you always, always,
<emphasis role="strong">always</emphasis> feed back any portability
fixes you do to a GNOME package to the mainstream developers (see <xref
linkend="components.patches.feedback" />).  This is the only way to get
their attention on portability issues and to ensure that future versions
can be built out-of-the box on NetBSD.  The less custom patches in
pkgsrc, the easier further updates are.  Those developers in charge of
issuing major GNOME updates will be grateful if you do that.</para>

<para>The most common places to report bugs are the <ulink
url="http://bugzilla.gnome.org/">GNOME's Bugzilla</ulink> and the <ulink
url="http://bugzilla.freedesktop.org/">freedesktop.org's
Bugzilla</ulink>.  Not all components use these to track bugs, but most
of them do.  Do not be short on your reports: always provide detailed
explanations of the current failure, how it can be improved to achieve
maximum portability and, if at all possible, provide a patch against CVS
head.  The more verbose you are, the higher chances of your patch being
accepted.</para>

<para>Also, please avoid using preprocessor magic to fix portability
issues.  While the FreeBSD GNOME people are doing a great job in porting
GNOME to their operating system, the official GNOME sources are now
plagued by conditionals that check for <varname>__FreeBSD__</varname>
and similar macros.  This hurts portability.  Please see our patching
guidelines (<xref linkend="components.patches.guidelines" />) for more
details.</para>

</sect1>

</chapter>