paul@263 | 1 | Introduction
|
paul@263 | 2 | ------------
|
paul@28 | 3 |
|
paul@735 | 4 | Micropython is a language environment incorporating static analysis tools and
|
paul@735 | 5 | a compiler for a simplified version of the Python programming language; this
|
paul@735 | 6 | compiler targets a simple target language called Syspython as well as
|
paul@735 | 7 | producing HTML reports describing the properties of Python programs.
|
paul@30 | 8 |
|
paul@510 | 9 | Prerequisites
|
paul@510 | 10 | -------------
|
paul@510 | 11 |
|
paul@510 | 12 | Micropython uses a forked version of the compiler package originating from the
|
paul@510 | 13 | Python standard library. This package should be made available to Micropython
|
paul@510 | 14 | using the PYTHONPATH environment variable or copied into the distribution
|
paul@510 | 15 | directory of this software. See the following locations for the code for this
|
paul@510 | 16 | compiler package variant:
|
paul@510 | 17 |
|
paul@599 | 18 | http://hgweb.boddie.org.uk/python2.6-compiler-package-micropython/
|
paul@735 | 19 | http://hgweb.boddie.org.uk/python2.7-compiler-package-micropython/
|
paul@510 | 20 |
|
paul@510 | 21 | It should be sufficient to use the Python 2.6 package for systems running
|
paul@510 | 22 | Python 2.5 or 2.6 since the underlying standard library does not seem to have
|
paul@510 | 23 | changed significantly between these releases and the language syntax is
|
paul@735 | 24 | sufficiently similar. For Python 2.7, the appropriate variant referenced above
|
paul@735 | 25 | is required due to standard library and syntax changes in that release of the
|
paul@735 | 26 | language implementation.
|
paul@510 | 27 |
|
paul@263 | 28 | Quick Start
|
paul@263 | 29 | -----------
|
paul@29 | 30 |
|
paul@263 | 31 | Currently, the test.py program is the principal means of compiling and running
|
paul@680 | 32 | code. For example, to inspect the logical.py test program...
|
paul@29 | 33 |
|
paul@735 | 34 | python -i test.py tests/logical.py
|
paul@29 | 35 |
|
paul@735 | 36 | ...will provide a number of objects which can then be inspected.
|
paul@29 | 37 |
|
paul@735 | 38 | To generate Syspython programs, the -s option must be given along with a
|
paul@735 | 39 | target directory. For example:
|
paul@28 | 40 |
|
paul@735 | 41 | python test.py tests/logical.py -s logical_program
|
paul@29 | 42 |
|
paul@735 | 43 | The files in the indicated directory will then be suitable for processing by
|
paul@735 | 44 | tools that understand Syspython.
|
paul@295 | 45 |
|
paul@510 | 46 | Program Reports/Summaries
|
paul@510 | 47 | -------------------------
|
paul@510 | 48 |
|
paul@510 | 49 | Using the test.py program, reports can be generated which should show the
|
paul@510 | 50 | modules present in a given program, with each module's code annotated with
|
paul@510 | 51 | scope, attribute and inferred type information. For example:
|
paul@510 | 52 |
|
paul@680 | 53 | python test.py tests/logical.py -d logical_report
|
paul@510 | 54 |
|
paul@510 | 55 | This should produce a number of files in the logical_report directory.
|
paul@510 | 56 |
|
paul@510 | 57 | * The __main__ module, being the "main" file of any given program will
|
paul@510 | 58 | always be described by the __main__.xhtml file.
|
paul@510 | 59 |
|
paul@510 | 60 | * Imported modules will be described by files whose names contain the module
|
paul@510 | 61 | path for such modules, such as compiler.ast.xhtml (for the compiler.ast
|
paul@510 | 62 | module) or sys.xhtml (for the sys module).
|
paul@510 | 63 |
|
paul@510 | 64 | In addition, a summary of the classes defined by each module should be
|
paul@510 | 65 | generated, and these files will have a "-summary" suffix added to the basename
|
paul@510 | 66 | of each module filename. For example, compiler.ast.xhtml will have a
|
paul@510 | 67 | corresponding summary file called compiler.ast-summary.xhtml (summarising
|
paul@510 | 68 | classes in the compiler.ast module).
|
paul@510 | 69 |
|
paul@510 | 70 | Roadmap
|
paul@510 | 71 | -------
|
paul@510 | 72 |
|
paul@510 | 73 | Writing a language toolchain is a huge undertaking involving numerous
|
paul@510 | 74 | activities, many of which are hastily described in the TO_DO.txt file. It is
|
paul@510 | 75 | tempting to write a source code analyser and to then claim that it could be
|
paul@510 | 76 | used as part of a larger system offering performance benefits in comparison to
|
paul@510 | 77 | other toolchains or implementations of a language, but the feasibility of such
|
paul@510 | 78 | a system should be at least demonstrated for such claims to have much
|
paul@510 | 79 | credibility. If a toolchain cannot even produce working programs then any
|
paul@510 | 80 | discussion of relative performance becomes academic.
|
paul@510 | 81 |
|
paul@735 | 82 | Thus, an attempt has been made to make a genuine compiler and output
|
paul@735 | 83 | representation, together with a virtual machine that can run and test compiled
|
paul@735 | 84 | programs (previously part of this distribution, but now under separate
|
paul@735 | 85 | development), hopefully modelling a sufficiently realistic architecture
|
paul@735 | 86 | without any unjustified shortcuts being taken to produce the desired program
|
paul@735 | 87 | behaviour. This virtual machine and the code generation activity that is
|
paul@735 | 88 | needed to exercise it can be regarded as distractions from the principal
|
paul@735 | 89 | merits of the software: the analysis activity that attempts to define and
|
paul@735 | 90 | indicate the structure and properties of a reasonable subset of the Python
|
paul@735 | 91 | language and its semantics.
|
paul@510 | 92 |
|
paul@510 | 93 | With limited time to spend on the project, some activities are regarded as
|
paul@510 | 94 | more rewarding than others. Making a viable virtual machine or runtime
|
paul@510 | 95 | environment is a demanding task in itself, as is generating machine code for
|
paul@510 | 96 | real machine architectures, at least if it is to be done in an optimal
|
paul@510 | 97 | fashion. Experimenting with garbage collection strategies and memory
|
paul@510 | 98 | allocation are interesting projects but can also be considered as peripheral
|
paul@735 | 99 | activities that can consume substantial amounts of effort. Thus, the virtual
|
paul@735 | 100 | machine activity is now separate and the Syspython output representation has
|
paul@735 | 101 | been adopted as an intermediary between this work and the virtual machine
|
paul@735 | 102 | effort.
|
paul@510 | 103 |
|
paul@510 | 104 | It is therefore likely that interoperability with other projects and tools may
|
paul@510 | 105 | take precedence over the production of a complete system that can target
|
paul@510 | 106 | various machine architectures and offer the ability to compile Python programs
|
paul@510 | 107 | for deployment as directly executable code. Nevertheless, the ability to
|
paul@510 | 108 | generate programs for deployment on microcomputers and microcontrollers - one
|
paul@510 | 109 | of the initial motivations - remains a long-term goal.
|
paul@510 | 110 |
|
paul@263 | 111 | Contact, Copyright and Licence Information
|
paul@263 | 112 | ------------------------------------------
|
paul@30 | 113 |
|
paul@263 | 114 | The current Web page for micropython at the time of release is:
|
paul@261 | 115 |
|
paul@510 | 116 | http://hgweb.boddie.org.uk/micropython
|
paul@261 | 117 |
|
paul@263 | 118 | Copyright and licence information can be found in the docs directory - see
|
paul@263 | 119 | docs/COPYING.txt and docs/gpl-3.0.txt for more information.
|