micropython

Annotated README.txt

781:257aa2d84abe
2014-02-23 Paul Boddie Added a test of a name taking different scopes in the same unit. syspython-as-target
paul@263 1
Introduction
paul@263 2
------------
paul@28 3
paul@735 4
Micropython is a language environment incorporating static analysis tools and
paul@735 5
a compiler for a simplified version of the Python programming language; this
paul@735 6
compiler targets a simple target language called Syspython as well as
paul@735 7
producing HTML reports describing the properties of Python programs.
paul@30 8
paul@510 9
Prerequisites
paul@510 10
-------------
paul@510 11
paul@510 12
Micropython uses a forked version of the compiler package originating from the
paul@510 13
Python standard library. This package should be made available to Micropython
paul@510 14
using the PYTHONPATH environment variable or copied into the distribution
paul@510 15
directory of this software. See the following locations for the code for this
paul@510 16
compiler package variant:
paul@510 17
paul@599 18
http://hgweb.boddie.org.uk/python2.6-compiler-package-micropython/
paul@735 19
http://hgweb.boddie.org.uk/python2.7-compiler-package-micropython/
paul@510 20
paul@510 21
It should be sufficient to use the Python 2.6 package for systems running
paul@510 22
Python 2.5 or 2.6 since the underlying standard library does not seem to have
paul@510 23
changed significantly between these releases and the language syntax is
paul@735 24
sufficiently similar. For Python 2.7, the appropriate variant referenced above
paul@735 25
is required due to standard library and syntax changes in that release of the
paul@735 26
language implementation.
paul@510 27
paul@263 28
Quick Start
paul@263 29
-----------
paul@29 30
paul@263 31
Currently, the test.py program is the principal means of compiling and running
paul@680 32
code. For example, to inspect the logical.py test program...
paul@29 33
paul@735 34
  python -i test.py tests/logical.py
paul@29 35
paul@735 36
...will provide a number of objects which can then be inspected.
paul@29 37
paul@735 38
To generate Syspython programs, the -s option must be given along with a
paul@735 39
target directory. For example:
paul@28 40
paul@735 41
  python test.py tests/logical.py -s logical_program
paul@29 42
paul@735 43
The files in the indicated directory will then be suitable for processing by
paul@735 44
tools that understand Syspython.
paul@295 45
paul@510 46
Program Reports/Summaries
paul@510 47
-------------------------
paul@510 48
paul@510 49
Using the test.py program, reports can be generated which should show the
paul@510 50
modules present in a given program, with each module's code annotated with
paul@510 51
scope, attribute and inferred type information. For example:
paul@510 52
paul@680 53
  python test.py tests/logical.py -d logical_report
paul@510 54
paul@510 55
This should produce a number of files in the logical_report directory.
paul@510 56
paul@510 57
  * The __main__ module, being the "main" file of any given program will
paul@510 58
    always be described by the __main__.xhtml file.
paul@510 59
paul@510 60
  * Imported modules will be described by files whose names contain the module
paul@510 61
    path for such modules, such as compiler.ast.xhtml (for the compiler.ast
paul@510 62
    module) or sys.xhtml (for the sys module).
paul@510 63
paul@510 64
In addition, a summary of the classes defined by each module should be
paul@510 65
generated, and these files will have a "-summary" suffix added to the basename
paul@510 66
of each module filename. For example, compiler.ast.xhtml will have a
paul@510 67
corresponding summary file called compiler.ast-summary.xhtml (summarising
paul@510 68
classes in the compiler.ast module).
paul@510 69
paul@510 70
Roadmap
paul@510 71
-------
paul@510 72
paul@510 73
Writing a language toolchain is a huge undertaking involving numerous
paul@510 74
activities, many of which are hastily described in the TO_DO.txt file. It is
paul@510 75
tempting to write a source code analyser and to then claim that it could be
paul@510 76
used as part of a larger system offering performance benefits in comparison to
paul@510 77
other toolchains or implementations of a language, but the feasibility of such
paul@510 78
a system should be at least demonstrated for such claims to have much
paul@510 79
credibility. If a toolchain cannot even produce working programs then any
paul@510 80
discussion of relative performance becomes academic.
paul@510 81
paul@735 82
Thus, an attempt has been made to make a genuine compiler and output
paul@735 83
representation, together with a virtual machine that can run and test compiled
paul@735 84
programs (previously part of this distribution, but now under separate
paul@735 85
development), hopefully modelling a sufficiently realistic architecture
paul@735 86
without any unjustified shortcuts being taken to produce the desired program
paul@735 87
behaviour. This virtual machine and the code generation activity that is
paul@735 88
needed to exercise it can be regarded as distractions from the principal
paul@735 89
merits of the software: the analysis activity that attempts to define and
paul@735 90
indicate the structure and properties of a reasonable subset of the Python
paul@735 91
language and its semantics.
paul@510 92
paul@510 93
With limited time to spend on the project, some activities are regarded as
paul@510 94
more rewarding than others. Making a viable virtual machine or runtime
paul@510 95
environment is a demanding task in itself, as is generating machine code for
paul@510 96
real machine architectures, at least if it is to be done in an optimal
paul@510 97
fashion. Experimenting with garbage collection strategies and memory
paul@510 98
allocation are interesting projects but can also be considered as peripheral
paul@735 99
activities that can consume substantial amounts of effort. Thus, the virtual
paul@735 100
machine activity is now separate and the Syspython output representation has
paul@735 101
been adopted as an intermediary between this work and the virtual machine
paul@735 102
effort.
paul@510 103
paul@510 104
It is therefore likely that interoperability with other projects and tools may
paul@510 105
take precedence over the production of a complete system that can target
paul@510 106
various machine architectures and offer the ability to compile Python programs
paul@510 107
for deployment as directly executable code. Nevertheless, the ability to
paul@510 108
generate programs for deployment on microcomputers and microcontrollers - one
paul@510 109
of the initial motivations - remains a long-term goal.
paul@510 110
paul@263 111
Contact, Copyright and Licence Information
paul@263 112
------------------------------------------
paul@30 113
paul@263 114
The current Web page for micropython at the time of release is:
paul@261 115
paul@510 116
http://hgweb.boddie.org.uk/micropython
paul@261 117
paul@263 118
Copyright and licence information can be found in the docs directory - see
paul@263 119
docs/COPYING.txt and docs/gpl-3.0.txt for more information.