1.1 --- a/README.txt Mon May 21 23:11:04 2012 +0200
1.2 +++ b/README.txt Mon May 21 23:59:50 2012 +0200
1.3 @@ -11,6 +11,27 @@
1.4 probably be implemented as short macros or library routines in programs
1.5 translated to the instruction set of a real target processor.
1.6
1.7 +Prerequisites
1.8 +-------------
1.9 +
1.10 +Micropython uses a forked version of the compiler package originating from the
1.11 +Python standard library. This package should be made available to Micropython
1.12 +using the PYTHONPATH environment variable or copied into the distribution
1.13 +directory of this software. See the following locations for the code for this
1.14 +compiler package variant:
1.15 +
1.16 +http://hgweb.boddie.org.uk/python2.5-compiler-package/
1.17 +http://hgweb.boddie.org.uk/python2.6-compiler-package/
1.18 +http://hgweb.boddie.org.uk/python2.7-compiler-package/
1.19 +
1.20 +It should be sufficient to use the Python 2.6 package for systems running
1.21 +Python 2.5 or 2.6 since the underlying standard library does not seem to have
1.22 +changed significantly between these releases and the language syntax is
1.23 +sufficiently similar. For Python 2.7, the appropriate variant may be
1.24 +preferable or even required due to standard library and syntax changes in that
1.25 +release of the language implementation, but this has not yet been tested in
1.26 +any depth.
1.27 +
1.28 Quick Start
1.29 -----------
1.30
1.31 @@ -47,12 +68,72 @@
1.32 substantially faster. Optimisations should not cause programs to fail: they
1.33 should all always be "safe" to apply.
1.34
1.35 +Program Reports/Summaries
1.36 +-------------------------
1.37 +
1.38 +Using the test.py program, reports can be generated which should show the
1.39 +modules present in a given program, with each module's code annotated with
1.40 +scope, attribute and inferred type information. For example:
1.41 +
1.42 + python test.py tests/logical.py -omax -d logical_report
1.43 +
1.44 +This should produce a number of files in the logical_report directory.
1.45 +
1.46 + * The __main__ module, being the "main" file of any given program will
1.47 + always be described by the __main__.xhtml file.
1.48 +
1.49 + * Imported modules will be described by files whose names contain the module
1.50 + path for such modules, such as compiler.ast.xhtml (for the compiler.ast
1.51 + module) or sys.xhtml (for the sys module).
1.52 +
1.53 +In addition, a summary of the classes defined by each module should be
1.54 +generated, and these files will have a "-summary" suffix added to the basename
1.55 +of each module filename. For example, compiler.ast.xhtml will have a
1.56 +corresponding summary file called compiler.ast-summary.xhtml (summarising
1.57 +classes in the compiler.ast module).
1.58 +
1.59 +Roadmap
1.60 +-------
1.61 +
1.62 +Writing a language toolchain is a huge undertaking involving numerous
1.63 +activities, many of which are hastily described in the TO_DO.txt file. It is
1.64 +tempting to write a source code analyser and to then claim that it could be
1.65 +used as part of a larger system offering performance benefits in comparison to
1.66 +other toolchains or implementations of a language, but the feasibility of such
1.67 +a system should be at least demonstrated for such claims to have much
1.68 +credibility. If a toolchain cannot even produce working programs then any
1.69 +discussion of relative performance becomes academic.
1.70 +
1.71 +Thus, an attempt has been made to make a genuine compiler and virtual machine
1.72 +that can run and test compiled programs, hopefully modelling a sufficiently
1.73 +realistic architecture without any unjustified shortcuts being taken to
1.74 +produce the desired program behaviour. This virtual machine and the code
1.75 +generation activity that is needed to exercise it can be regarded as
1.76 +distractions from the principal merits of the software: the analysis activity
1.77 +that attempts to define and indicate the structure and properties of a
1.78 +reasonable subset of the Python language and its semantics.
1.79 +
1.80 +With limited time to spend on the project, some activities are regarded as
1.81 +more rewarding than others. Making a viable virtual machine or runtime
1.82 +environment is a demanding task in itself, as is generating machine code for
1.83 +real machine architectures, at least if it is to be done in an optimal
1.84 +fashion. Experimenting with garbage collection strategies and memory
1.85 +allocation are interesting projects but can also be considered as peripheral
1.86 +activities that can consume substantial amounts of effort.
1.87 +
1.88 +It is therefore likely that interoperability with other projects and tools may
1.89 +take precedence over the production of a complete system that can target
1.90 +various machine architectures and offer the ability to compile Python programs
1.91 +for deployment as directly executable code. Nevertheless, the ability to
1.92 +generate programs for deployment on microcomputers and microcontrollers - one
1.93 +of the initial motivations - remains a long-term goal.
1.94 +
1.95 Contact, Copyright and Licence Information
1.96 ------------------------------------------
1.97
1.98 The current Web page for micropython at the time of release is:
1.99
1.100 -http://www.boddie.org.uk/python/micropython.html
1.101 +http://hgweb.boddie.org.uk/micropython
1.102
1.103 Copyright and licence information can be found in the docs directory - see
1.104 docs/COPYING.txt and docs/gpl-3.0.txt for more information.