Source

pymite / README

======
PyMite
======

:Author:    Dean Hall
:Copyright: Copyright 2002 Dean Hall.
            See `License`_ for details.
:Release:   06
:Site:      http://pymite.python-hosting.com/
:Id:        $Id: README 116 2006-08-24 13:42:09Z dwhall $

Purpose
-------

PyMite is a flyweight Python interpreter written from scratch to execute
on 8-bit and larger microcontrollers with resources as limited as 64 KiB
of program memory (flash) and 4 KiB of RAM. PyMite supports a subset of
the Python 2.5 syntax and can execute a subset of the Python 2.5 bytecodes.
PyMite can also be compiled, tested and executed on a desktop computer.

License
-------

All of the source code for PyMite is licensed under the GNU General
Public License v2.  A copy of the license is in the file ``LICENSE``.

    Copyright 2002 Dean Hall.

    This program is free software; you can redistribute it and/or
    modify it under the terms of version 2 of the GNU General
    Public License as published by the Free Software Foundation.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public
    License along with this program; if not, write to the Free
    Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA  02110-1301, USA

All of the documentation and images for PyMite are
licensed under the GNU Free Documentation License.

    Copyright 2006 Dean Hall

    Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.2
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
    Texts.  A copy of the license is in the file ``docs/LICENSE``.

Build
-----

Perform the following steps to build PyMite and the included
system tests on the desktop:

    1. In the project root, run ``make`` to create ``libpmvm.a``
    2. In the project root, run ``make check`` to build and run
       the unit tests and the system tests.

To build for AVR targets like the ATmega103 (refer to the Makefile for others):

    1. In the project root, run ``make clean; make TARGET=AVR``
    2. In ``src/sample/avr`` run ``make`` to build a sample program for the AVR.

The development system should have installed the GNU Compiler
Collection version 3.4 or later and Python 2.5 or later.
The author also uses avr-gcc to target Atmel AVR microcontrollers.

PyMite is developed on Mac OS X and should also compile on
GNU/Linux and Cygwin operating systems.  Since PyMite is so
deeply embedded, it does not rely on many libraries.
When compiling for the AVR, it will need avr-libc.

PyMite builds as an archive.  The user should then build his
own main() function following examples in ``src/sample/`` and link to
``libpmvm.a`` and the appropriate PyMite native libraries.

Discussion
----------

Please review the `PyMite Trac`_ project management space
space for up-to-date information about PyMite.
Please join the `PyMite maillist`_ for all communications concerning PyMite.
This will ensure that FAQs can be found in the list archives and
all issues are captured and available for public inspection.

.. _`PyMite Trac`: http://pymite.python-hosting.com/
.. _`PyMite maillist`: http://groups.google.com/group/pymite

Thanks
------

My personal thanks go out to these people for their contribution to PyMite:

    - Philipp Adelt: Threading, enhancements to pmImgCreator.py, issues and
      fixes.
    - Josh Lifton: Used PyMite in PhD work, donated many code fixes and tests.
    - www.webfaction.com: for providing quality, free project hosting on
      www.python-hosting.com

Release Notes
-------------

This is PyMite release 06

* Release 06, 2009/01/30

    - #13:  Implement the equivalent of '__name__ == "__main__"' in module attrs
    - #39:  Absorb changes from SnarfVM
    - #101: Backport core objects' new methods from SnarfVM
    - #104: Design and implement garbage collection
    - #111: Remove bytecodes that aren't used in Python 2.5 and later
    - #115: Optimize Dict type's memory use
    - #120: Update the document on how to release PyMite
    - #122: Make GC mark CodeObj's image if it is in RAM
    - #123: Fix GC so it marks native function arguments properly
    - #124: Fix name space for recursive function call
    - #132: VM doesn't throw TypeError when function has wrong number of
      arguments
    - #134: ipm instructions lead to an exception
    - #135: Code "if None" executes the positive case
    - #136: Create module interface for compound datatypes
    - #137: Create release 06

* Release 05, 2007/05/10

    - #116: Created Release 05 package
    - #109: Created check to ensure stack is empty after RETURN_VALUE pops last
      item
    - #114: Created platform file for Atmel's ARM7
    - #112: Forced Dict keys to be of hashable type
    - #105: Moved OBJ_TYPE_THR to some value before OBJ_TYPE_HASHABLE_MAX
    - #108: Cleaned up *_POWER bytecodes
    - #113: Fixed the implementation of builtin map()
    - #68:  Cleaned up code to meet standards
    - #102: Implemented the remaining IMPORT_ bytecodes
    - #46:  Finalized design of string objects
    - #69:  Fixed bitwise operators to prevent automatic promotion
    - #32:  Used GNU indent for code formatting
    - #64:  Renamed MEMSPACE_FLASH to MEMSPACE_PROGMEM
    - #85:  Created new avr sample project
    - #100: Removed od_const bit from object descriptor
    - #103: Implemented obj_print() for other object types
    - #98:  Fixed writing image file for win32 target
    - #99:  Designed a way for ipm to be able to receive images larger than
      HEAP_MAX_CHUNK_SIZE
    - #90:  Created new lib function to return system time
    - #63:  Created mmb sample project
    - #91:  Fixed vm so that error codes are returned by the main() function
    - #93:  Changed ifdef from TARGET_DESKTOP to a debug-oriented definition
      where it is appropriate
    - #70:  Fixed incorrect exception for chr('a')
    - #96:  Created library function to spawn a new thread
    - #82:  Fixed namespace issue
    - #95:  Fixed sys.heap() so it doesn't overwrite the static const 0 integer
      obj
    - #94:  Fixed integer loading from image so it re-uses static ints (-1,0,1).
    - #89:  Moved plat module functions into sys module
    - #88:  Created library function to return heap stats
    - #84:  Fixed bus error when using ipm
    - #87:  Redesigned the heap
    - #86:  Moved as much platform-specific code to the platform implementation
      file
    - #83:  Updated documentation to reflect new size requirement
    - #74:  Added to pmImgCreator a filter to catch constants of unsupported
      types
    - #65:  Created plat module with put and get routines
    - #71:  Added support for builtin function eval()
    - #80:  Fixed DUP_TOPX bytecode
    - #81:  Implemented list_setItem()
    - #67:  Created interactive interface
    - #78:  Fixed import module yields None
    - #76:  Printed always escapes special characters and puts quotes around it
    - #75:  Supported multiple (green) threads inside PyMite

* Release 04, 2006/12/14

    - #62:  Created Release 04 package
    - #51:  Updated to Python 2.5 bytecodes
    - #57:  Created doc showing what PyMite does [not] support
    - #60:  Implemented heap_sweep
    - #59:  Improved bytecode UNPACK_SEQUENCE
    - #58:  Added support for keyword "in"
    - #26:  Implemented more builtin functions
    - #49:  Removed null check from object methods
    - #56:  Implemented \*_POWER bytecodes
    - #17:  Completed the implementation of obj_isEqual()
    - #54:  Changed seglist API so segnum/segindx are encapsulated
    - #10:  Created sequence_getSubscript()
    - #33:  Created new ARM target
    - #36:  Deprecated dwh_types.h
    - #53:  Fixed Win32/x86 build break
    - #38:  Made use of pycscope.py conditional in Makefile
    - #37:  Created PM_RAISE()
    - #34:  Converted all "Py" to "Pm"
    - #50:  Integrated __LINE__ into PM_RAISE
    - #48:  Organized and deploy unit tests
    - #45:  Finished interpret loop edits
    - #35:  Macroized all operations on object descriptors
    - #42:  Fixed misuse of PM_RAISE
    - #43:  Fixed mem_getInt()
    - #40:  Fixed heap chunk transfer

* Release 03, 2006/09/17

    - #30:  Created Release 03 package
    - #4:   Enabled compiler warnings as errors
    - #7:   Unified licensing and copyright info in all files
    - #16:  Created pm_init() that does the initial housekeeping
    - #29:  Corrected function call in mmb.py's sleepms()
    - #28:  Fixed loader to modules with root-level __NATIVE__ docstring load
    - #2:   Separated stdlib from user app
    - #27:  Made S16/U16 really be 16-bits on DESKTOP
    - #20:  Added support for the assert statement
    - #25:  Created slide-compatible illustration for build process
    - #24:  Removed consts[0] == docstring assumption from pmImgCreator
    - #3:   Made src/tests/Makefile clean better
    - #23:  Removed absolute paths to allow building with WinAVR
    - #18:  Removed "-ansi" compiler option from AVR builds
    - #19:  Broadened target from ATMEGA103 to AVR
    - #11:  Made src/tests/ build module images as C files, not header files
    - #9:   Fixed BINARY_SUBSCR for case stringobj[intobj]
    - #14:  Documented the development process
    - #6:   Made pmImgCreator append a null terminator to image list
    - #8:   Removed leftover uses of ``HOST_``
    - #12:  Made mem_* funcs always use RAM memspace when target is DESKTOP
    - #15:  All mem_*() funcs and pointers in the vm should use unsigned not
      signed or void
    - #1:   Transfered PyMite repository to http://pymite.python-hosting.com

* Release 02, 2006/08/11

    - N/A:  Create Release v 02 package.
    - N/A:  VM funcs modified so that return objects are by
      reference and funcs return a PyReturn_t for internal
      error checking.  Library modules are broken until they
      are modified similarly.
    - N/A:  The pmImgCreator.py script was modified to work via
      the command line. pmImgCreator GUI is deprecated.
    - N/A:  Converted many files' EOLs to Unix.

* Release 01, 2003/03/18

    - N/A:  Initial release made for PyCon 2003.
    - N/A:  Compiles for desktop and Atmel ATmega103.

.. :mode=rest:
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.