Development

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 https://bitbucket.org/windel/ppci
$ cd ppci
$ sudo python setup.py 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/

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

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/__init__.py

  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 setup.py 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/__init__.py.

  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: