DEVELOPMENT.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

# Awlsim development notes


## Unit tests

The unit test suite can be run with the invocation of the command `./tests/run.sh`. This will run all unit tests and show the results.
Please see `./tests/run.sh --help` for more options.


### Code coverage tracing

To run a code statement coverage trace during unit testing the option `./tests/run.sh --coverage` is available. The results will be stored in `./code-coverage-report/`. It is desired to have a reasonable code coverage of the unit tests. All main code paths should be covered.


## Special annotations in the source code

In order to support both compiling the Awlsim core with Cython and running the same code in a plain Python interpreter without compilation, a method to patch the files is required. The setup.py scrips patch each .py source file and create a .pyx file before starting Cython compilation. The Cython patching mechanism rewrites all `import`s to import the compiled Cython modules instead of the plain Python modules. In addition to that some special comments are provided as hint to the Cython patcher:

* `#@cy` : Enable (un-comment) this line during Cython patching.
* `#@cy2` : Enable (un-comment) this line during Cython patching, if compiling for Python 2.
* `#@cy3` : Enable (un-comment) this line during Cython patching, if compiling for Python 3.
* `#@cy-posix` : Enable (un-comment) this line during Cython patching, if compiling for a Posix platform.
* `#@cy-win` : Enable (un-comment) this line during Cython patching, if compiling for a Windows platform.
* `#@nocy` : Disable (comment) this line during Cython patching.
* `#@no-cython-patch` : Do not touch this line during cython patching.
* `#+NoneToNULL` : Transform all `None` keywords in this line into `NULL`.
* `#+cimport` : Transform all `import` keywords in this line into `cimport`.
* `#+cdef` : Add a `cdef` to this line. For functions or methods that means to change `def` into `cdef` in the function signature. For classes that means to change `class` to `cdef class`.
* `#+cpdef` : Same as `#+cdef`, but add `cpdef` instead.
* `#+cdef-foobar-bizz` : Same as `#+cdef`, but also add the additional words `foobar bizz` after `cdef`. Arbitrary words may be specified and the number of words is not limited. The dash `-` will be transformed into a space character.
* `#+likely` : Mark an `if` condition as being likely to evaluate to True. This annotation can only be used in lines with an `if` statement. It helps the C compiler to generate better machine code.
* `#+unlikely` : Mark an `if` condition as being unlikely to evaluate to True. This annotation can only be used in lines with an `if` statement. It helps the C compiler to generate better machine code.
* `#+suffix-u` : Add an `u` suffix to all decimal and hexadecimal immediates in the line.
* `#+suffix-LL` : Add an `L` suffix to all decimal and hexadecimal immediates in the line.

To disable code coverage tracing an additional special comment is provided:

* `#@nocov` : This excludes the line from Python `coverage` tracing.