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