Author: | Dean Hall |
---|---|
Id: | BuildSystem.txt 213 2007-05-06 15:04:07Z dwhall |
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.
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/.
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.
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:
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.
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.
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.