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