# ComPyLL

A Compiler from Python to LLVM, written in Python.

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