Metadata-Version: 2.0
Name: shivyc
Version: 0.4.1
Summary: A C compiler written in Python
Home-page: https://github.com/ShivamSarodia/ShivyC
Author: Shivam Sarodia
Author-email: ssarodia@gmail.com
License: MIT
Download-URL: https://github.com/ShivamSarodia/ShivyC/archive/0.4.1.tar.gz
Keywords: shivyc compiler c programming parsing
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: C
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Build Tools
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education

ShivyC
======

| |Build Status| |Code Coverage|


ShivyC is a dependency-free C compiler written in Python 3, targeting Linux
x86-64 machines. ShivyC seeks to eventually support the entire C11
standard and produce reasonably efficient code. For ShivyC’s current
feature set, see the test files in the `tests/general\_tests`_ and
`tests/feature\_tests`_ directories.

ShivyC is a rewrite from scratch of my older attempt at a C compiler,
`ShivC`_, with much more emphasis on feature completeness and code
quality. See the ShivC README for more details on the target
improvements.

Quickstart
------------

x86-64 Linux
^^^^^^^^^^^^

For compilation of C code, ShivyC only requires Python 3. Assembling and linking are done using the GNU binutils and glibc, which you almost certainly already have installed.

To install ShivyC:
::

    pip3 install shivyc

For command line usage info:
::

    shivyc

To create, compile, and run an example program:
::

    printf "%s\n" '#include <stdio.h>' > test.c
    printf "%s\n" 'int main() { printf("hello, world!\n"); }' >> test.c
    shivyc test.c
    ./out

To run the tests:
::

    git clone https://github.com/ShivamSarodia/ShivyC.git
    cd ShivyC
    python3 -m unittest discover

Other Architectures
^^^^^^^^^^^^

For the convenience of those not running Linux, the ``docker/`` directory provides a Dockerfile that sets up an x86-64 Linux Ubuntu environment with everything necessary for ShivyC. To use this, run:

::

    git clone https://github.com/ShivamSarodia/ShivyC.git  
    cd ShivyC
    docker build -t shivyc docker/
    docker/shell

This will open up a shell in an environment with ShivyC installed and ready to use with

::

    python3 -m unittest discover  # to run tests
    shivyc any_c_file.c           # to compile a file

The Docker ShivyC executable will update live with any changes made in your local ShivyC directory. 


Implementation Overview
-----------------------

Preprocessor
^^^^^^^^^^^^

ShivyC currently has a very limited preprocessor that parses out
comments and expands #include directives. These features are implemented
between ``lexer.py`` and ``preproc.py``. A more complete preprocessor
will be implemented.

Lexer
^^^^^

The ShivyC lexer is implemented primarily in ``lexer.py``. Additionally,
``tokens.py`` contains definitions of the token classes used in the
lexer and ``token_kinds.py`` contains instances of recognized keyword
and symbol tokens.

Parser
^^^^^^

The ShivyC parser uses recursive descent techniques for all parsing. It
is implented in ``parser/*.py`` and creates a parse tree of nodes
defined in ``tree/nodes.py`` and ``tree/expr_nodes.py``.

IL generation
^^^^^^^^^^^^^

ShivyC traverses the parse tree to generate a flat custom IL
(intermediate language). The commands for this IL are in
``il_cmds/*.py``. Objects used for IL generation are in ``il_gen.py``,
but most of the IL generating code is in the ``make_code`` function of
each tree node in ``tree/*.py``.

ASM generation
^^^^^^^^^^^^^^

ShivyC sequentially reads the IL commands, converting each into x86-64
assembly code. ShivyC performs register allocation using George and
Appel’s iterated register coalescing algorithm; see References below.
The general ASM generation functionality is in ``asm_gen.py``, but much
of the ASM generating code is in the ``make_asm`` function of each IL
command in ``il_cmds/*.py``.

Contributing
------------

ShivyC has so far been an entirely individual project. That said, pull
requests are welcome if they pass flake8 and are well-tested. Make sure to copy the hooks in the ``hooks/`` directory into your .git/ folder.

References
----------

-  C11 Specification -
   http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
-  x86\_64 ABI -
   http://web.archive.org/web/20160801075139/http://www.x86-64.org/documentation/abi.pdf
-  Iterated Register Coalescing (George and Appel) -
   https://www.cs.purdue.edu/homes/hosking/502/george.pdf

.. _tests/general\_tests: https://github.com/ShivamSarodia/ShivyC/tree/master/tests/general_tests
.. _tests/feature\_tests: https://github.com/ShivamSarodia/ShivyC/tree/master/tests/feature_tests
.. _ShivC: https://github.com/ShivamSarodia/ShivC

.. |Build Status| image:: https://travis-ci.org/ShivamSarodia/ShivyC.svg?branch=master
   :target: https://travis-ci.org/ShivamSarodia/ShivyC
.. |Code Coverage| image:: https://codecov.io/gh/ShivamSarodia/ShivyC/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/ShivamSarodia/ShivyC


