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