1 Plug-in directory structure

     2 ===========================

     3 

     4 ConE plug-ins are divided into plug-in "packages", which enables a ConE

     5 distribution to be built with a specific set of installed plug-ins. There is a ``common``

     6 package that contains the default plug-ins that are always present in a ConE installation,

     7 and any other plug-in package provides extra plug-ins in addition to these.

     8 

     9 For example, one might build a 'vanilla' ConE distribution which contains only the

    10 core ConE components and common plug-ins, or a 'symbian' distribution which contains

    11 those as well as all Symbian-specific plug-ins.

    12 

    13 The plug-in packages are simply sub-directories of ``source/plugins``. For example, the

    14 following shows the current plug-in packages:

    15 

    16   .. image:: plugins-dir.png

    17 

    18 As can be seen, there are three plug-in packages (``common``, ``example`` and ``symbian``)

    19 and several utility Python files.

    20 

    21 Package directory structure

    22 ---------------------------

    23 

    24 Each plug-in package contains the sources of all plug-ins, an optional integration test set,

    25 and a Python script to run all test cases related to the plug-in package. For example, the

    26 following shows the contents of the ``common`` plug-in package:

    27 

    28   .. image:: plugins-common-dir.png

    29 

    30 The naming of the sub-directories is important:

    31 

    32 - Directories with a name of the form ``Cone*Plugin`` are considered to be plug-in sources

    33 - If a directory with the name ``integration-test`` exists, it is expected to contain a

    34   ``runtests.py`` file that runs the integration tests

    35 

    36 Plug-in source directory structure

    37 ----------------------------------

    38 

    39 A plug-in source directory is expected to contain two things:

    40 

    41 - A single Python module that contains the plug-in sources

    42 - ``setup.py`` for packaging the plug-in into an egg (``setup.cfg`` and ``makefile`` are related to this)

    43 

    44 The following shows the contents of the command plug-in directory in the common package:

    45 

    46   .. image:: plugins-common-commandplugin-dir.png

    47 

    48 For an example with more complete descriptions see

    49 :ref:`here <plugin-howto-example-plugin-dir-structure>`.

    50 

    51 Integration test directory structure

    52 ------------------------------------

    53 

    54 In addition to a collection of plug-in sources a plug-in package directory may contain an

    55 ``integration-test`` directory. This directory is supposed to contain integration tests

    56 for the plug-ins by running actions (e.g. generate) using the ConE CLI to test that the plug-ins

    57 work correctly from the topmost level.

    58 

    59 File naming matters here too:

    60 

    61 - Files of the form ``unittest_*.py`` are expected to contain the test cases

    62 - If a file named ``export_standalone.py`` exists, it is expected to contain a function that

    63   exports any needed extra data when exporting the integration tests into a standalone test set.

    64 

    65 For an example with more complete descriptions see

    66 :ref:`here <plugin-howto-example-plugin-integration-tests`.