--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/configurationengine/doc/intro.rst Thu Mar 11 17:04:37 2010 +0200
@@ -0,0 +1,173 @@
+Introduction
+============
+
+ConE installation offers three different use scenarios of the tool.
+
+#. ConE API (read, write)
+#. ConE plugin API (A plugin interface to add functionality to ConE)
+#. ConE command line interface (tools/utilities that use the API)
+
+ConE API
+--------
+The ConE API tries to offer a simple way to access the configurations inside the Configuration
+project. The concepts of confml and the Configuration project are quite complicated, but the API
+simplifies the project quite a bit to enable effective programming. Although the API aims for
+simplicity, everything is made available via the API.
+The API is described in this document with python api documentation tool *epydoc*.
+
+ConE plugin API
+---------------
+The purpose of the plugin API is to offer the possibility to expand the functionality of Configuration project. Normal use case
+is an implementation plugin which reads data from the configuration and transforms it into some other form
+(e.g. centralrepository text file).
+
+ConE command line interface
+---------------------------
+The main purpose of ConE is to offer the above APIs, but ConE installation as tool
+offers also set of command line utilities that can used to modify, read and utilize (generate other output files
+with implementation plugins) from a Configuration project. These utilities lie on the cone-script package and
+are described in the ConE command line interface section.
+
+Installation
+------------
+
+Requirements
+^^^^^^^^^^^^
+
+ConE installation requires:
+
+* Python 2.5 (though 2.6 probably works too)
+* Ant (Required for installing from source)
+* Python setuptools - http://pypi.python.org/pypi/setuptools. (Required to install ConE as part of python)
+
+ConE can be installed in two different ways:
+
+1. In the Python environment under site-packages like any other Python package
+
+ - Makes it possible to use the ConE API from Python scripts
+
+2. As a standalone installation in a separate directory
+
+ - Contains the CLI and a set of plug-ins
+
+Installing from source
+^^^^^^^^^^^^^^^^^^^^^^
+
+In order to install from source, you obviously need to first get the ConE sources:
+
+* Clone the Mercurial repository:
+
+ * ``hg clone https://developer.symbian.org/sfl/MCL/sftools/depl/swconfigmdw/``
+
+* -- or -- checkout from SVN (if you are in Nokia intranet):
+
+ * ``svn checkout https://trace1.isource-nokia.nokia.com/isource/svnroot/cone/trunk cone_src``
+
+**Installing under site-packages**
+
+Simply install using ``setup.py`` like for any Python package:
+
+* ``cd cone_src/source``
+* ``python setup.py install``
+
+This will install the ConE core module into your Python environment. To install a plug-in,
+do the same in the desired plug-in's source directory (e.g. ``cone_src/plugins/common/ConeRulePlugin``).
+
+**Installing the standalone ConE**
+
+The normal installation in windows environment creates a directory containing the needed
+libraries and ConE plug-ins, and a ``cone.cmd`` wrapper script. The directory can then
+be added somewhere into your PATH, and then the CLI can be used by running ``cone``.
+
+To install, run:
+
+* <windows> ``install.cmd /path/to/install common``
+* <linux> *Not available yet*
+
+Notice the parameter ``common`` in the install command. This specifies the plug-in package to install.
+It can be omitted, in which case it defaults to ``common``. Replace this with e.g. ``symbian`` to create
+a Symbian-specific ConE installation.
+
+.. note::
+ Currently the standalone installation is Windows-specific in the sense that only a batch file
+ wrapper (``cone.cmd``) is included and some Symbian-specific plug-ins have dependencies to
+ Windows applications and Python libraries with native components. However, the ``common``
+ plug-in package should contain only pure Python, so it should work in Unix. Also, a ``cone.sh``
+ script is available under ``source/``, which can be used to replace ``cone.cmd`` in Unix.
+
+Install from ZIP
+^^^^^^^^^^^^^^^^
+
+Fetch the latest ConE build from our CruiseControl build server (works only in Nokia intranet):
+
+* Goto http://trwec021.nmp.nokia.com:8080/buildresults/cone-build
+* Click on the Build Artifacts to get the latest build. Older builds are also available for some time.
+* Download the zip file
+
+The ZIP file should contain a pre-built standalone installation described in the previous section.
+Simply unzip it where you please.
+
+
+.. _installation-export-tests:
+
+Standalone test set
+^^^^^^^^^^^^^^^^^^^
+
+A standalone ConE installation can be tested using an automated standalone test set, which tests the
+ConE CLI functionality. Like the ``install`` command, exporting the test set also needs to
+be given the plug-in package name (it wouldn't make much sense to test a Symbian ConE
+installation using a Maemo-specific test set).
+
+* Export the test set:
+
+ * ``cd cone_src``
+ * <windows> ``export_bat.cmd /path/to/tests common``
+ * <linux> *Not available yet*
+
+
+.. warning::
+ The path specified as the target path will be cleared before the actual
+ export takes place, so be sure not to pass anything like C:\\ there.
+
+* Run the test set:
+
+ * Copy the ConE installation to test into ``/path/to/tests/cone/``
+ * ``cd /path/to/tests``
+ * ``runtests.cmd``
+
+You can also run the tests so that a standalone ConE installation is built and then tested
+with its corresponding test set:
+
+ * ``cd cone_src``
+ * <windows> ``run_bat.cmd /path/to/tests common``
+ * <linux> *Not available yet*
+
+If you simply want to test that ConE works correctly on your machine, you can
+also run:
+
+ * ``ant test``
+
+This will export the test set, install ConE and run the tests inside a temporary
+build directory in the working copy.
+
+Build and install debian packages (Maemo)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ 1. Install tools and cone dependencies, as root or with sudo.
+
+ * ``sudo apt-get install dpkg-dev fakeroot python-setuptools python-central``
+
+ 2. Build python-cone and cone-tool. The packages are placed in parent directory.
+
+ * ``cd cone/trunk``
+ * ``dpkg-buildpackage -rfakeroot -b``
+
+ 3. Install the binary packages, as root or with sudo.
+
+ * ``sudo dpkg -i ../python-cone*.deb ../cone-tool*.deb``
+
+ 4. Install Jinja2 (not part of all Debian-based distros)
+
+ * ``sudo easy_install Jinja2``
+
+