Home | History | Annotate | Download | only in docs
      1 How to package gconf schemas
      2 ----------------------------
      3 
      4 Background
      5 
      6 (Skip this if you are familiar with gconf, schemas, %gconf.xml files.)
      7 Somewhere between GNOME 2.12 and 2.14 GConf changed the file format of
      8 its xml backend.  Previously, if you had a key called
      9 /desktop/gnome/interface/foo, the corresponding value was stored in
     10 /etc/gconf/gconf.xml.defaults/desktop/gnome/interface/%gconf.xml
     11 These files were created using gconftool-2 by installing schemas files,
     12 stored in /etc/gconf/schemas.
     13 So we had 100s of small xml files, each containing just a few keys/values
     14 and translations of the key descriptions in all languages.
     15 This became a performance issue, as it took several seconds to load
     16 these files when gconfd-2 started.  The new approach is using
     17 one "merged" xml file that includes all key - value pairs.
     18 Localisations were split into separate xml files, one for each locale.
     19 The new files are /etc/gconf/gconf.xml.defaults/%gconf-tree.xml and
     20 /etc/gconf/gconf.xml.defaults/%gconf-tree-<locale>.xml
     21 First a program called gconf-merge-tree was used to generate the
     22 merged xml files from the directory structure.  Once the merged xml
     23 files were created, gconfd-2 only read those and ignored the directory
     24 structure.  So we ended up with 2 gconf data bases which could become
     25 inconsistent.  Fortunately,  gconftool-2 can now install the schemas
     26 straight into the merged xml files.  So the preferred way to install
     27 schemas is doing just that.
     28 
     29 
     30 Introduction
     31 
     32 In JDS3, we installed the schemas into $RPM_BUILD_ROOT during 'make install'
     33 and included the generated %gconf.xml files in the -root packages.
     34 This was kinda broken as it wasn't possible for multiple packages to
     35 install gconf keys in the same directory as they would have had to
     36 deliver the same %gconf.xml file with different contents.
     37 However, the format of the xml database changed to merged xml files
     38 (see the Background above), so we were forced to change the way we
     39 deliver gconf data.
     40 The basic idea is similar to what Linux distributions do: we package the
     41 schemas files and install/uninstall them using postinstall/preremove
     42 scripts.  The only difference is that we can't use gconftool-2 directly
     43 in procedural package scripts because of problems with Live Upgrade and
     44 Alternate Root installations (see postrun.txt for more details).
     45 So what we do is, use postrun to run gconftool-2 "as soon as possible".
     46 The gconftool-2 command will install the schemas into the merged gconf
     47 files in /etc/gconf/gconf.xml.defaults/%gconf-tree*.xml.
     48 
     49 
     50 Step by step instructions
     51 
     52 1) Make sure that each -root sub package that delivers gconf schemas
     53    depends on SUNWgnome-config (gconf) and SUNWpostrun.  Add these
     54    2 lines to the end of the %package definition:
     55 
     56      Requires: SUNWpostrun-root
     57      Requires: SUNWgnome-config
     58 
     59    Example:
     60 
     61      ...
     62      %package root
     63      Summary:                 %{summary} - / filesystem
     64      SUNW_BaseDir:            /
     65      %include default-depend.inc
     66      Requires: SUNWpostrun-root
     67      Requires: SUNWgnome-config
     68      ...
     69 
     70 2) Make sure that %install does not include the directory based %gconf.xml
     71    files.  Note, if you use separate Linux and Solaris spec files and %use,
     72    these commands should go in the Linux spec file:
     73 
     74      export GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL=1    
     75      make DESTDIR=$RPM_BUILD_ROOT install
     76 
     77    If you do this, the only gconf-related files in $RPM_BUILD_ROOT/etc
     78    should be schemas.
     79 
     80    Some more explanations and historical details follow, skip to 3) if you
     81    don't care.
     82 
     83    In JDS3 and early JDS4 builds, we installed the schemas explicitely
     84    in the Solaris spec files' %install section like this:
     85 
     86      export GCONF_CONFIG_SOURCE=xml::$RPM_BUILD_ROOT%{_sysconfdir}/gconf/gconf.xml.defaults
     87      for S in $RPM_BUILD_ROOT/%{_sysconfdir}/gconf/schemas/*.schemas; do
     88        %{_bindir}/gconftool-2 --makefile-install-rule $S >/dev/null
     89      done
     90 
     91    Then we had to remove the zero-lenght %gconf.xml nodes (for example
     92    /etc/gconf/gconf.xml.defaults/apps/%gconf.xml) as they would
     93    have otherwise appeared in multiple -root pkgs, which is a violation
     94    of the packaging rules:
     95 
     96      chmod -R a+rX $RPM_BUILD_ROOT/%{_sysconfdir}
     97      for f in apps/?gconf.xml \
     98 	      schemas/?gconf.xml \
     99 	      schemas/apps/?gconf.xml \
    100 	 ; do
    101        test ! -s $RPM_BUILD_ROOT%{_sysconfdir}/gconf/gconf.xml.defaults/$f && \
    102 	 rm -rf $RPM_BUILD_ROOT%{_sysconfdir}/gconf/gconf.xml.defaults/$f
    103      done
    104 
    105    This was really broken, because if the package that includes the removed
    106    %gconf.xml files is not installed then the files included in this pkg
    107    will not be found by gconfd-2.  Worse, if, by mistake, no package
    108    includes some empty %gconf.xml nodes, the leaves won't be found at all.
    109 
    110 3) Add a %post and a %preun script that installs/uninstalls the schemas.
    111    Note, you need to list the schemas files in the %preun script.
    112    In the %post script we always install all schemas available on
    113    the system for performance reasons.
    114 
    115      %post root
    116      ( echo 'test -x /usr/bin/gconftool-2 || {';
    117        echo '  echo "ERROR: gconftool-2 not found"';
    118        echo '  exit 1';
    119        echo '}';
    120        echo 'umask 0022';
    121        echo 'GCONF_CONFIG_SOURCE=xml:merged:/etc/gconf/gconf.xml.defaults';
    122        echo 'export GCONF_CONFIG_SOURCE';
    123        echo '/usr/bin/gconftool-2 --makefile-install-rule %{_sysconfdir}/gconf/schemas/*.schemas'
    124      ) | $BASEDIR/var/lib/postrun/postrun -u -c JDS_wait
    125 
    126      %preun root
    127      test -x $BASEDIR/var/lib/postrun/postrun || exit 0
    128      ( echo 'test -x $PKG_INSTALL_ROOT/usr/bin/gconftool-2 || {';
    129        echo '  echo "WARNING: gconftool-2 not found; not uninstalling gconf schemas"';
    130        echo '  exit 0';
    131        echo '}';
    132        echo 'umask 0022';
    133        echo 'GCONF_CONFIG_SOURCE=xml:merged:$BASEDIR/etc/gconf/gconf.xml.defaults';
    134        echo 'GCONF_BACKEND_DIR=$PKG_INSTALL_ROOT/usr/lib/GConf/2';
    135        echo 'LD_LIBRARY_PATH=$PKG_INSTALL_ROOT/usr/lib';
    136        echo 'export GCONF_CONFIG_SOURCE GCONF_BACKEND_DIR LD_LIBRARY_PATH';
    137        echo 'SDIR=$BASEDIR%{_sysconfdir}/gconf/schemas';
    138        echo 'schemas="$SDIR/###FILE1###.schemas';
    139        echo '         $SDIR/###FILE2###.schemas';
    140        echo '         $SDIR/###FILE3###.schemas';
    141      (...)
    142        echo '         $SDIR/###FILEn###.schemas"';
    143        echo '$PKG_INSTALL_ROOT/usr/bin/gconftool-2 --makefile-uninstall-rule $schemas'
    144      ) | $BASEDIR/var/lib/postrun/postrun -i -c JDS -a
    145 
    146 4) update %files root (or %files -n SUNWfoo-bar-root), it should look
    147    something like this:
    148 
    149      %files root
    150      %defattr (0755, root, sys)
    151      %attr (0755, root, sys) %dir %{_sysconfdir}
    152      %{_sysconfdir}/gconf/schemas/###FILE1###.schemas
    153      %{_sysconfdir}/gconf/schemas/###FILE2###.schemas
    154      %{_sysconfdir}/gconf/schemas/###FILE3###.schemas
    155    (...)
    156      %{_sysconfdir}/gconf/schemas/###FILEn###.schemas
    157 
    158    Note: ###FILE1### ... ###FILEn### must match the list of lines in
    159    %preun.  Please don't use *.schemas but list each schemas
    160    file so that when a new schemas file is added to the source tarball
    161    the build will break and we will notice that %post %preun and %files
    162    need to be updated.
    163 
    164 That's it.  If something is not clear, have questions or need a review,
    165 feel free to email me at laca (a] sun.com.
    166 
    167 Last updated: 2006-06-02
    168