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