# 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.