Lichen

README.txt

860:21f92740b225
2018-07-22 Paul Boddie Merged changes from the default branch. trailing-data
     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 Getting Started
    28 ===============
    29 
    30 The principal interface to the toolchain is the lplc command which can be run
    31 on source files as in the following example:
    32 
    33 lplc tests/unicode.py
    34 
    35 This causes the inspection of the indicated program file and all imported
    36 modules, the deduction and optimisation of program information, and the
    37 generation and translation of the program to a form suitable for compilation.
    38 By default, compilation is performed by invoking the widely-known make
    39 utility.
    40 
    41 The results of this process are stored in the _lplc directory, with the
    42 executable program being written out as "_main" in the working directory
    43 unless the -o option is presented to lplc. For example:
    44 
    45 lplc -o unicode tests/unicode.py
    46 
    47 The executable program here will be written out as "unicode" and can be run
    48 directly:
    49 
    50 ./unicode
    51 
    52 Since the executable program is merely C source code and can be compiled using
    53 a normal C compiler, it may also be compiled using a cross compiler by setting
    54 the ARCH environment variable. For example:
    55 
    56 ARCH=mipsel-linux-gnu lplc -o unicode tests/unicode.py
    57 
    58 This employs a cross compiler targeting the mipsel (little-endian MIPS)
    59 architecture running GNU/Linux.
    60 
    61 Test Suite
    62 ==========
    63 
    64 A test suite is provided to exercise the toolchain and expose regressions.
    65 More information is available by running the test_all.sh script with the
    66 appropriate option:
    67 
    68 ./test_all.sh --help
    69 
    70 Running it with the --build option should prove to be the most useful
    71 approach in testing code analysis and validating code generation.
    72 
    73 Source Code Overview
    74 ====================
    75 
    76 The source files implementing the toolchain are found in the distribution
    77 directory with .py suffixes. The lplc tool is also found in the distribution
    78 directory.
    79 
    80 The following directories also contain source code employed by the toolchain:
    81 
    82 compiler       - a modified version of the Python compiler package
    83 pyparser       - a modified version of the PyPy parser package
    84 
    85 The following directories provide tests:
    86 
    87 internal_tests - a collection of tests exercising toolchain objects directly
    88 tests          - individual test programs exercising the toolchain itself
    89 
    90 The toolchain relies on additional code when generating output programs:
    91 
    92 lib            - the standard library for Lichen programs
    93 templates      - runtime support libraries for generated programs
    94 
    95 Finally, a docs directory provides documentation about this project.
    96 
    97 Contact, Copyright and Licence Information
    98 ==========================================
    99 
   100 See the following Web pages for more information about this work:
   101 
   102 http://projects.boddie.org.uk/Lichen
   103 
   104 The author can be contacted at the following e-mail address:
   105 
   106 paul@boddie.org.uk
   107 
   108 Copyright and licence information can be found in the docs directory - see
   109 docs/COPYING.txt and docs/gpl-3.0.txt for more information.
   110 
   111 Generating the Wiki Pages
   112 =========================
   113 
   114 The docs/tools/make_pages.sh script generates a page package for MoinMoin. The
   115 following command will generate a page package called pages.zip using the
   116 pages directory for staging, with Lichen as the page prefix:
   117 
   118 docs/tools/make_pages.sh pages Lichen
   119 
   120 Make sure to include the page prefix where the pages are being deployed in a
   121 wiki with other content at the top level.
   122 
   123 Currently, the wiki pages require the following extensions:
   124 
   125 ImprovedTableParser     https://moinmo.in/ParserMarket/ImprovedTableParser
   126 
   127 MoinSupport             http://hgweb.boddie.org.uk/MoinSupport
   128 
   129 GraphvizParser          https://moinmo.in/ParserMarket/graphviz
   130 
   131 The GraphvizParser requires diagram-tools for the notugly.xsl stylesheet,
   132 although a copy of the stylesheet is provided in the GraphvizParser
   133 distribution for convenience.