source: main/waeup.sirp/trunk/src/waeup/sirp/doc/developernotes.txt @ 4978

Last change on this file since 4978 was 4978, checked in by uli, 15 years ago

Fix package names and svn download path.

File size: 8.1 KB
Line 
1Developer Notes
2***************
3
4How to setup a developer instance of the WAeUP SIRP, handle tests, docs
5etc.
6
7The new WAeUP SIRP is based on `Grok <http://grok.zope.org/>`_.
8
9Installing a developer copy
10===========================
11
12The installation is described for Linux-based computers.
13
14Preparing the system
15--------------------
16
17To create a working copy of the WAeUP SIRP we recommend use of
18`virtualenv`. You, however, need also some basic libraries, a C
19compiler and some things more.
20
21What you need (Debian/Ubuntu package names in brackets):
22
23* Python 2.5 (python2.5)
24
25  Currently, also Python2.4 is supported but we want to make use of
26  some of the 2.5 goodies in the future.
27
28
29* Python 2.5 development files (python2.5-dev)
30
31* A C-Compiler (gcc)
32
33* The C library development files (libc6-dev)
34
35* A subversion client (svn)
36
37* enscript (enscript) [optional]
38
39  This is only needed if you want test coverage reports.
40
41All these packages can be installed on Debian systems like this::
42
43  # apt-get install python2.5 python2.5-dev python2.5-dbg \
44                    gcc libc6-dev svn enscript
45
46Afterwards you should be able to enter::
47
48  $ python2.5
49
50at the commandline and get a Python prompt. Quit the interpreter
51pressing <CTRL-D>.
52
53Installing `virtualenv`
54-----------------------
55
56We recommend use of `virtualenv` to create Python sandboxes where you
57can run your code without touching any other installations.
58
59If you don't already have ``easy_install`` available, you can find the
60script to set it up on the `PEAK EasyInstall page`_.
61
62.. _`PEAK EasyInstall page`: http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install
63
64You need to download `ez_setup.py`_. Then, you run it like this to
65install ``easy_install`` into your system Python::
66
67  $ sudo python2.5 ez_setup.py
68
69.. _`ez_setup.py`: http://peak.telecommunity.com/dist/ez_setup.py
70
71This will make ``easy_install`` available to you.
72
73.. note:: Sometimes you have ``easy_install`` installed but you need a
74          newer version of the underlying setuptools infrastructure to
75          make Grok work. You can upgrade setuptools with::
76
77            $ sudo easy_install -U setuptools
78
79Now you can install `virtualenv` by doing (as root)::
80
81  # easy_install-2.5 virtualenv
82
83This step will fetch all needed sources from the internet and install
84`virtualenv` locally in your Python2.5 installation.
85
86
87Creating a sandbox
88------------------
89
90This step is only necessary (and recommended) if you installed
91`virtualenv` before.
92
93As a normal user you now can create a sandbox for your upcoming work
94by::
95
96  $ virtualenv --no-site-packages mysandbox
97
98where ``mysandbox`` is a directory in the filesystem where your
99sandbox will be created. `virtualenv` will also create this directory
100for you.
101
102By passing the ``no-site-packages`` switch we tell `virtualenv` to
103provide us a clean environment without any extra-packages installed
104systemwide.
105
106If you have a look into the freshly created sandbox, you will notice
107that in the ``bin/`` directory there is also
108
109You now can activate the sandbox by doing::
110
111  $ source mysandbox/bin/activate
112
113You will notice that the input prompt changes.
114
115To deactivate the sandbox at any time, enter::
116
117  $ deactivate
118
119and the prompt will be the same as before the activation.
120
121For the following steps make sure the sandbox is active.
122
123
124Creating a working place
125------------------------
126
127In the sandbox (or anywhere else) we now create our real working
128environment. To do this, we change to the sandbox and checkout the
129sources of the WAeUP SIRP from the subversion server::
130
131  $ cd mysandbox/
132  $ svn co https://svn.waeup.org/repos/main/waeup.sirp/trunk waeup-trunk
133
134where ``waeup-trunk`` is only a name we've chosen here to make clear
135where the sources come from.
136
137This command should fetch the sources of the WAeUP sources for you and
138put it in the directory ``waeup-trunk/``.
139
140Now enter the new directory::
141
142  $ cd waeup-trunk
143
144
145Preparing the build
146-------------------
147
148In the sources directory (``waeup-trunk/``) you have to prepare the
149project to fetch needed components (eggs), compile C-code parts,
150etc. This steip will not touch any external projects::
151
152  $ python2.5 bootstrap.py
153
154This will generate some directories and the ``buildout`` script in
155``bin/`` for us. This step must be executed only once for each
156instance.
157
158Now we can do the real build by triggering::
159
160  $ bin/buildout
161
162If this is your first install of some Grok-related project, this step
163will need some time as lots of sources have to be fetched, many
164components must be compiled, etc.
165
166This step must be redone whenever you change something in
167``buildout.cfg`` or ``setup.py``.
168
169Afterwards we are ready to go.
170
171
172Start the instance
173------------------
174
175You should be able now to start the created instance by doing::
176
177   $ bin/zopectl fg
178
179If you now point a browser to::
180
181   localhost:8080
182
183you should get a login pop-up, where you can login as superuser with
184``grok`` and ``grok`` as username/password.
185
186If you want to change the default credentials, have a look into
187``buildout.cfg`` where the superuser password is determined.
188
189You can stop the instance by pressing <CTRL-C>.
190
191
192
193Documentation
194=============
195
196With the :mod:`waeup.sirp` package we try to reach high standards in
197both, documentation and testing.
198
199:mod:`waeup.sirp` makes extensive use of doctests, which this way also
200become both: executable (i.e. testable) examples and documentation.
201
202Generating documentation
203------------------------
204
205We use the excellent `Sphinx <http://sphinx.pocoo.org/>`_ Python
206documentation generator to generate the docs as HTML pages.
207
208The documentation of the :mod:`waeup.sirp` project can easily be
209created doing::
210
211  $ bin/waeupdocs
212
213This will create a tree of HTML pages in
214``parts/waeupdocs/waeup.sirp/build/waeup.sirp/`` which you can for
215instance browse by pointing your browser to this location.
216
217An 'official' place in internet for the whole docs is about to come
218but not yet available.
219
220
221Writing documentation
222---------------------
223
224means explaining to other developers what your code does and test it
225at the same time. See the many .txt files in the :mod:`waeup.sirp`
226package for examples.
227
228
229Testing
230=======
231
232Tests are most important to the reliability of the :mod:`waeup.sirp`
233package. We don't tell someone that our code works, if we cannot prove
234it. And we prove it by testing.
235
236Running tests
237-------------
238
239You can run all the tests for the package by doing::
240
241  $ bin/test
242
243If you like colored output (can improve readability of failure
244messages), use the ``-c`` switch::
245
246  $ bin/test -c
247
248We have many tests in the :mod:`waeup.sirp` package so that sometimes
249you only want the functional *or* the unit tests to run. This can be
250done like this::
251
252  $ bin/test -c -u
253
254if you want only unit tests or like this::
255
256  $ bin/test -c -f
257
258if you only want functional tests.
259
260
261Writing tests
262-------------
263
264Is a wiiide topic. For now, please see the numerous .txt files in the
265source. Most of the **are** tests.
266
267Code coverage
268-------------
269
270We want to make sure, that all aspects of our software are
271tested. This means, that all parts of the codes should be tested
272somewhere.
273
274To tell how good our test coverage is, we can also use the testrunner
275(``bin/test``)::
276
277  $ bin/test --coverage=coverage
278
279will run the tests but also look, which parts of code were touched by
280them. For releases we want 100% coverage. Beware: running tests with
281the ``--coverage`` switch slows down tests by factor 10 or more.
282
283The command above will output a table with percentages. Furthermore,
284in ``/parts/test/coverage`` you will (after the testrun) find your
285sources preceeded by markers which tell, how often (or none) a certain
286line was used in tests.
287
288To have a more convenient cmdline interface, we also provide some
289shortcuts::
290
291  $ bin/coverage-detect
292
293will run all the tests as shown above and put the results in
294``parts/coverage-detect/coverage``.
295
296After that you can run::
297
298  $ bin/coverage
299
300to get a browsable HTML representation of test coverage in
301``parts/coverage-detect/coverage/report``.
302
303Both, the coverage reports and HTML documentation generated by sphinx
304can be packed and put onto a website as-is.
305
306It is also possible to generate the docs and reports nightly by a
307buildbot or something like this.
Note: See TracBrowser for help on using the repository browser.