Lichen

Annotated README.txt

861:f745d151a441
2018-08-17 Paul Boddie Wrapped text in the documentation for more convenient "offline" editing.
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.
paul@810 110
paul@810 111
Generating the Wiki Pages
paul@810 112
=========================
paul@810 113
paul@810 114
The docs/tools/make_pages.sh script generates a page package for MoinMoin. The
paul@810 115
following command will generate a page package called pages.zip using the
paul@810 116
pages directory for staging, with Lichen as the page prefix:
paul@810 117
paul@810 118
docs/tools/make_pages.sh pages Lichen
paul@810 119
paul@810 120
Make sure to include the page prefix where the pages are being deployed in a
paul@810 121
wiki with other content at the top level.
paul@810 122
paul@810 123
Currently, the wiki pages require the following extensions:
paul@810 124
paul@810 125
ImprovedTableParser     https://moinmo.in/ParserMarket/ImprovedTableParser
paul@810 126
paul@810 127
MoinSupport             http://hgweb.boddie.org.uk/MoinSupport
paul@810 128
paul@810 129
GraphvizParser          https://moinmo.in/ParserMarket/graphviz
paul@810 130
paul@810 131
The GraphvizParser requires diagram-tools for the notugly.xsl stylesheet,
paul@810 132
although a copy of the stylesheet is provided in the GraphvizParser
paul@810 133
distribution for convenience.