# HG changeset patch # User Paul Boddie # Date 1337637590 -7200 # Node ID 41b26d6cd7ea0c083e9652c457d54ac835c08f7f # Parent 705454dffaae38931280a969b606b2c07c881033 Expanded the documentation, adding prerequisites, reports and roadmap sections. Updated the copyright information. diff -r 705454dffaae -r 41b26d6cd7ea README.txt --- a/README.txt Mon May 21 23:11:04 2012 +0200 +++ b/README.txt Mon May 21 23:59:50 2012 +0200 @@ -11,6 +11,27 @@ probably be implemented as short macros or library routines in programs translated to the instruction set of a real target processor. +Prerequisites +------------- + +Micropython uses a forked version of the compiler package originating from the +Python standard library. This package should be made available to Micropython +using the PYTHONPATH environment variable or copied into the distribution +directory of this software. See the following locations for the code for this +compiler package variant: + +http://hgweb.boddie.org.uk/python2.5-compiler-package/ +http://hgweb.boddie.org.uk/python2.6-compiler-package/ +http://hgweb.boddie.org.uk/python2.7-compiler-package/ + +It should be sufficient to use the Python 2.6 package for systems running +Python 2.5 or 2.6 since the underlying standard library does not seem to have +changed significantly between these releases and the language syntax is +sufficiently similar. For Python 2.7, the appropriate variant may be +preferable or even required due to standard library and syntax changes in that +release of the language implementation, but this has not yet been tested in +any depth. + Quick Start ----------- @@ -47,12 +68,72 @@ substantially faster. Optimisations should not cause programs to fail: they should all always be "safe" to apply. +Program Reports/Summaries +------------------------- + +Using the test.py program, reports can be generated which should show the +modules present in a given program, with each module's code annotated with +scope, attribute and inferred type information. For example: + + python test.py tests/logical.py -omax -d logical_report + +This should produce a number of files in the logical_report directory. + + * The __main__ module, being the "main" file of any given program will + always be described by the __main__.xhtml file. + + * Imported modules will be described by files whose names contain the module + path for such modules, such as compiler.ast.xhtml (for the compiler.ast + module) or sys.xhtml (for the sys module). + +In addition, a summary of the classes defined by each module should be +generated, and these files will have a "-summary" suffix added to the basename +of each module filename. For example, compiler.ast.xhtml will have a +corresponding summary file called compiler.ast-summary.xhtml (summarising +classes in the compiler.ast module). + +Roadmap +------- + +Writing a language toolchain is a huge undertaking involving numerous +activities, many of which are hastily described in the TO_DO.txt file. It is +tempting to write a source code analyser and to then claim that it could be +used as part of a larger system offering performance benefits in comparison to +other toolchains or implementations of a language, but the feasibility of such +a system should be at least demonstrated for such claims to have much +credibility. If a toolchain cannot even produce working programs then any +discussion of relative performance becomes academic. + +Thus, an attempt has been made to make a genuine compiler and virtual machine +that can run and test compiled programs, hopefully modelling a sufficiently +realistic architecture without any unjustified shortcuts being taken to +produce the desired program behaviour. This virtual machine and the code +generation activity that is needed to exercise it can be regarded as +distractions from the principal merits of the software: the analysis activity +that attempts to define and indicate the structure and properties of a +reasonable subset of the Python language and its semantics. + +With limited time to spend on the project, some activities are regarded as +more rewarding than others. Making a viable virtual machine or runtime +environment is a demanding task in itself, as is generating machine code for +real machine architectures, at least if it is to be done in an optimal +fashion. Experimenting with garbage collection strategies and memory +allocation are interesting projects but can also be considered as peripheral +activities that can consume substantial amounts of effort. + +It is therefore likely that interoperability with other projects and tools may +take precedence over the production of a complete system that can target +various machine architectures and offer the ability to compile Python programs +for deployment as directly executable code. Nevertheless, the ability to +generate programs for deployment on microcomputers and microcontrollers - one +of the initial motivations - remains a long-term goal. + Contact, Copyright and Licence Information ------------------------------------------ The current Web page for micropython at the time of release is: -http://www.boddie.org.uk/python/micropython.html +http://hgweb.boddie.org.uk/micropython Copyright and licence information can be found in the docs directory - see docs/COPYING.txt and docs/gpl-3.0.txt for more information. diff -r 705454dffaae -r 41b26d6cd7ea docs/COPYING.txt --- a/docs/COPYING.txt Mon May 21 23:11:04 2012 +0200 +++ b/docs/COPYING.txt Mon May 21 23:59:50 2012 +0200 @@ -1,7 +1,7 @@ Licence Agreement for micropython --------------------------------- -Copyright (C) 2006, 2007, 2008, 2009, 2010 Paul Boddie +Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011, 2012 Paul Boddie This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software