1. Jacques Dafflon
  2. ComPyLL

Overview

HTTPS SSH

ComPyLL

A Compiler from Python to LLVM, written in Python.

Credits

Usage

The compiler only support a subset of Python, defined as P0.

The compiler takes the path to a program to compile and outputs the result to the standard output. The compiled program is in LLVM assembly language. In order to run it, it needs to be transform into an object file. In addition the compyll_lib.a in the ComPyLL/clib folder needs to be compiled as well. With both object files, the programm can be compiled and run.

The steps below demonstrate the above procedure to run a program called program.py

  1. Generate the compyll_lib.a static library.

    $ make -C CompPyLL/clib lib
    
  2. Compile program.py ot the LLLVM assembly language:

    $ python ComPyLL/compile.py program.py > program.ll
    
  3. Generate a object file from using llc, the LLVM static compiler:

    $ llc program.ll -filetype=obj -o program.o
    
  4. Generate an object file from runtime.c:

    $ gcc -o program program.o clib/compyll_lib.a -lgc
    
  5. Run the compiled program:

    $ ./program
    
  6. Link both files:

    $ gcc program.o ComPyLL/runtime.o
    

Note the static library ComPyLL/clib/compyll_lib.a only needs to be generated once and can be linked with multiple programs.

Testing

The project uses makefiles to run different tests and other tasks. The most important make targets are explained below.

In addition, each make target is run in a virtual environment.

Unit Tests

To run the unit tests , fomr the root of the project, simply do:

$ make unit-test

The unit tests wil generate a Cobertura style xml report in the root of the project in a file named xunit.xml.

Integration Tests

To run the integration tests , fomr the root of the project, simply do:

$ make integration-test

The integration tests wil generate a Cobertura style xml report in the root of the project in a file named xunit-integration.xml.

In addition, when running integration tests, two folders are created in the root pof the project: compiled and errors. The compiled folder contains the compiled files (LLVM assembly language, object files and executable) for each test. The errors folder contains the reference errors, as if the program was run directly with Python and the actual errros of the program. thins includes compilation errors, linking errors and runtime errors.

Linting

The project uses pylint to detect code smells and respect conventions (such as PEP 8).

To run pylint , fomr the root of the project, simply do:

$ make pylint

Pylint will generate a file named pylint.out in the root of the project with the violations.

Coverage

By default both unit tests and integration tests will also generate a coverage data. Note however that running unit tests erase any previous coverage but running integration tests preserve the existing coverage data. The reason behin this is to be able to collect the global coverage data from both types of testing.

For this reason, it is advised not to take into account the coverage data when the unit tests or integration tests are run manually.

Instead, if you want coverage data, run the following commnand from the root of the project:

$ make coverage

This will erase the existing coverage and collect the coverage data from both the unit tests and integration tests. In addition it will generate a file on the root of the project named coverage.xml which contains the coverage data.

Grouping

It is possible to run the above all together witht he follwing command:

$ make

This will create a virtual environment and run pylint and the coverage (which will run unit tests and integration tests) in the same virtual environment and cleanup afterwars. (Leaving the files containing the tests reuslts and coverage).

Documentation

The documentation can also be generated using a make command.

Just type the following in the root of the project:

$ make doc

This will generate an html documentation which is available at doc/build/html. The master file is index.html.

Cleaning

The Makefile also include targets for cleaning.

The obvious one:

$ make clean

This will remove all the .pyc files in the project

The tests will generate files with details concerning the status of their last run and files needed to run some of the tests. Those are erase autmatically before each new tests run but they can also be removed manually with the following command:

$ make clean-results

If you which to remove the files generated to run the tests but keep the results, use the following:

$ make clean-tests

The documentation can be removed as well with the following command:

$ make clean-doc

If the unit tests, integration tests, or the coverage are run manually, it is recommended to run the following command to clean up after the tests. (This will not erase the results of the tests)

$ make cleanup

Note that when running make, then this is run automatically afterwards.

Finally, to clean everything you can run:

$ make clean-all

This will remove everything including the test resutls and the documentation. This can be usefull espically in some case where ttargets can fail because the virtual environment cannot be set as this will clean both the virtual environment and the cach containing its dependencies.

License

The MIT License (MIT)

Copyright (c) 2013 Jacques Dafflon, Giorgio Gori, Giovanni Viviani

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.