micropython

README.txt

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