GNOME libraries 2.xx road map

[Miguel de Icaza <miguel gnu org>]

Hello guys,

   You can read my proposal for brining the GNOME libraires to their
next major release (as part of the GNOME 2.0 project) at
http://www.nuclecu.unam.mx/~miguel/gnome-libs-2/

   Comments are welcome.

   Or you can try to read the SGML source code here at the end.

Best wishes,
Miguel.

<!Doctype article PUBLIC "-//Davenport//DTD DocBook V3.0//EN" []>

<article class="techreport" id="programming-guidelines">

  <artheader>
    <title>Upgrading the GNOME libraries for their second major release</title>

    <authorgroup>
      <author>
	<firstname>Miguel</firstname>
	<surname>de Icaza</surname>
	<affiliation>
	  <address>
	    <email>miguel@kernel.org</email>
	  </address>
	</affiliation>
      </author>
    </authorgroup>
    <copyright>
      <year>1999</year>
      <holder>International GNOME Support</holder>
    </copyright>

    <abstract>
      <para>
	In this document I describe the process in which the GNOME
	libraries on the GNOME CVS will be managed for their next
	major release.
      </para>

      <para>
	This document contains the rationale and the precise steps
	that will be taken to acomplish the gnome-libs-2 release.  It
	is a live document, meaning that we will be upgrading its
	contents as time passes. 
      </para>
    </abstract>
  </artheader>

  <sect1 id="major-goals">
    <title>Major goals of the next release</title>

    <para>
      The major goals for the next release of the GNOME core libraries
      include:

      <itemizedlist>
	<listitem>
	  <para>
	    Removal of the Imlib dependency, as it has design
	    problems with its memory management setup.  The code that
	    will replace Imlib exists in the
	    <filename>gdk-pixbuf</filename> CVS module and will be
	    integrated into the GNOME libraries.
	  </para>
	</listitem>

	<listitem>
	  <para>
	    Integration of the asyncronous virtual file system
	    (<filename>gnome-vfs</filename>) written by Ettore. 
	  </para>
	</listitem>

	<listitem>
	  <para>
	    GNOME dialog boxes for common operations: File opening,
	    file saving, file printing.  These dialog boxes will all
	    be dependant on the <filename>gnome-vfs</filename> module,
	    because most new applications will have support for
	    VFS-based files. 
	  </para>
	</listitem>

	<listitem>
	  <para>
	    Source code compatibility.  Applications written against
	    the previous API of the GNOME libraries should continue to
	    work when recompiled with the new libraries.  This should
	    be preserved up to a reasonable point.
	  </para>
	</listitem>

	<listitem>
	  <para>
	    Possibly integrate the GNOME printing architecture into
	    the gnome-libraries, or at least providing the hooks in
	    <filename>gnome-libs</filename> for seemless printing
	    integration. 
	  </para>
	</listitem>

	<listitem>
	  <para>
	    Incorporation of new code that has been written, but we
	    could not include in previous releases for various reasons.
	  </para>
	</listitem>

	<listitem>
	  <para>
	    Incorporation of design fixes and major code overhauls
	    that would have made the gnome-libraries unstable. 
	  </para>
	</listitem>
      </itemizedlist>
    </para>
  </sect1>

  <sect1 id="dependencies">
    <title>Dependencies</title>
    <para>
      The various components that we will be integrating have in some
      cases circular dependencies.  For example, the standard dialog
      boxes might end up using <filename>libglade</filename>, which in
      turn requires the gnomeui library to be compiled before it can
      be used.
    </para>
  </sect1>

  <sect1 id="newcode">
    <title>Integration of new code</title>

    <para>
      We have two types of new code we want to integrate into the
      GNOME libraries: code that is readily available as a released
      package, code that should be part of gnome-libs and code that
      needs to be put in its own library.
    </para>
      
    <para>
      There is a number of code pieces that we want to include in the
      main gnome-libs package that is alredy developed, but was not
      included in the 1.0.xx series.
    </para>

    <para>
      These include the Bezier Path canvas item, Raph Levien's Type1
      font loading code, HackText canvas item.  The canvas items can
      go directly into the <filename>libgnomeui</filename> library.
      While the Type1 font loading is perhaps useful without any
      connection to the user interface, so it might go into its own
      module, perhaps <filename>libtype1</filename> or even a more
      generic <filename>libgnomefont</filename> which would abstract
      font loading and handling for us. 
    </para>

    <para>
      Correct font handling also means that we would have a dependency
      on the <classname>GnomeFont</classname> code in the
      <filename>gnome-print</filename> module.  This is another
      reason for adding a dependency or integrating gnome-print into
      gnome-libs. 
    </para>
  </sect1>

  <sect1 id="fixing-code">
    <title>Fixing existing code</title>
    <para>
      The Canvas has its own branch in which various binary
      incompatible changes have been done to ensure that all canvas
      items do handle the canvas update setup correctly.  These type
      of changes can be incorporated into the main line development
      inmediately. 
    </para>
  </sect1>
  
  <sect1 id="source-compat">
    <title>Deprecated code and source compatibility</title>
    <para>
      Given that we are dropping support for various functions from
      the GNOME libraries and in some cases an entire familiy of
      functions we need to provide a compatibility layer for existing
      code. 
    </para>

    <para>
      To achieve this two new libraries will be created inside the
      <filename>gnome-libs</filename> module called
      <filename>libgnomecompat</filename> and
      <filename>libgnomeuicompat</filename> in which we will move
      (trough careful CVS surgery) the files we are deprecating.  
    </para>

    <para>
      Open for discussion: the current
      <filename>gnome-config</filename> program is usually invoked
      with the gnomeui argument and the user will expect the old
      values.  Do we want to make the "gnomeui" symbol return the
      compatibility libraries as well and create a new "gnomeui2"
      option, or do we want to have a "compat" option as well when
      invoking <filename>gnome-config</filename>
    </para>
    
    <sect2>
      <title>Imlib</title>

      <para>
	We are dropping the Imlib module, and we need to provide both
	ways for existing users of the API to recompile their
	applications in gnome-libs-2 as well as moving our own code
	away from it.
      </para>
	
      <para>
	The module <filename>libgnomeuicompat</filename> will contain
	wrapper functions that will emulate the Imlib routines using
	exclusively code from the <filename>gdk-pixbuf</filename>, the
	<filename>libart_lgpl</filename> and the GdkRGB code in Gdk.
      </para>

      <para>
	Particularly, Gtk+ based applications have had to deal with
	multiple visuals in the past and handle Imlib specially.  The
	<function>gdk_imlib_get_visual</function> and the
	<function>gdk_imlib_get_colormap</function> will just point to
	the GdkRGB equivalents.
      </para>

      <para>
	Moving our code away from Imlib is 
      </para>
      
    </sect2>

    <sect2>
      <title>Deprecated widgets</title>

      <para>
	Various widgets and functions will be moved into the
	<filename>libgnomeui</filename> library and we will have to
	maintain them still for the gnome-libs-2.x release.
      </para>

      <para>
	Here is the list of files: <filename>gtkcauldron.c</filename>,
	<filename>gnome-less.c</filename>,
	<filename>gnome-spell.c</filename>. 
      </para>
    </sect2>
    
    <sect2>
      <title>Code that can be safely removed</title>

      <para>
	There is some code that has few users and we do not think it
	was ever used outside the GNOME project.  We want to remove
	the GnomeGuru widget, GtkTed widget, and the gnome-properties
	code.
      </para>
    </sect2>
  </sect1>

  <sect1 id="new-pieces">
    <title>New code that should be written</title>
    <para>
      Despite the fact that we are integrating a lot of existing code,
      there are a few things that we still need to write

      <itemizedlist>
	<listitem>
	  <para>
	    A pluggable gnome-init replacement that would enable
	    various libraries to be initialized at once, rather than
	    having various versions of the "initialization" code all
	    over the place.  ie, instead of having gnome_init,
	    gnome_CORBA_init, etc, we want a single gnome_init that
	    can initialize more than one package.  We still need to
	    design this and come up with a scheme
	  </para>
	</listitem>

	<listitem>
	  <para>
	    A new activation system that will work without an X
	    connection: basically we have to handle activation of
	    objects in various execution domains: an X-bound execution
	    domain (because Gtk application are bound to a single
	    display, hence all of our GUI CORBA servers are bound to
	    the same X domain);  a user-execution domain for the
	    current host and a system-execution domain for the current
	    host.
	  </para>

	  <para>
	    This code will be initially written in the
	    <filename>bonobo</filename> module, to make the activation
	    code available for people that do not want or can not
	    upgrade to gnome-libs, but still want to work on
	    activation issues.  Given that Bonobo is not frozen and
	    developers know this, there is no problem here.
	  </para>

	  <para>
	    Some of this code has already been written, and we are
	    just waiting for comments from the community to make sure
	    the proposal we posted made sense and people were ok with
	    it
	  </para>
	</listitem>
      </itemizedlist>
      
    </para>
  </sect1>
  
  <sect1 id="migration-path">
    <title>Managing the migration path</title>
    <para>
      If this is not managed properly, we might end up with a very big
      task that we will not be able to finish in a reasonable amount
      of time.  Particulary, we do not want all applications to be
      changed overnight to the new API, nor to depend on an unreleased
      gnome-libs package for them to work.
    </para>

    <para>
      We also can assume that most users will be interested in trying
      to run the productivity applications of GNOME without having to
      install the experimental version of the libraries.  We also have
      to assume that developers will want to develop applications that
      users can inmediately test, and not test within our time-line
      for releasing the GNOME libraies.
    </para>
    
    <para>
      To minimize these problems, I suggest that if at all possible,
      the various new libraries and components that  will be
      integrated in the GNOME libraries is made readily available for
      other developers to use as separate packages.  This is already
      the case for GConf, Bonobo, the GNOME VFS, and GNOME-print.
    </para>

    <para>
      So even if they will be fully integrated in the gnome-libs-2
      package, they will be available for use as independent packages
      in the meantime.  And this is solely targeted at enabling
      developers to ship and develop without having to install a very
      experimental branch of the gnome-libs code.
    </para>
  </sect1>

  <sect1 id="policies">
    <title>Policies on new code integrated</title>

    <para>
      We learned an painful lesson in the gnome-libs-1.0 series and
      with Gtk.  We need to document the code as soon as it gets
      written.
    </para>

    <para>
      All new code that is added to the new gnome-libs should be fully
      API documented, and hopefully the tmpl files should be commited
      at the same time the initial code is imported into the
      libraries.
    </para>

    <para>
      This is necessary if we want to get developers to adopt the
      GNOME libraries for their work, and it will also reduce the
      long-term problems of the library.
    </para>
  </sect1>
  
  <sect1 id="time-frame">
    <title>Release time frame</title>

    <para>
      Here is a time frame for the various things that must be worked
      on:

      <itemizedlist>
	<listitem>
	  <para>
	    gnome-libs branching as soon as 1.0.50 has been officially
	    released. 
	  </para>
	</listitem>
      </itemizedlist>
    </para>
  </sect1>
  
</article>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->