1 Introduction
2 ------------
3
4 Micropython is a language environment incorporating a compiler for a
5 simplified version of the Python programming language which targets a simple
6 instruction set supported by a virtual machine known as RSVP (a Really Simple
7 Virtual Processor).
8
9 The RSVP instruction set is intended to map relatively closely to instructions
10 employed by real processors, with only a few "macroinstructions" which would
11 probably be implemented as short macros or library routines in programs
12 translated to the instruction set of a real target processor.
13
14 Prerequisites
15 -------------
16
17 Micropython uses a forked version of the compiler package originating from the
18 Python standard library. This package should be made available to Micropython
19 using the PYTHONPATH environment variable or copied into the distribution
20 directory of this software. See the following locations for the code for this
21 compiler package variant:
22
23 http://hgweb.boddie.org.uk/python2.5-compiler-package/
24 http://hgweb.boddie.org.uk/python2.6-compiler-package/
25 http://hgweb.boddie.org.uk/python2.7-compiler-package/
26
27 It should be sufficient to use the Python 2.6 package for systems running
28 Python 2.5 or 2.6 since the underlying standard library does not seem to have
29 changed significantly between these releases and the language syntax is
30 sufficiently similar. For Python 2.7, the appropriate variant may be
31 preferable or even required due to standard library and syntax changes in that
32 release of the language implementation, but this has not yet been tested in
33 any depth.
34
35 Quick Start
36 -----------
37
38 Currently, the test.py program is the principal means of compiling and running
39 code. For example, to inspect the logical.py test program (with all
40 optimisations enabled)...
41
42 python -i test.py tests/logical.py -m -omax
43
44 ...will provide a number of objects which can then be inspected, notably the
45 rm (RSVP machine) object which provides the following methods:
46
47 * show - reveals the contents of the machine's memory
48 * run - starts execution of the code in the memory
49 * step - steps through the code one instruction at a time
50 * dump - shows the machine's registers
51
52 To run a test and check the output, specify the -t option:
53
54 python test.py tests/logical.py -t -omax
55
56 To run all tests, use the test_all.py program:
57
58 python test_all.py -omax
59
60 Both programs support optimisations either using the -o flag immediately
61 followed (no space or separator) by a comma-separated list of options (defined
62 in the docs/optimisations.txt document) or by specifying -omax to apply all
63 possible optimisations.
64
65 It is generally recommended to apply all possible optimisations when
66 generating programs as this dramatically reduces the size of the program and
67 accompanying structures, and it also makes the code generation process
68 substantially faster. Optimisations should not cause programs to fail: they
69 should all always be "safe" to apply.
70
71 Program Reports/Summaries
72 -------------------------
73
74 Using the test.py program, reports can be generated which should show the
75 modules present in a given program, with each module's code annotated with
76 scope, attribute and inferred type information. For example:
77
78 python test.py tests/logical.py -omax -d logical_report
79
80 This should produce a number of files in the logical_report directory.
81
82 * The __main__ module, being the "main" file of any given program will
83 always be described by the __main__.xhtml file.
84
85 * Imported modules will be described by files whose names contain the module
86 path for such modules, such as compiler.ast.xhtml (for the compiler.ast
87 module) or sys.xhtml (for the sys module).
88
89 In addition, a summary of the classes defined by each module should be
90 generated, and these files will have a "-summary" suffix added to the basename
91 of each module filename. For example, compiler.ast.xhtml will have a
92 corresponding summary file called compiler.ast-summary.xhtml (summarising
93 classes in the compiler.ast module).
94
95 Roadmap
96 -------
97
98 Writing a language toolchain is a huge undertaking involving numerous
99 activities, many of which are hastily described in the TO_DO.txt file. It is
100 tempting to write a source code analyser and to then claim that it could be
101 used as part of a larger system offering performance benefits in comparison to
102 other toolchains or implementations of a language, but the feasibility of such
103 a system should be at least demonstrated for such claims to have much
104 credibility. If a toolchain cannot even produce working programs then any
105 discussion of relative performance becomes academic.
106
107 Thus, an attempt has been made to make a genuine compiler and virtual machine
108 that can run and test compiled programs, hopefully modelling a sufficiently
109 realistic architecture without any unjustified shortcuts being taken to
110 produce the desired program behaviour. This virtual machine and the code
111 generation activity that is needed to exercise it can be regarded as
112 distractions from the principal merits of the software: the analysis activity
113 that attempts to define and indicate the structure and properties of a
114 reasonable subset of the Python language and its semantics.
115
116 With limited time to spend on the project, some activities are regarded as
117 more rewarding than others. Making a viable virtual machine or runtime
118 environment is a demanding task in itself, as is generating machine code for
119 real machine architectures, at least if it is to be done in an optimal
120 fashion. Experimenting with garbage collection strategies and memory
121 allocation are interesting projects but can also be considered as peripheral
122 activities that can consume substantial amounts of effort.
123
124 It is therefore likely that interoperability with other projects and tools may
125 take precedence over the production of a complete system that can target
126 various machine architectures and offer the ability to compile Python programs
127 for deployment as directly executable code. Nevertheless, the ability to
128 generate programs for deployment on microcomputers and microcontrollers - one
129 of the initial motivations - remains a long-term goal.
130
131 Contact, Copyright and Licence Information
132 ------------------------------------------
133
134 The current Web page for micropython at the time of release is:
135
136 http://hgweb.boddie.org.uk/micropython
137
138 Copyright and licence information can be found in the docs directory - see
139 docs/COPYING.txt and docs/gpl-3.0.txt for more information.
