awlsim/DEVELOPMENT.md

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