micropython

README.txt

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