| 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@991 | 27 | A Note about the Documentation
|
| paul@991 | 28 | ------------------------------
|
| paul@991 | 29 |
|
| paul@991 | 30 | The original content in docs/wiki aims to be readable as plain text under most
|
| paul@991 | 31 | circumstances, but the intention is that this content be translated to HTML
|
| paul@991 | 32 | since it employs a formatting language based on the MoinMoin wiki format
|
| paul@991 | 33 | syntax.
|
| paul@991 | 34 |
|
| paul@991 | 35 | The following command can be used to generate the HTML form of the
|
| paul@991 | 36 | documentation from the main directory of this distribution:
|
| paul@991 | 37 |
|
| paul@991 | 38 | ./docs/tools/make_docs.sh
|
| paul@991 | 39 |
|
| paul@991 | 40 | Specify the --web option for Web server deployment:
|
| paul@991 | 41 |
|
| paul@991 | 42 | ./docs/tools/make_docs.sh --web
|
| paul@991 | 43 |
|
| paul@991 | 44 | To generate individual documents, specify their names after any options.
|
| paul@991 | 45 |
|
| paul@450 | 46 | Getting Started
|
| paul@450 | 47 | ===============
|
| paul@450 | 48 |
|
| paul@450 | 49 | The principal interface to the toolchain is the lplc command which can be run
|
| paul@450 | 50 | on source files as in the following example:
|
| paul@450 | 51 |
|
| paul@450 | 52 | lplc tests/unicode.py
|
| paul@450 | 53 |
|
| paul@450 | 54 | This causes the inspection of the indicated program file and all imported
|
| paul@450 | 55 | modules, the deduction and optimisation of program information, and the
|
| paul@450 | 56 | generation and translation of the program to a form suitable for compilation.
|
| paul@450 | 57 | By default, compilation is performed by invoking the widely-known make
|
| paul@450 | 58 | utility.
|
| paul@450 | 59 |
|
| paul@450 | 60 | The results of this process are stored in the _lplc directory, with the
|
| paul@450 | 61 | executable program being written out as "_main" in the working directory
|
| paul@450 | 62 | unless the -o option is presented to lplc. For example:
|
| paul@450 | 63 |
|
| paul@450 | 64 | lplc -o unicode tests/unicode.py
|
| paul@450 | 65 |
|
| paul@450 | 66 | The executable program here will be written out as "unicode" and can be run
|
| paul@450 | 67 | directly:
|
| paul@450 | 68 |
|
| paul@450 | 69 | ./unicode
|
| paul@450 | 70 |
|
| paul@450 | 71 | Since the executable program is merely C source code and can be compiled using
|
| paul@450 | 72 | a normal C compiler, it may also be compiled using a cross compiler by setting
|
| paul@450 | 73 | the ARCH environment variable. For example:
|
| paul@450 | 74 |
|
| paul@450 | 75 | ARCH=mipsel-linux-gnu lplc -o unicode tests/unicode.py
|
| paul@450 | 76 |
|
| paul@450 | 77 | This employs a cross compiler targeting the mipsel (little-endian MIPS)
|
| paul@450 | 78 | architecture running GNU/Linux.
|
| paul@440 | 79 |
|
| paul@457 | 80 | Test Suite
|
| paul@457 | 81 | ==========
|
| paul@457 | 82 |
|
| paul@457 | 83 | A test suite is provided to exercise the toolchain and expose regressions.
|
| paul@457 | 84 | More information is available by running the test_all.sh script with the
|
| paul@457 | 85 | appropriate option:
|
| paul@457 | 86 |
|
| paul@457 | 87 | ./test_all.sh --help
|
| paul@457 | 88 |
|
| paul@457 | 89 | Running it with the --build option should prove to be the most useful
|
| paul@457 | 90 | approach in testing code analysis and validating code generation.
|
| paul@457 | 91 |
|
| paul@457 | 92 | Source Code Overview
|
| paul@457 | 93 | ====================
|
| paul@457 | 94 |
|
| paul@457 | 95 | The source files implementing the toolchain are found in the distribution
|
| paul@457 | 96 | directory with .py suffixes. The lplc tool is also found in the distribution
|
| paul@457 | 97 | directory.
|
| paul@457 | 98 |
|
| paul@457 | 99 | The following directories also contain source code employed by the toolchain:
|
| paul@457 | 100 |
|
| paul@457 | 101 | compiler - a modified version of the Python compiler package
|
| paul@457 | 102 | pyparser - a modified version of the PyPy parser package
|
| paul@457 | 103 |
|
| paul@457 | 104 | The following directories provide tests:
|
| paul@457 | 105 |
|
| paul@457 | 106 | internal_tests - a collection of tests exercising toolchain objects directly
|
| paul@457 | 107 | tests - individual test programs exercising the toolchain itself
|
| paul@457 | 108 |
|
| paul@457 | 109 | The toolchain relies on additional code when generating output programs:
|
| paul@457 | 110 |
|
| paul@457 | 111 | lib - the standard library for Lichen programs
|
| paul@457 | 112 | templates - runtime support libraries for generated programs
|
| paul@457 | 113 |
|
| paul@457 | 114 | Finally, a docs directory provides documentation about this project.
|
| paul@457 | 115 |
|
| paul@440 | 116 | Contact, Copyright and Licence Information
|
| paul@440 | 117 | ==========================================
|
| paul@440 | 118 |
|
| paul@440 | 119 | See the following Web pages for more information about this work:
|
| paul@440 | 120 |
|
| paul@440 | 121 | http://projects.boddie.org.uk/Lichen
|
| paul@440 | 122 |
|
| paul@440 | 123 | The author can be contacted at the following e-mail address:
|
| paul@440 | 124 |
|
| paul@440 | 125 | paul@boddie.org.uk
|
| paul@440 | 126 |
|
| paul@440 | 127 | Copyright and licence information can be found in the docs directory - see
|
| paul@440 | 128 | docs/COPYING.txt and docs/gpl-3.0.txt for more information.
|
