The PyMite Build System

Author: Dean Hall
Id:BuildSystem.txt 213 2007-05-06 15:04:07Z dwhall

Purpose

This document describes the build system for the PyMite project. In doing so, it serves both as a design document for the PyMite developer and a user manual for the PyMite user.

Overview

PyMite shall use a makefile based build system with an allowance for using features of GNU make. The project shall have a Makefile in the project root directory that, when called by typing make at the command prompt, will compile:

  • the PyMite standard library src/lib/ to an image file, src/vm/pmstdlib_img.c, and native code file, src/vm/pmstdlib_nat.c
  • the PyMite VM to an archive, libpmvm.a that shall be linked with PyMite end-user programs.

More options for building the project are available by using the available make targets as explained in the next section.

The PyMite project has a src/lib/ directory that differs in meaning from most software projects. Most projects compile source code to create a library as a product and put that library in a lib/ directory. PyMite, on the other hand, converts Python code that is meant to run inside the PyMite VM to an image file, an equivalent to a .pyc file. The image file is a C file, pmstdlib_img.c, containing an array of bytes. The file containing the image of the PyMite libraries is what is built when make is run in src/lib/.

Requirements

The PyMite build process requires Python version 2.4 or later to be used to compile Python source for use in PyMite. While most semantics in PyMite need only Python 2.0 or later, the assert statement specifically requires Python 2.4. This is because the bytecode generated from an assert statement changed in Python 2.4. PyMite attempts to keep up-to-date with the desktop Python and therefore implements the 2.4 method of handling assert. Python 2.5 is supported and may be used.

Available Targets

GNU projects have, by convention, a set of typical targets that can be built. The PyMite build system shall support the following set of targets by typing make <target> at the command prompt:

all:
Compiles the entire program. This shall be the default target.
clean:
Deletes all files in the current directory that are normally created by building the program. Also deletes files in other directories if they are created by this makefile.
TAGS:
Updates a tags table for this program. Also updates a cscope database for the VM and pmstdlib source code.
html:
Generates the documentation files from docs/src/ and places the output HTML files in docs/html/.
dist:
Create a distribution tar file for this program. This target should only be used by the PyMite release manager.
check:
Compiles and executes PyMite self-tests found in src/tests/.

Build Options

There are a handful of build options that one can provide to make that alter PyMite's behavior or set its configuration in some way. The following is a list of the build options and their possible values.

DEBUG:
Builds PyMite with extra debugging information and code. Possible values: true, false. The default is false. Example: make DEBUG=true
HEAP_SIZE:
Specifies the desired size of the PyMite heap in bytes. Possible values can be any positive integer. To avoid errors, the size should be less than the size of physical memory and (for 32-bit targets) an integer multiple of 4. The default value depends on the TARGET. See the Makefile for details. Example: make HEAP_SIZE=0x1000
TARGET:
Specifies the intended build target. Possible values: AT91SAM7S, AVR, DESKTOP. The default is DESKTOP. Example: make TARGET=AVR
TARGET_MCU:
Specifies the precise chip to compile for when TARGET is something other than DESKTOP. For example, if the TARGET=AVR, the TARGET_MCU can be any value that would be given as an argument to avr-gcc -mmcu. The default value depends on TARGET; there is no value when TARGET is DESKTOP. See the Makefile for details. Example: make TARGET=AVR TARGET_MCU=atmega128.

Self Testing

PyMite has both unit tests and system tests to provide some amount of code validity. Running make check will build the VM if needed and all self tests and then execute the self tests. More details on self tests can be found in Testing

Testing the VM is primarily intended for the desktop target because the desktop offers greater resources (size and execution speed) and can quickly run all test programs in a batch and report any failures through the command interface.

Running individual test programs on the target device is possible, but one must either painstakingly step through the program using a debugger or devise a way to determine the exit code of the VM. Perhaps running on a device simulator is a better option.

Distribution

The PyMite release manager should be the only one who uses the distribution target. The makefiles shall be configured so that all the release manager must do is run make dist PYMITE_RELEASE=RR (where RR is the release number, in hexadecimal) to create the release file, pymite-RR.tar.gz.

The html documentation shall be pre-built and included in the release file.