README for the TinyOS Make System created on 7 Jan 2004 written by Cory Sharp updated on 16 Apr 2004 by Cory Sharp To describe new TOSMAKE_INCLUDE variable for user make subdirectories. $Id$ ---------------------------------------------------------------------------- Introduction ---------------------------------------------------------------------------- This is a new make system. It's nicer than the old apps/Makerules, especially for adding new targets and platforms. Basically, new features can be added without getting in the way of existing make platforms and rules. ---------------------------------------------------------------------------- Quick Start ---------------------------------------------------------------------------- To use this build system, GNU Make 3.80 or greater is required; check with "make --version". Then, set MAKERULES, find an application, and try make export MAKERULES=`ncc -print-tosdir`/../tools/make/Makerules cd `ncc -print-tosdir`/../apps/Blink #or any app dir make telos help The end of this document has a few notes on some issues that can arise with GNU Make 3.80. ---------------------------------------------------------------------------- Directory Structure and Naming Conventions ---------------------------------------------------------------------------- The root of the make system is the make/ directory in which this README is located. You'll find two main types of files with the extensions .target and .extra. Both types of files define valid make goals. A target file must define a valid make target of the same name. An extra file automatically has a dummy target created for it, making it useful for defining extra make variables given a particular goal on the command line. There are also subdirectories in make/, such as make/avr/ and make/hc08/. Files in these directories are not exposed to the current build unless imported from another goal. For instance, the mica2 target imports the avr/ directory with the command "$(call TOSMake_include_platform,avr)", which further exposes the target and extra files in the avr subdirectory as valid goals for the current build. The TOSMake_include_platform function expects to find a .rules file of the same name as the directory, such as avr/avr.rules. It is expected that the primary build behavior occurs in a platform/platform.rules file (such as avr/avr.rules). Further target and extra goals in that platform make directory should augment the behavior of the rules file. Then, platform build targets are globally exposed by creating a simple .target file in the make/ root. Overall, this structure gives a lot of opportunity to change the behavior of a build given goals on the command line with few or no ifdef's in the makefiles. And, each make behavior is localized to a single file, which I think should be pretty nice. There's also a make/Makerules file. Do not edit make/Makerules. No new build features should ever be exposed via make/Makerules, but rather though the .rules, .target, and .extra files. Let me repeat, do not edit make/Makerules, add new features elsewhere. make/Makerules is the frontend that defines the structure and behavior on those special file extensions. ---------------------------------------------------------------------------- User make/ directories ---------------------------------------------------------------------------- I've added a new variable TOSMAKE_PATH that allows you to define additional root directories for the TinyOS Make System that behave just like the primary make/ directory. In one of your own make files, just add one or more directories to TOSMAKE_PATH sometime before make/Makerules is included: TOSMAKE_PATH += $(TOSDIR)/../contrib/eyes/make That's all you need, and you're in business. Enjoy. ---------------------------------------------------------------------------- make 3.80 ---------------------------------------------------------------------------- The standard version of GNU Make 3.80 (based on October 2002 source) has a bug which this make system can trigger. If a make variable is longer than 200 bytes (characters), then make will report that it has run out of virtual memory and exit. This can happen if, for example, your application depends on a lot of Java/mig message classes, which are BUILD_EXTRA_DEPS. The only way to fix this problem is to use a newer, patched version of make 3.80. All TinyOS releases after 1.1.8 should have a patched version, and will work properly. Pre-1.1.7 versions, however, may run into this problem; you can either upgrade to >= 1.1.8, or download the make source, apply the patch 'eval-crash.diff' in this directory, and compile then install the patched version. ---------------------------------------------------------------------------- Go go go ---------------------------------------------------------------------------- ... okay, hopefully that's enough head's up that you can poke around this directory tree and add new targets, extras, and platforms. Good luck, and holler if you want more documentation.