Developer Notes *************** How to setup a developer instance of the WAeUP.Kofa, handle tests, docs etc. The new WAeUP.Kofa is based on `Grok `_. Installing a developer copy =========================== The installation is described for Linux-based computers. Preparing the system -------------------- To create a working copy of the WAeUP.Kofa we recommend use of `virtualenv`. You, however, need also some basic libraries, a C compiler and some things more. What you need (Debian/Ubuntu package names in brackets): * Python 2.6 (python2.6) Currently, also Python2.5 is supported but we want to make use of some of the 2.6 goodies in the future. * Python 2.6 development files (python2.6-dev) * A C-Compiler (gcc) * The C library development files (libc6-dev) * A subversion client (svn) * enscript (enscript) [optional] This is only needed if you want test coverage reports. All these packages can be installed on Debian systems like this:: # apt-get install python2.6 python2.6-dev python2.6-dbg \ gcc libc6-dev svn enscript Afterwards you should be able to enter:: $ python2.6 at the commandline and get a Python prompt. Quit the interpreter pressing . Installing `virtualenv` ----------------------- We recommend use of `virtualenv` to create Python sandboxes where you can run your code without touching any other installations. If you don't already have ``easy_install`` available, you can find the script to set it up on the `PEAK EasyInstall page`_. .. _`PEAK EasyInstall page`: http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install You need to download `ez_setup.py`_. Then, you run it like this to install ``easy_install`` into your system Python:: $ sudo python2.6 ez_setup.py .. _`ez_setup.py`: http://peak.telecommunity.com/dist/ez_setup.py This will make ``easy_install`` available to you. .. note:: Sometimes you have ``easy_install`` installed but you need a newer version of the underlying setuptools infrastructure to make Grok work. You can upgrade setuptools with:: $ sudo easy_install -U setuptools Now you can install `virtualenv` by doing (as root):: # easy_install-2.6 virtualenv This step will fetch all needed sources from the internet and install `virtualenv` locally in your Python2.6 installation. Creating a sandbox ------------------ This step is only necessary (and recommended) if you installed `virtualenv` before. As a normal user you now can create a sandbox for your upcoming work by:: $ virtualenv --no-site-packages mysandbox where ``mysandbox`` is a directory in the filesystem where your sandbox will be created. `virtualenv` will also create this directory for you. By passing the ``no-site-packages`` switch we tell `virtualenv` to provide us a clean environment without any extra-packages installed systemwide. If you have a look into the freshly created sandbox, you will notice that in the ``bin/`` directory there is also You now can activate the sandbox by doing:: $ source mysandbox/bin/activate You will notice that the input prompt changes. To deactivate the sandbox at any time, enter:: $ deactivate and the prompt will be the same as before the activation. For the following steps make sure the sandbox is active. Creating a working place ------------------------ In the sandbox (or anywhere else) we now create our real working environment. To do this, we change to the sandbox and checkout the sources of the WAeUP.Kofa from the subversion server:: $ cd mysandbox/ $ svn co https://svn.waeup.org/repos/main/waeup.kofa/trunk waeup-trunk where ``waeup-trunk`` is only a name we've chosen here to make clear where the sources come from. This command should fetch the sources of the WAeUP sources for you and put it in the directory ``waeup-trunk/``. Now enter the new directory:: $ cd waeup-trunk Preparing the build ------------------- In the sources directory (``waeup-trunk/``) you have to prepare the project to fetch needed components (eggs), compile C-code parts, etc. This steip will not touch any external projects:: $ python2.6 bootstrap.py This will generate some directories and the ``buildout`` script in ``bin/`` for us. This step must be executed only once for each instance. Now we can do the real build by triggering:: $ bin/buildout If this is your first install of some Grok-related project, this step will need some time as lots of sources have to be fetched, many components must be compiled, etc. This step must be redone whenever you change something in ``buildout.cfg`` or ``setup.py``. Afterwards we are ready to go. Start the instance ------------------ You should be able now to start the created instance by doing:: $ bin/zopectl fg If you now point a browser to:: localhost:8080 you should get a login pop-up, where you can login as superuser with ``grok`` and ``grok`` as username/password. If you want to change the default credentials, have a look into ``buildout.cfg`` where the superuser password is determined. You can stop the instance by pressing . Documentation ============= With the :mod:`waeup.kofa` package we try to reach high standards in both, documentation and testing. :mod:`waeup.kofa` makes extensive use of doctests, which this way also become both: executable (i.e. testable) examples and documentation. Generating documentation ------------------------ We use the excellent `Sphinx `_ Python documentation generator to generate the docs as HTML pages. The documentation of the :mod:`waeup.kofa` project can easily be created doing:: $ bin/waeupdocs This will create a tree of HTML pages in ``parts/waeupdocs/waeup.kofa/build/waeup.kofa/`` which you can for instance browse by pointing your browser to this location. An 'official' place in internet for the whole docs is about to come but not yet available. Writing documentation --------------------- means explaining to other developers what your code does and test it at the same time. See the many .txt files in the :mod:`waeup.kofa` package for examples. Testing ======= Tests are most important to the reliability of the :mod:`waeup.kofa` package. We don't tell someone that our code works, if we cannot prove it. And we prove it by testing. Running tests ------------- You can run all the tests for the package by doing:: $ bin/test If you like colored output (can improve readability of failure messages), use the ``-c`` switch:: $ bin/test -c We have many tests in the :mod:`waeup.kofa` package so that sometimes you only want the functional *or* the unit tests to run. This can be done like this:: $ bin/test -c -u if you want only unit tests or like this:: $ bin/test -c -f if you only want functional tests. Writing tests ------------- Is a wiiide topic. For now, please see the numerous .txt files in the source. Most of the **are** tests. Generally, we use `z3c.testsetup` for finding and setting up tests. There are mainly two kinds of tests we use: * unit- or simple doctests These are included in test runs automatically, if they provide a marker like this somewhere (normally near top of file):: .. :doctest: Most unit tests furthermore declare that they want to be run inside the `WAeUPKofaUnitTestLayer` defined in `waeup.kofa.testing`. This layer groks the whole `waeup.kofa` package, so that all ZCA components are already setup when you start your tests. To declare that a unit test testfile should be run inside this layer, the testfile has to provide the following line:: .. :layer: waeup.kofa.testing.WAeUPKofaUnitTestLayer Use it, if in your tests you make use of registered components like utilities, adapters and the like. * integration or functional tests These provide a full-blown ZODB storage, so that we can emulate browser requests to the whole system. Functional tests are much more expensive in terms of memory and runtime but needed, if you want to test UI components. A testfile is registered as functional test on testruns when it provides a line like the following:: :Test-Layer: functional Code coverage ------------- We want to make sure, that all aspects of our software are tested. This means, that all parts of the codes should be tested somewhere. To tell how good our test coverage is, we can also use the testrunner (``bin/test``):: $ bin/test --coverage=coverage will run the tests but also look, which parts of code were touched by them. For releases we want 100% coverage. Beware: running tests with the ``--coverage`` switch slows down tests by factor 10 or more. The command above will output a table with percentages. Furthermore, in ``/parts/test/coverage`` you will (after the testrun) find your sources preceeded by markers which tell, how often (or none) a certain line was used in tests. To have a more convenient cmdline interface, we also provide some shortcuts:: $ bin/coverage-detect will run all the tests as shown above and put the results in ``parts/coverage-detect/coverage``. After that you can run:: $ bin/coveragereport to get a browsable HTML representation of test coverage in ``coverage-report/`` subdir. Both, the coverage reports and HTML documentation generated by sphinx can be packed and put onto a website as-is. It is also possible to generate the docs and reports nightly by a buildbot or something like this.