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