Added documentation of the Contiki build system

This commit is contained in:
adamdunkels 2006-10-02 22:04:09 +00:00
parent 5a7034fe5d
commit 60c700b66e
3 changed files with 132 additions and 11 deletions

View file

@ -78,7 +78,7 @@ INPUT = contiki-mainpage.txt net.txt dev.txt \
uip-doc.txt \
code-style.txt \
examples.txt \
uip-doc.txt \
uip-doc.txt build-system.txt \
../apps/program-handler/program-handler.c \
../core/sys/process.c \
../core/sys/process.h \
@ -143,12 +143,13 @@ INPUT = contiki-mainpage.txt net.txt dev.txt \
../core/lib/crc16.c \
../platform/esb/doc/esb.txt \
../platform/esb/doc/slipintro.txt \
../platform/esb/doc/winintro.txt \
../platform/esb/dev/beep.h \
../platform/esb/dev/eeprom.c \
../platform/esb/dev/rs232.h \
../platform/esb/dev/rs232.c \
../platform/esb/dev/tr1001.c
../platform/esb/dev/tr1001.c \
../platform/win32/doc/getting-started.txt
FILE_PATTERNS =
RECURSIVE = NO
EXCLUDE =

101
doc/build-system.txt Normal file
View file

@ -0,0 +1,101 @@
/**
\defgroup buildsystem The Contiki build system
.
The Contiki build system is designed to make it easy to compile
Contiki applications for either to a hardware platform or into a
simulation platform by simply supplying different parameters to the
<tt>make</tt> command, without having to edit makefiles or modify
the application code.
The file example project in examples/hello-world/ shows how the
Contiki build system works. The <tt>hello-world.c</tt> application
can be built into a complete Contiki system by running <tt>make</tt>
in the examples/hello-world/ directory. Running <tt>make</tt> without
parameters will build a Contiki system using the <tt>native</tt>
target. The <tt>native</tt> target is a special Contiki platform that
builds an entire Contiki system as a program that runs on the
development system. After compiling the application for the
<tt>native</tt> target it is possible to run the Contiki system with
the application by running the file <tt>hello-world.native</tt>. To
compile the application and a Contiki system for the \ref esb "ESB
platform" the command <tt>make TARGET=esb</tt> is used. This produces
a hello-world.esb file that can be loaded into an ESB board.
To compile the hello-world application into a stand-alone executable
that can be loaded into a running Contiki system, the command
<tt>make hello-world.ce</tt> is used. To build an executable file for
the ESB platform, <tt>make TARGET=esb hello-world.ce</tt> is run.
To avoid having to type <tt>TARGET=</tt> every time <tt>make</tt> is
run, it is possible to run <tt>make TARGET=esb savetarget</tt> to
save the selected target as the default target platform for
subsequent invocations of <tt>make</tt>. A file called
<tt>Makefile.target</tt> containing the currently saved target is
saved in the project's directory.
\section buildsystem-makefiles Makefiles used in the Contiki build system
The Contiki build system is composed of a number of Makefiles. These
are:
- <tt>Makefile</tt>: the project's makefile, located in the project directory.
- <tt>Makefile.include</tt>: the system-wide Contiki makefile,
located in the root of the Contiki source tree.
- <tt>Makefile.\$(TARGET)</tt> (where \$(TARGET) is the name of the
platform that is currently being built): rules for the specific
platform, located in the platform's subdirectory in the platform/ directory.
- <tt>Makefile.\$(CPU)</tt> (where \$(CPU) is the name of the CPU or
microcontroller architecture used on the platform for which Contiki
is built): rules for the CPU architecture, located in the CPU
architecture's subdirectory in the cpu/ directory.
- <tt>Makefile.\$(APP)</tt> (where \$(APP) is the name of an
application in the apps/ directory): rules for applications in the
apps/ directories. Each application has its own makefile.
The Makefile in the project's directory is intentionally simple. It
specifies where the Contiki source code resides in the system and
includes the system-wide Makefile, <tt>Makefile.include</tt>. The
project's makefile can also define in the <tt>APPS</tt> variable a
list of applications from the apps/ directory that should be included
in the Contiki system. The Makefile used in the hello-world example
project looks like this:
\code
CONTIKI = ../..
all: hello-world
include $(CONTIKI)/Makefile.include
\endcode
First, the location of the Contiki source code tree is given by
defining the <tt>CONTIKI</tt> variable. Next, the name of the
application is defined. Finally, the system-wide
<tt>Makefile.include</tt> is included.
The <tt>Makefile.include</tt> contains definitions of the C files of
the core Contiki system. <tt>Makefile.include</tt> always reside in
the root of the Contiki source tree. When <tt>make</tt> is run,
<tt>Makefile.include</tt> includes the <tt>Makefile.\$(TARGET)</tt>
as well as all makefiles for the applications in the <tt>APPS</tt>
list (which is specified by the project's <tt>Makefile</tt>).
<tt>Makefile.\$(TARGET)</tt>, which is located in the
platform/\$(TARGET)/ directory, contains the list of C files that the
platform adds to the Contiki system. This list is defined by the
<tt>CONTIKI_TARGET_SOURCEFILES</tt> variable. The
<tt>Makefile.\$(TARGET)</tt> also includes the
<tt>Makefile.\$(CPU)</tt> from the cpu/\$(CPU)/ directory.
The <tt>Makefile.\$(CPU)</tt> typically contains definitions for the
C compiler used for the particular CPU. If multiple C compilers are
used, the <tt>Makefile.\$(CPU)</tt> can either contain a conditional
expression that allows different C compilers to be defined, or it can
be completely overridden by the platform specific makefile
<tt>Makefile.\$(TARGET)</tt>.
@{
*/
/**
@}
*/

View file

@ -20,15 +20,23 @@ available as open source under a BSD-style license. More information
about Contiki can be found at the Contiki home page:
http://www.sics.se/~adam/contiki/
\section contiki-mainpage-tcpip TCP/IP support
\section contiki-mainpage-getting-started Getting started with Contiki
Contiki includes the uIP TCP/IP stack (http://www.sics.se/~adam/uip/)
that provides Contiki with TCP/IP networking support. uIP provides the
protocols TCP, UDP, IP, and ARP.
Contiki is designed to run on many different \ref platform "platforms". It is also
possible to compile and build both the Contiki system and Contiki
applications on many different development platforms.
\sa \ref uip "The uIP TCP/IP stack documentation"
\sa \ref tcpip "The Contiki/uIP interface"
\sa \ref psock "Protosockets library"
See \ref esb-getting-started "Getting started with Contiki for the ESB platform
\section contiki-mainpage-building Building the Contiki system and its applications
The Contiki build system is designed to make it easy to compile
Contiki applications for either to a hardware platform or into a
simulation platform by simply supplying different parameters to the
<tt>make</tt> command, without having to edit makefiles or modify
the application code.
See \ref buildsystem
\section contiki-mainpage-threads Multi-threading and protothreads
@ -50,4 +58,15 @@ and linked list operations.
\sa \ref memb "Memory block management"
\sa \ref list "Linked list library"
\section contiki-mainpage-tcpip TCP/IP support
Contiki includes the uIP TCP/IP stack (http://www.sics.se/~adam/uip/)
that provides Contiki with TCP/IP networking support. uIP provides the
protocols TCP, UDP, IP, and ARP.
\sa \ref uip "The uIP TCP/IP stack documentation"
\sa \ref tcpip "The Contiki/uIP interface"
\sa \ref psock "Protosockets library"
*/