Namespace Management in GNOME

[Brian Cameron <Brian Cameron Sun COM>]

To continue with the discussion about ARC and GNOME, I thought
it would be useful to share with the community some of the
issues that the ARC has identified with GNOME 2.6, which is
currently going through an ARC review process at Sun.  While
GNOME 2.6 is frozen, some of the issues identified are things
that still apply to the code in current development.

One of the biggest concerns that ARC has about GNOME has to do
with namespace management. The GNOME community does a reasonable
job of managing namespace management within libraries (using
reasonable prefixes like "gtk_" to define which interfaces are
public, for example).  An area where the community could do a
better job of managing namespace management with the file system.

Note that at Sun, a "stable" or "evolving" interface means that
an interface does not change incompatibly from release-to-release.
An "evolving" interface is one that may change, and users who
depend on such interfaces may experience breakage from release-to-
release.

Here are the problems that Sun's ARC has highlighted about
namespace management with the filesystem:

1) Data is stored in directories with names that are too generic

   GNOME currently installs files to directories with generic
   names.  This could cause problems and conflicts with other
   programs that wanted to use directories with the same names.
   ARC prefers to see applications install files into directories
   that separate data files into subdirectories that are clearly
   associated with the product.  For example, using
   /usr/share/gnome/themes or /usr/share/themes/gnome rather
   than /usr/share/themes.  Examples of generic directories where
   GNOME installs files:

   /etc/sound
   /etc/X11	
   /usr/share/idl	
   /usr/share/mime-info
   /usr/share/sgml	
   /usr/share/sounds
   /usr/share/themes

2) Furthermore, GNOME clutters the /usr/share directory with a lot of
   subdirectories that are specific and private to small/minor GNOME
   applications.

   For example /usr/share contains "geyes", "gnect", "gnibbles",
   "gnobots", "gnome-panel", "gnome-panelrc", "gnome-print-2.0",
   "gnome-stones", "gnome-stonesrc*", "gnome-terminal", "metacity",
   "nautilus", "yelp", "gkb", and so on.  ARC feels that GNOME would
   better integrate with the file-system if this clutter were
   organized.  Perhaps GNOME files should install into a directory
   named /usr/share/gnome for subdirectories that are "stable" and
   /usr/share/gnome-private" for subdirectories that are private to
   an application.  This way the file system would be less cluttered,
   there would be less chance of conflict with other programs, and it
   would be more clear to the end-user where they should look if they
   want to find file integration points (places where they might want
   to add sounds, pixmaps, mime-info, glade files, themes, etc.)

3) Mixed standards for binaries and libraries.  Some GNOME binaries
   have the "gnome-" prefix while others have a "g" prefix, and others
   have no prefix.  Likewise, some libraries have "gnome" in their
   name while others do not.  It would be nice if the community used
   some sort of rule system for determining how programs and libraries
   should be named.

4) Files aren't always installed to the most sane location.  For
   example, there are a number of programs that GNOME currently
   installs to /bin that should probably be in /libexec
   (gnome-keyring-daemon for example).  Also there are files like
   /etc/X11/serverconfig, /etc/X11/starthere, and /etc/X11/sysconfig
   which seem to be Nautilus configuration files that have little to
   do with the Xserver and perhaps belong in some other /etc
   subdirectory.  Not sure if that's the best example, but I suspect
   that a review of the file locations would highlight other issues
   as well.

I think I mentioned in an earlier email that when Sun decided
to release GNOME 2.0, we decided to put datadir files for "external"
applications in /usr/share/gnome, and data files for "stable"
applications in /usr/share.

Anyway, because we moved files around, ARC asked us to put
together the attached file, which is our initial attempt at analysing
the purpose of all the directories that GNOME installs into /usr/share
with an attempt to classify them into "external" or "stable/evolving".

It would be useful if people would review this information so that we
can give the best answers in our ARC review process.  You can respond
to me privately to avoid clutter on the list.

I would be interested  in expanding this document into a GEP that
specifies how GNOME could better organize the filesystem to make the
interfaces more clear and usable.  I would also like to expand it so
it also covers files  installed to other locations (/etc, /var, ...).
It would also be useful if anyone could highlight areas where we
have mislabelled stable integration points as "external" or
mislabelled private file locations as "stable".

I realize that these sorts of file naming/location issues could
just be treated as bugs that are handled individually, but I
think first putting together a standards document would make it
easier to work with module maintainers to make the right decisions
about where files should be placed.  That's why I'm suggesting
using the GEP process to define a standard...but if there is a
better mechanism for this sort of thing please let me know.
What I like about the GEP process is that it gives the community
a mechanism for reviewing a proposal and making modifications to
it before it gets approved.  I think it would be similar to
GEP-04 which defines standards for how libraries should be named.

If we could get this figured out, I'd be happy to do the work to
create patches to make GNOME conform to the standard.  It would
make the process of ARCing GNOME in the future much easier for
Sun's GNOME team, and I think it would also be an effort that
would benefit the GNOME product and documentation.

Another issue that would be of interest to me would be to help
make better documentation that highlights the stability level of
the various GNOME interfaces.  Although people within the
community often talk about certain interfaces as being stable,
I do not think that this information is clearly publically
documented anywhere.  It would be nice if a person could go
to developer.gnome.org and see a list of interfaces
(libraries, file locations, etc.) with an indication of
how stable each interface is. This would let the user know
which libraries they can depend upon to be ABI compatible
from release-to-release, which file locations are stable
integration points, etc.

Just to check, I'm not sure that desktop-devel is the best
GNOME alias to use for this sort of dicussion.  I haven't gotten
a testy email from Mark yet, so that's a good sign.  But if
there is a more appropriate mail alias for discussing this sort
of thing, I'm happy to move the discussion there.

--

Brian

Summary:
-------


Dir     Subdir               If Class   GNOME 2.6?
------- -------------------- -------- - ------------------------------------
/etc
	gtk-2.0		     EVOLVING 	OK
	pango		     EVOLVING   OK
	esd.conf	     external   OK
	gconf		     EVOLVING   OK
	scrollkeeper.conf    EVOLVING   OK
/etc/gnome		     EVOLVING   gone (all contents moved)

        bonobo-activation    external   moved to /etc/
	gnome-vfs-2.0        external   moved to /etc/
	gnome-vfs-mime-magic external   moved to /etc/
	sound		     external   moved to /etc/
	X11		     external	moved to /etc/
/usr/share
	aclocal		     external   OK
	applications	     EVOLVING   OK
	gtk-2.0		     EVOLVING   OK
	omf		     external   OK
	pixmaps		     EVOLVING   OK
	scrollkeeper	     external   OK
	sounds		     EVOLVING   OK
	themes		     EVOLVING   OK
	xml		     EVOLVING   OK
	xmodmap		     external   OK
/usr/share/gnome	     EVOLVING   OK
	application-registry external   moved to /usr/share/ (*)
	control-center-2.0   external   moved to /usr/share/
	gedit-2		     external	moved to /usr/share/
	gen_util	     external	moved to /usr/share/
	geyes		     external   moved to /usr/share/
	glade-2		     external   moved to /usr/share/
	gnect		     external   moved to /usr/share/
	gnibbles	     external   moved to /usr/share/
	gnobots2	     external   moved to /usr/share/
	gnome-2.0	     external   moved to /usr/share/
	gnome-about	     external   moved to /usr/share/
	gnome-panel	     external   moved to /usr/share/
	gnome-panelrc	     external   moved to /usr/share/
	gnome-print-2.0	     external	moved to /usr/share/libgnomeprint
	gnome-stones	     external   moved to /usr/share/
	gnome-stonesrc	     external   moved to /usr/share/
	gnome-stonesrc.ko    external   gone
	gnome-terminal	     external   moved to /usr/share/
	gperfmeter	     external   moved to /usr/share/
	gtk-doc		     external   moved to /usr/share/
	idl		     external   moved to /usr/share/
	metacity	     external   moved to /usr/share/
	mime-info	     external   moved to /usr/share/ (*)
	nautilus	     external   moved to /usr/share/
	sgml		     external	moved to /usr/share/
	yelp		     external	moved to /usr/share/
	cursor-fonts	     external	OK
	default.session	     external	OK
	default.wm	     external	OK
	gkb		     external   OK
	help		     external	OK
	libgnomeprint-2.0    external	gone
	panel		     external   OK
	vfolders	     external	OK
	wm-properties	     external   OK

(*) = GNOME 2.0 directory is also searched for backward compatibility


Details of the directories that were moved:
------------------------------------------


  /etc/gnome/bonobo-activation    external   moved to /etc/

        includes 1 config file that is not expected to be hand edited,
	but using bonobo-activation-sysconf

  /etc/gnome/gnome-vfs-2.0        external   moved to /etc/

	private gnome-vfs module config files and global menu
	config files; not an integration directory
	
  /etc/gnome/gnome-vfs-mime-magic external   moved to /etc/

        (file) list of magic patterns used for identifying
	file types; obsoleted by the new mime info data
	in /usr/share/mime

  /etc/gnome/sound		  external   moved to /etc/

        config files for assigning sound files to events.
	used by gtk, games and the mailcheck applet.
	This is an integration directory but, I believe,
	a low priority one.

  /etc/gnome/X11		     external	moved to /etc/

        gdm config files and special launchers for nautilus;
	not an integration directory.

  /usr/share/gnome/application-registry external   moved to /usr/share/ (*)

        Obsolete mime type integration directory maintained for backward
	compatibility.  Both the /usr/share and /usr/share/gnome
        are searched.  (The new directory is /usr/share/mime)

  /usr/share/gnome/control-center-2.0   external   moved to /usr/share/

        This is going away completely in a future GNOME release,
        AFAIK.  The gnome-vfs vfolder files in /etc/gnome-vfs-2.0 can
	be edited to add the old directory into the search path.

  /usr/share/gnome/gedit-2		     external	moved to /usr/share/

        Gedit private data.

  /usr/share/gnome/gen_util	     external	moved to /usr/share/

	Private data of some basic panel applets

  /usr/share/gnome/geyes		     external   moved to /usr/share/

        "Themes" for the geyes applet.  Private.

  /usr/share/gnome/glade-2		     external   moved to /usr/share/

        "autogen.sh" script to be used in sources generated by the
        Glade UI designer tool. Private.

  /usr/share/gnome/gnect		     external   moved to /usr/share/

        private data of the gnect game.

  /usr/share/gnome/gnibbles	     external   moved to /usr/share/

        private data of the gnibbles game.

  /usr/share/gnome/gnobots2	     external   moved to /usr/share/

        private data of the gnobots2 game.

  /usr/share/gnome/gnome-2.0	     external   moved to /usr/share/

        libbonoboui UI definition files (mostly menus for panel
        applets and nautilus views). This is an integration directory
        for applets, Brian already logged CR #6196679.

  /usr/share/gnome/gnome-about	     external   moved to /usr/share/

        private images and text displayed in the gnome-about program

  /usr/share/gnome/gnome-panel	     external   moved to /usr/share/

	private data of the window list and workspace switcher panel
        applets.

  /usr/share/gnome/gnome-panelrc	     external   moved to /usr/share/

        an empty file (comments only) to be used for setting gtk theme
        definitions that only apply to the panel.  ugly hack, imho...

  /usr/share/gnome/gnome-stones	     external   moved to /usr/share/

        private data of the gnome-stones game

  /usr/share/gnome/gnome-stonesrc	     external   moved to /usr/share/

        gtk theme file for the gnome-stones game

  /usr/share/gnome/gnome-terminal	     external   moved to /usr/share/

        private data of the gnome-terminal (glade ui def file)

  /usr/share/gnome/gperfmeter	     external   moved to /usr/share/

	private data of gperfmeter (glade ui def file)

  /usr/share/gnome/gtk-doc		     external   moved to /usr/share/

        generated API docs for the GNOME libraries (HTML)

  /usr/share/gnome/idl		     external   moved to /usr/share/

        Corba IDL files for bonobo component development. pkg-config is
	used to return the location (IDL_FLAGS) for using these so the
	actual location is irrelevant as long as it's consistent with
	the pkgconfig data.

  /usr/share/gnome/metacity	     external   moved to /usr/share/

        Private data (icons and glade ui def files) of the metacity
	window manager.

  /usr/share/gnome/mime-info	     external   moved to /usr/share/ (*)

        Obsolete mime type integration directory maintained for backward
	compatibility.  Both the /usr/share and /usr/share/gnome
        are searched.  (The new directory is /usr/share/mime)
        
  /usr/share/gnome/nautilus	     external   moved to /usr/share/

        Private data of the nautilus file manager. (Images, static
	bookmarks, glade ui definition files, etc.)

  /usr/share/gnome/sgml		     external	moved to /usr/share/

	docbook sgml/xsl stylesheets used by gtk-doc and openjade;
	not an integration directory.

  /usr/share/gnome/yelp		     external	moved to /usr/share/

        private data of the yelp help browser (icons, tables of
        contents, glade ui def files)

  /usr/share/gnome/gnome-print    external	moved to /usr/share/libgnomeprint

        printer model descriptions