From 60c700b66e7ff3738edddf218f61207492d5ff96 Mon Sep 17 00:00:00 2001 From: adamdunkels Date: Mon, 2 Oct 2006 22:04:09 +0000 Subject: [PATCH] Added documentation of the Contiki build system --- doc/Doxyfile | 7 +-- doc/build-system.txt | 101 +++++++++++++++++++++++++++++++++++++++ doc/contiki-mainpage.txt | 35 ++++++++++---- 3 files changed, 132 insertions(+), 11 deletions(-) create mode 100644 doc/build-system.txt diff --git a/doc/Doxyfile b/doc/Doxyfile index 146a055f6..d8d2cb449 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -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 = diff --git a/doc/build-system.txt b/doc/build-system.txt new file mode 100644 index 000000000..98deb0560 --- /dev/null +++ b/doc/build-system.txt @@ -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 + make 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 hello-world.c application + can be built into a complete Contiki system by running make + in the examples/hello-world/ directory. Running make without + parameters will build a Contiki system using the native + target. The native 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 + native target it is possible to run the Contiki system with + the application by running the file hello-world.native. To + compile the application and a Contiki system for the \ref esb "ESB + platform" the command make TARGET=esb 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 + make hello-world.ce is used. To build an executable file for + the ESB platform, make TARGET=esb hello-world.ce is run. + + To avoid having to type TARGET= every time make is + run, it is possible to run make TARGET=esb savetarget to + save the selected target as the default target platform for + subsequent invocations of make. A file called + Makefile.target 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: + - Makefile: the project's makefile, located in the project directory. + - Makefile.include: the system-wide Contiki makefile, + located in the root of the Contiki source tree. + - Makefile.\$(TARGET) (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. + - Makefile.\$(CPU) (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. + - Makefile.\$(APP) (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, Makefile.include. The + project's makefile can also define in the APPS 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 CONTIKI variable. Next, the name of the + application is defined. Finally, the system-wide + Makefile.include is included. + + The Makefile.include contains definitions of the C files of + the core Contiki system. Makefile.include always reside in + the root of the Contiki source tree. When make is run, + Makefile.include includes the Makefile.\$(TARGET) + as well as all makefiles for the applications in the APPS + list (which is specified by the project's Makefile). + + Makefile.\$(TARGET), 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 + CONTIKI_TARGET_SOURCEFILES variable. The + Makefile.\$(TARGET) also includes the + Makefile.\$(CPU) from the cpu/\$(CPU)/ directory. + + The Makefile.\$(CPU) typically contains definitions for the + C compiler used for the particular CPU. If multiple C compilers are + used, the Makefile.\$(CPU) 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 + Makefile.\$(TARGET). +@{ + */ + + /** + @} + */ + diff --git a/doc/contiki-mainpage.txt b/doc/contiki-mainpage.txt index de7e0c99d..b85f51de9 100644 --- a/doc/contiki-mainpage.txt +++ b/doc/contiki-mainpage.txt @@ -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 + make 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" -*/ \ No newline at end of file +\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" + + +*/