--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/configurationengine/doc/plugins/plugin-dir-structure.rst	Thu Mar 11 17:04:37 2010 +0200
@@ -0,0 +1,66 @@
+Plug-in directory structure
+===========================
+
+ConE plug-ins are divided into plug-in "packages", which enables a ConE
+distribution to be built with a specific set of installed plug-ins. There is a ``common``
+package that contains the default plug-ins that are always present in a ConE installation,
+and any other plug-in package provides extra plug-ins in addition to these.
+
+For example, one might build a 'vanilla' ConE distribution which contains only the
+core ConE components and common plug-ins, or a 'symbian' distribution which contains
+those as well as all Symbian-specific plug-ins.
+
+The plug-in packages are simply sub-directories of ``source/plugins``. For example, the
+following shows the current plug-in packages:
+
+  .. image:: plugins-dir.png
+
+As can be seen, there are three plug-in packages (``common``, ``example`` and ``symbian``)
+and several utility Python files.
+
+Package directory structure
+---------------------------
+
+Each plug-in package contains the sources of all plug-ins, an optional integration test set,
+and a Python script to run all test cases related to the plug-in package. For example, the
+following shows the contents of the ``common`` plug-in package:
+
+  .. image:: plugins-common-dir.png
+
+The naming of the sub-directories is important:
+
+- Directories with a name of the form ``Cone*Plugin`` are considered to be plug-in sources
+- If a directory with the name ``integration-test`` exists, it is expected to contain a
+  ``runtests.py`` file that runs the integration tests
+
+Plug-in source directory structure
+----------------------------------
+
+A plug-in source directory is expected to contain two things:
+
+- A single Python module that contains the plug-in sources
+- ``setup.py`` for packaging the plug-in into an egg (``setup.cfg`` and ``makefile`` are related to this)
+
+The following shows the contents of the command plug-in directory in the common package:
+
+  .. image:: plugins-common-commandplugin-dir.png
+
+For an example with more complete descriptions see
+:ref:`here <plugin-howto-example-plugin-dir-structure>`.
+
+Integration test directory structure
+------------------------------------
+
+In addition to a collection of plug-in sources a plug-in package directory may contain an
+``integration-test`` directory. This directory is supposed to contain integration tests
+for the plug-ins by running actions (e.g. generate) using the ConE CLI to test that the plug-ins
+work correctly from the topmost level.
+
+File naming matters here too:
+
+- Files of the form ``unittest_*.py`` are expected to contain the test cases
+- If a file named ``export_standalone.py`` exists, it is expected to contain a function that
+  exports any needed extra data when exporting the integration tests into a standalone test set.
+
+For an example with more complete descriptions see
+:ref:`here <plugin-howto-example-plugin-integration-tests`.
\ No newline at end of file