<?xml version='1.0'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

  <article id="structure" lang="en">
  <articleinfo>
    <title>
      Directory Structure of the <application>GIMP</application> Source Tree
    </title>
    <author>
      <firstname>Sven</firstname>
      <surname>Neumann</surname>
    </author>
    <date>2003</date>
    <abstract>
      <para>
	This document outlines the directory structure of the
	<application>GIMP</application> source tree. It should help
	people to get started with the <application>GIMP</application> code.
      </para>
    </abstract>
  </articleinfo>
  
  <para>
    The <application>GIMP</application> source tree can be divided
    into the core application, libraries, plug-ins, data files and
    some stuff that doesn't fit into these catagories. Here is a list
    of top-level directories:
  </para>
  
  <informaltable>
    <tgroup cols="2" align="left">
      <tbody>
	<row>
	  <entry><filename>app</filename></entry>
	  <entry>
            The source code of the core GIMP application.
          </entry>
	</row>
	<row>
	  <entry><filename>build</filename></entry>
	  <entry>
            This is a virtual CVS module that is only here to assist in
            building <application>GIMP</application> for Windows.
          </entry>
	</row>
	<row>
	  <entry><filename>cursors</filename></entry>
	  <entry>
            Bitmaps that are used to construct cursors used by the various
            <application>GIMP</application> tools.
          </entry>
	</row>
	<row>
	  <entry><filename>data</filename></entry>
	  <entry>
            All sorts of data files like brushes, gradients, patterns as well
            as the splash image and files to integrate
            <application>GIMP</application> into the GNOME desktop.
          </entry>
	</row>
 	<row>
	  <entry><filename>devel-docs</filename></entry>
	  <entry>
            The developers documentation. The file you are looking at (or at
            least the source that was used to generate it) is located here.
          </entry>
	</row>
 	<row>
	  <entry><filename>docs</filename></entry>
	  <entry>
            Documentation for users. The man-pages which get installed with
            the <application>GIMP</application> as well as reference sheets
            for keybindings and other stuff.
          </entry>
	</row>
 	<row>
	  <entry><filename>etc</filename></entry>
	  <entry>
            Configuration files that get installed with the
            <application>GIMP</application>.
          </entry>
	</row>
 	<row>
	  <entry><filename>libgimp</filename></entry>
	  <entry>
            The main <application>GIMP</application> library. It provides the
            API to write plug-ins in the C programming
            language. <application>GIMP</application> itself does not link
            against this library.
          </entry>
	</row>
 	<row>
	  <entry><filename>libgimpbase</filename></entry>
	  <entry>
            Basic functions that are shared by the
            <application>GIMP</application> application and its plug-ins.
          </entry>
	</row>
 	<row>
	  <entry><filename>libgimpcolor</filename></entry>
	  <entry>
            Color-related functionality that is shared by the
            <application>GIMP</application> application and its plug-ins.
          </entry>
	</row>
 	<row>
	  <entry><filename>libgimpmath</filename></entry>
	  <entry>
            A basic set of mathematic operations useful for the the
            <application>GIMP</application> application and its plug-ins.
          </entry>
	</row>
 	<row>
	  <entry><filename>libgimpmodule</filename></entry>
	  <entry>
            A small library that abstracts dynamic loading of modules. This is
            used to implement loadable color selectors and display filters.
          </entry>
	</row>
 	<row>
	  <entry><filename>libgimpwidgets</filename></entry>
	  <entry>
            User interface elements (widgets) and utility functions that are
            shared by the <application>GIMP</application> application and its
            plug-ins.
          </entry>
	</row>
 	<row>
	  <entry><filename>m4macros</filename></entry>
	  <entry>
            m4 macros (well, actually just one) which get installed to help
            automake to detect a GIMP installation. Useful for plug-in
            developers.
          </entry>
	</row>
 	<row>
	  <entry><filename>modules</filename></entry>
	  <entry>
            Color selectors and display filters that can be loaded at
            run-time.
          </entry>
	</row>
 	<row>
	  <entry><filename>plug-ins</filename></entry>
	  <entry>
            This directory and its sub-directories hold all the
            <application>GIMP</application> plug-ins that are part of the main
            <application>GIMP</application> distribution.
          </entry>
	</row>
 	<row>
	  <entry><filename>po</filename></entry>
	  <entry>
            Translations of strings used in the main
            <application>GIMP</application> application.
          </entry>
	</row>
 	<row>
	  <entry><filename>po-libgimp</filename></entry>
	  <entry>
            Translations of strings used in libgimp.
          </entry>
	</row>
 	<row>
	  <entry><filename>po-plug-ins</filename></entry>
	  <entry>
            Translations of strings used in <application>GIMP</application>
            plug-ins.
          </entry>
	</row>
 	<row>
	  <entry><filename>po-script-fu</filename></entry>
	  <entry>
            Translations of strings used in Script-Fu scripts.
          </entry>
	</row>
 	<row>
	  <entry><filename>regexrepl</filename></entry>
	  <entry>
            Code to handle regular expressions in case your C library does not
            suport them. These files will not be used for most builds since
            modern libc implementation have offer support for regular
            expressions.
          </entry>
	</row>
 	<row>
	  <entry><filename>themes</filename></entry>
	  <entry>
            The look of <application>GIMP</application> is themeable to some
            extent. This directory at the moment only holds the default theme
            but more themes might be added in the future.
          </entry>
	</row>
 	<row>
	  <entry><filename>tips</filename></entry>
	  <entry>
            The helpful tips shown at startup are located here together with
            their translations.
          </entry>
	</row>
 	<row>
	  <entry><filename>tools</filename></entry>
	  <entry>
            The source code for some <application>GIMP</application>-related
            tools as well as tools used to build the
            <application>GIMP</application> application.
          </entry>
	</row>
      </tbody>
    </tgroup>
  </informaltable>

  <para>  
    The contents of these directories will be explained in detail in
    the following sections.
  </para>

  <sect1 id="app">
    <title>The <application>GIMP</application> application</title>
    <para>
      The source code of the core <application>GIMP</application>
      application is found in the <filename>app</filename> directory.
    </para>

    <informaltable>
      <tgroup cols="2" align="left">
	<tbody>
	  <row>
	    <entry><filename>app/base</filename></entry>
	    <entry>
	      base functionality such as pixel regions, tiles etc.
	    </entry>
	  </row>
	  <row>
	    <entry><filename>app/paint-funcs</filename></entry>
	    <entry>
	      functions to manipulate pixels, part of the base
	      functionality
	    </entry>
	  </row>
	  <row>
	    <entry><filename>app/compose</filename></entry>
	    <entry>
	      new pixel compositing routines that supersede the code
              in <filename>app/paint-funcs</filename>
	    </entry>
	  </row>
	  <row>
	    <entry><filename>app/config</filename></entry>
	    <entry>
	      handling of config files, provides the GimpConfig
	      interface and the GimpRc object which is used from
	      all over of the application; depends on GObject
	    </entry>
	  </row>
	  <row>
	    <entry><filename>app/core</filename></entry>
	    <entry>
	      the core of the GIMP core, makes heavy use of GObject
              but is not GTK+-dependant
	    </entry>
	  </row>
	  <row>
	    <entry><filename>app/file</filename></entry>
	    <entry>
	      file handling routines, part of the core
	    </entry>
	  </row>
	  <row>
	    <entry><filename>app/paint</filename></entry>
	    <entry>
	      paint core that provides different ways to paint strokes
	    </entry>
	  </row>
	  <row>
	    <entry><filename>app/plug-in</filename></entry>
	    <entry>
	      plug-in handling, part of the core
	    </entry>
	  </row>
	  <row>
	    <entry><filename>app/pdb</filename></entry>
	    <entry>
	      core side of the Procedural Database, exposes internal
	      functionality by means of the PDB
	    </entry>
	  </row>
	  <row>
	    <entry><filename>app/text</filename></entry>
	    <entry>
	      text handling, part of the core
	    </entry>
	  </row>
	  <row>
	    <entry><filename>app/vectors</filename></entry>
	    <entry>
	      vectors framework, part of the core
	    </entry>
	  </row>
	  <row>
	    <entry><filename>app/xcf</filename></entry>
	    <entry>
	      XCF file handling, part of the core
	    </entry>
	  </row>
	  <row>
	    <entry><filename>app/display</filename></entry>
	    <entry>
	      handles displays (e.g. image windows), part of the GUI
	    </entry>
	  </row>
	  <row>
	    <entry><filename>app/tools</filename></entry>
	    <entry>
	      user interface part of the tools as found in the toolbox.
	      The actual tool functionality is in the core
	    </entry>
	  </row>
	  <row>
	    <entry><filename>app/widgets</filename></entry>
	    <entry>
	      a collection of widgets used in the application GUI
	    </entry>
	  </row>
	  <row>
	    <entry><filename>app/gui</filename></entry>
	    <entry>
	      the code that puts the user interface together
	    </entry>
	  </row>

	</tbody>
      </tgroup>
    </informaltable>

  </sect1>

  </article>

