diff -r 000000000000 -r 2e8eeb919028 configurationengine/doc/intro.rst --- /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: + +* ``install.cmd /path/to/install common`` +* *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`` + * ``export_bat.cmd /path/to/tests common`` + * *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`` + * ``run_bat.cmd /path/to/tests common`` + * *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`` + +