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