| paul@440 | 1 | Introduction
|
| paul@440 | 2 | ============
|
| paul@440 | 3 |
|
| paul@450 | 4 | Lichen is both a Python-like language and a toolchain for that language. The
|
| paul@450 | 5 | language foregoes various dynamic aspects of Python to provide a foundation
|
| paul@450 | 6 | upon which more predictable programs can be built, while preserving essential
|
| paul@450 | 7 | functionality to make the core of the language seem very much "like Python"
|
| paul@450 | 8 | (thus yielding the name "Lichen"). The general syntax is largely identical to
|
| paul@450 | 9 | Python, with only certain syntactic constructs being deliberately unsupported,
|
| paul@450 | 10 | largely because the associated features are not desired.
|
| paul@440 | 11 |
|
| paul@440 | 12 | The toolchain employs existing tokeniser and parser software to obtain an
|
| paul@440 | 13 | abstract syntax tree which is then inspected to provide data to support
|
| paul@440 | 14 | deductions about the structure and nature of a given program. With the
|
| paul@440 | 15 | information obtained from these processes, a program is then constructed,
|
| paul@440 | 16 | consisting of a number of source files in the target compilation language
|
| paul@440 | 17 | (which is currently the C programming language). This generated program may be
|
| paul@450 | 18 | compiled and run, hopefully producing the results intended by the source
|
| paul@450 | 19 | program's authors.
|
| paul@450 | 20 |
|
| paul@450 | 21 | Lichen source files use the .py suffix since the language syntax is
|
| paul@450 | 22 | superficially compatible with Python, allowing text editors to provide
|
| paul@450 | 23 | highlighting and editing support for Lichen programs without the need to
|
| paul@450 | 24 | reconfigure such tools. However, an alternative suffix is likely to be
|
| paul@450 | 25 | introduced in future.
|
| paul@450 | 26 |
|
| paul@450 | 27 | Getting Started
|
| paul@450 | 28 | ===============
|
| paul@450 | 29 |
|
| paul@450 | 30 | The principal interface to the toolchain is the lplc command which can be run
|
| paul@450 | 31 | on source files as in the following example:
|
| paul@450 | 32 |
|
| paul@450 | 33 | lplc tests/unicode.py
|
| paul@450 | 34 |
|
| paul@450 | 35 | This causes the inspection of the indicated program file and all imported
|
| paul@450 | 36 | modules, the deduction and optimisation of program information, and the
|
| paul@450 | 37 | generation and translation of the program to a form suitable for compilation.
|
| paul@450 | 38 | By default, compilation is performed by invoking the widely-known make
|
| paul@450 | 39 | utility.
|
| paul@450 | 40 |
|
| paul@450 | 41 | The results of this process are stored in the _lplc directory, with the
|
| paul@450 | 42 | executable program being written out as "_main" in the working directory
|
| paul@450 | 43 | unless the -o option is presented to lplc. For example:
|
| paul@450 | 44 |
|
| paul@450 | 45 | lplc -o unicode tests/unicode.py
|
| paul@450 | 46 |
|
| paul@450 | 47 | The executable program here will be written out as "unicode" and can be run
|
| paul@450 | 48 | directly:
|
| paul@450 | 49 |
|
| paul@450 | 50 | ./unicode
|
| paul@450 | 51 |
|
| paul@450 | 52 | Since the executable program is merely C source code and can be compiled using
|
| paul@450 | 53 | a normal C compiler, it may also be compiled using a cross compiler by setting
|
| paul@450 | 54 | the ARCH environment variable. For example:
|
| paul@450 | 55 |
|
| paul@450 | 56 | ARCH=mipsel-linux-gnu lplc -o unicode tests/unicode.py
|
| paul@450 | 57 |
|
| paul@450 | 58 | This employs a cross compiler targeting the mipsel (little-endian MIPS)
|
| paul@450 | 59 | architecture running GNU/Linux.
|
| paul@440 | 60 |
|
| paul@457 | 61 | Test Suite
|
| paul@457 | 62 | ==========
|
| paul@457 | 63 |
|
| paul@457 | 64 | A test suite is provided to exercise the toolchain and expose regressions.
|
| paul@457 | 65 | More information is available by running the test_all.sh script with the
|
| paul@457 | 66 | appropriate option:
|
| paul@457 | 67 |
|
| paul@457 | 68 | ./test_all.sh --help
|
| paul@457 | 69 |
|
| paul@457 | 70 | Running it with the --build option should prove to be the most useful
|
| paul@457 | 71 | approach in testing code analysis and validating code generation.
|
| paul@457 | 72 |
|
| paul@457 | 73 | Source Code Overview
|
| paul@457 | 74 | ====================
|
| paul@457 | 75 |
|
| paul@457 | 76 | The source files implementing the toolchain are found in the distribution
|
| paul@457 | 77 | directory with .py suffixes. The lplc tool is also found in the distribution
|
| paul@457 | 78 | directory.
|
| paul@457 | 79 |
|
| paul@457 | 80 | The following directories also contain source code employed by the toolchain:
|
| paul@457 | 81 |
|
| paul@457 | 82 | compiler - a modified version of the Python compiler package
|
| paul@457 | 83 | pyparser - a modified version of the PyPy parser package
|
| paul@457 | 84 |
|
| paul@457 | 85 | The following directories provide tests:
|
| paul@457 | 86 |
|
| paul@457 | 87 | internal_tests - a collection of tests exercising toolchain objects directly
|
| paul@457 | 88 | tests - individual test programs exercising the toolchain itself
|
| paul@457 | 89 |
|
| paul@457 | 90 | The toolchain relies on additional code when generating output programs:
|
| paul@457 | 91 |
|
| paul@457 | 92 | lib - the standard library for Lichen programs
|
| paul@457 | 93 | templates - runtime support libraries for generated programs
|
| paul@457 | 94 |
|
| paul@457 | 95 | Finally, a docs directory provides documentation about this project.
|
| paul@457 | 96 |
|
| paul@440 | 97 | Contact, Copyright and Licence Information
|
| paul@440 | 98 | ==========================================
|
| paul@440 | 99 |
|
| paul@440 | 100 | See the following Web pages for more information about this work:
|
| paul@440 | 101 |
|
| paul@440 | 102 | http://projects.boddie.org.uk/Lichen
|
| paul@440 | 103 |
|
| paul@440 | 104 | The author can be contacted at the following e-mail address:
|
| paul@440 | 105 |
|
| paul@440 | 106 | paul@boddie.org.uk
|
| paul@440 | 107 |
|
| paul@440 | 108 | Copyright and licence information can be found in the docs directory - see
|
| paul@440 | 109 | docs/COPYING.txt and docs/gpl-3.0.txt for more information.
|
