This chapter descibes how to develop on ppci.

Source code

The sourcecode repository of the project is located at these locations:

To check out the latest code and work use the development version use these commands to checkout the source code and setup ppci such that you can use it without having to setup your python path.

$ mkdir HG
$ cd HG
$ hg clone
$ cd ppci
$ sudo python develop

Alternatively a git mirror is also created:

Coding style

All code is intended to be pep8 compliant. You can use the pep8 tool, or run:

$ tox -e flake8

This will check the code for pep8 violations.

Future work includes using pylint and mypy for more static code analysis.

Running the testsuite

To run the unit tests with the compiler, use pytest:

$ python -m pytest -v test/

Or use the unittest module:

$ python -m unittest discover -s test

Or, yet another way, use tox:

$ tox -e py3

In order to test ppci versus different versions of python, tox is used. To run tox, simply run in the root directory:

$ tox

Long tests

There are a series of test snippets located in the test/samples folder. If you want to run these, you can use this:

$ LONGTESTS=1 python -m pytest test/

Some targets need iverilog to emulate a certain processor. If you want to run these, use this:

$ LONGTESTS=1 IVERILOG=1 python -m pytest test/


If some part is slow, it can be handy to run a profiler. To do this, run the slow script with the cProfile. The output can be viewed with pyprof2calltree.

$ python -m cProfile -o profiled.out
$ pip install pyprof2calltree
$ pyprof2calltree -i profiled.out -k


Sometimes, the python interpreter might crash due to playing with dynamically injected code. To debug this, we can use gdb for example.

$ gdb --args python
(gdb) run

Once the program crashes, one can disassemble and print info:

(gdb) bt
(gdb) disassemble /r 0x7fff000, 0x7fff200
(gdb) info registers

3rd party test suites

There exist many different compiler validation suites. Some of them are pure validation sets, others are part of a compiler toolchain. In order to use these test suites, a series of test suite adapter files exists.

Available test adapters:

  • mcpp (set MCPP_DIR) test/lang/c/
  • wasm spec (set WASM_SPEC_DIR) test/wasm/
  • fortran compiler validation system 2.1 (set FCVS_DIR) test/lang/fortran/

To run for example wasm test spec tests:

$ WASM_SPEC_DIR=~/GIT/spec python -m pytest test/wasm/test_suite_full -v

Building the docs

The docs can be build locally by using sphinx. Sphinx can be invoked directly:

$ cd docs
$ sphinx-build -b html . build

Alternatively the tox docs environment can be used:

$ tox -e docs

Directory structure

  • ppci : source code of the ppci library
    • lang : human readable languages
      • c : c frontend
      • c3 : c3 frontend
      • python : python compilation code
      • tools : language tools
    • arch : different machine support
      • arm : arm support
      • avr : avr support
      • mips
      • msp430 : msp430 support
      • stm8
      • xtensa : xtensa support
    • cli : command line interface utilities
    • util : utilities
  • docs : documentation
  • examples : directory with example projects
  • test : tests

Release procedure

This is more a note to self section on how to create a new release.

  1. Determine the version numbers of this release and the next.

  2. Switch to the release branch and merge the default branch into the release branch.

    $ hg update release
    $ hg merge default
    $ hg commit
  3. Check the version number in ppci/

  4. Make sure all tests pass and fix them if not.

    $ tox
  5. Tag this release with the intended version number and update to this tag.

    $ hg tag x.y.z
    $ hg update x.y.z
  6. Package and upload the python package. The following command creates a tar gz archive as well as a wheel package.

    $ python sdist bdist_wheel upload
  7. Switch back to the default branch and merge the release branch into the default branch.

    $ hg update default
    $ hg merge release
    $ hg commit
  8. Increase the version number in ppci/

  9. Update docs/changelog.rst

Continuous integration

The compiler is tested for linux:

and for windows:

Code metrics

Code coverage is reported to the codecov service:

Other code metrics are listed here: