readme

tinyos-2.x.rar

README for the TinyOS Make System
created on 7 Jan 2004
written by Cory Sharp <[e-mail]>

updated on 16 Apr 2004 by Cory Sharp
To describe new TOSMAKE_INCLUDE variable for user make subdirectories.


$Id: README,v 1.4 2006/12/12 18:22:55 vlahan Exp $


----------------------------------------------------------------------------
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.