1.1 --- a/README.txt Thu Oct 31 17:18:31 2013 +0100
1.2 +++ b/README.txt Thu Oct 31 23:11:38 2013 +0100
1.3 @@ -1,18 +1,10 @@
1.4 -NOTE: This document needs updating for the separation of micropython and
1.5 -NOTE: syspython functionality.
1.6 -
1.7 Introduction
1.8 ------------
1.9
1.10 -Micropython is a language environment incorporating a compiler for a
1.11 -simplified version of the Python programming language which targets a simple
1.12 -instruction set supported by a virtual machine known as RSVP (a Really Simple
1.13 -Virtual Processor).
1.14 -
1.15 -The RSVP instruction set is intended to map relatively closely to instructions
1.16 -employed by real processors, with only a few "macroinstructions" which would
1.17 -probably be implemented as short macros or library routines in programs
1.18 -translated to the instruction set of a real target processor.
1.19 +Micropython is a language environment incorporating static analysis tools and
1.20 +a compiler for a simplified version of the Python programming language; this
1.21 +compiler targets a simple target language called Syspython as well as
1.22 +producing HTML reports describing the properties of Python programs.
1.23
1.24 Prerequisites
1.25 -------------
1.26 @@ -24,13 +16,14 @@
1.27 compiler package variant:
1.28
1.29 http://hgweb.boddie.org.uk/python2.6-compiler-package-micropython/
1.30 +http://hgweb.boddie.org.uk/python2.7-compiler-package-micropython/
1.31
1.32 It should be sufficient to use the Python 2.6 package for systems running
1.33 Python 2.5 or 2.6 since the underlying standard library does not seem to have
1.34 changed significantly between these releases and the language syntax is
1.35 -sufficiently similar. For Python 2.7, an appropriate variant may be preferable
1.36 -or even required due to standard library and syntax changes in that release of
1.37 -the language implementation, but this has not yet been tested in any depth.
1.38 +sufficiently similar. For Python 2.7, the appropriate variant referenced above
1.39 +is required due to standard library and syntax changes in that release of the
1.40 +language implementation.
1.41
1.42 Quick Start
1.43 -----------
1.44 @@ -38,23 +31,17 @@
1.45 Currently, the test.py program is the principal means of compiling and running
1.46 code. For example, to inspect the logical.py test program...
1.47
1.48 - python -i test.py tests/logical.py -m
1.49 + python -i test.py tests/logical.py
1.50
1.51 -...will provide a number of objects which can then be inspected, notably the
1.52 -rm (RSVP machine) object which provides the following methods:
1.53 +...will provide a number of objects which can then be inspected.
1.54
1.55 - * show - reveals the contents of the machine's memory
1.56 - * run - starts execution of the code in the memory
1.57 - * step - steps through the code one instruction at a time
1.58 - * dump - shows the machine's registers
1.59 +To generate Syspython programs, the -s option must be given along with a
1.60 +target directory. For example:
1.61
1.62 -To run a test and check the output, specify the -t option:
1.63 -
1.64 - python test.py tests/logical.py -t
1.65 + python test.py tests/logical.py -s logical_program
1.66
1.67 -To run all tests, use the test_all.py program:
1.68 -
1.69 - python test_all.py
1.70 +The files in the indicated directory will then be suitable for processing by
1.71 +tools that understand Syspython.
1.72
1.73 Program Reports/Summaries
1.74 -------------------------
1.75 @@ -92,14 +79,16 @@
1.76 credibility. If a toolchain cannot even produce working programs then any
1.77 discussion of relative performance becomes academic.
1.78
1.79 -Thus, an attempt has been made to make a genuine compiler and virtual machine
1.80 -that can run and test compiled programs, hopefully modelling a sufficiently
1.81 -realistic architecture without any unjustified shortcuts being taken to
1.82 -produce the desired program behaviour. This virtual machine and the code
1.83 -generation activity that is needed to exercise it can be regarded as
1.84 -distractions from the principal merits of the software: the analysis activity
1.85 -that attempts to define and indicate the structure and properties of a
1.86 -reasonable subset of the Python language and its semantics.
1.87 +Thus, an attempt has been made to make a genuine compiler and output
1.88 +representation, together with a virtual machine that can run and test compiled
1.89 +programs (previously part of this distribution, but now under separate
1.90 +development), hopefully modelling a sufficiently realistic architecture
1.91 +without any unjustified shortcuts being taken to produce the desired program
1.92 +behaviour. This virtual machine and the code generation activity that is
1.93 +needed to exercise it can be regarded as distractions from the principal
1.94 +merits of the software: the analysis activity that attempts to define and
1.95 +indicate the structure and properties of a reasonable subset of the Python
1.96 +language and its semantics.
1.97
1.98 With limited time to spend on the project, some activities are regarded as
1.99 more rewarding than others. Making a viable virtual machine or runtime
1.100 @@ -107,7 +96,10 @@
1.101 real machine architectures, at least if it is to be done in an optimal
1.102 fashion. Experimenting with garbage collection strategies and memory
1.103 allocation are interesting projects but can also be considered as peripheral
1.104 -activities that can consume substantial amounts of effort.
1.105 +activities that can consume substantial amounts of effort. Thus, the virtual
1.106 +machine activity is now separate and the Syspython output representation has
1.107 +been adopted as an intermediary between this work and the virtual machine
1.108 +effort.
1.109
1.110 It is therefore likely that interoperability with other projects and tools may
1.111 take precedence over the production of a complete system that can target
