doc/build-system.txt

   1 /**
   2  \defgroup buildsystem The Contiki build system
   3
   4  .
   5
   6  The Contiki build system is designed to make it easy to compile
   7  Contiki applications for either to a hardware platform or into a
   8  simulation platform by simply supplying different parameters to the
   9  <tt>make</tt> command, without having to edit makefiles or modify
  10  the application code.
  11
  12  The file example project in examples/hello-world/ shows how the
  13  Contiki build system works. The <tt>hello-world.c</tt> application
  14  can be built into a complete Contiki system by running <tt>make</tt>
  15  in the examples/hello-world/ directory. Running <tt>make</tt> without
  16  parameters will build a Contiki system using the <tt>native</tt>
  17  target. The <tt>native</tt> target is a special Contiki platform that
  18  builds an entire Contiki system as a program that runs on the
  19  development system. After compiling the application for the
  20  <tt>native</tt> target it is possible to run the Contiki system with
  21  the application by running the file <tt>hello-world.native</tt>. To
  22  compile the application and a Contiki system for the \ref esb "ESB
  23  platform" the command <tt>make TARGET=esb</tt> is used. This produces
  24  a hello-world.esb file that can be loaded into an ESB board.
  25
  26  To compile the hello-world application into a stand-alone executable
  27  that can be loaded into a running Contiki system, the command
  28  <tt>make hello-world.ce</tt> is used. To build an executable file for
  29  the ESB platform, <tt>make TARGET=esb hello-world.ce</tt> is run.
  30
  31  To avoid having to type <tt>TARGET=</tt> every time <tt>make</tt> is
  32  run, it is possible to run <tt>make TARGET=esb savetarget</tt> to
  33  save the selected target as the default target platform for
  34  subsequent invocations of <tt>make</tt>. A file called
  35  <tt>Makefile.target</tt> containing the currently saved target is
  36  saved in the project's directory.
  37
  38  \section buildsystem-makefiles Makefiles used in the Contiki build system
  39
  40  The Contiki build system is composed of a number of Makefiles. These
  41  are:
  42  - <tt>Makefile</tt>: the project's makefile, located in the project directory.
  43  - <tt>Makefile.include</tt>: the system-wide Contiki makefile,
  44  located in the root of the Contiki source tree.
  45  - <tt>Makefile.\$(TARGET)</tt> (where \$(TARGET) is the name of the
  46  platform that is currently being built): rules for the specific
  47  platform, located in the platform's subdirectory in the platform/ directory.
  48  - <tt>Makefile.\$(CPU)</tt> (where \$(CPU) is the name of the CPU or
  49  microcontroller architecture used on the platform for which Contiki
  50  is built): rules for the CPU architecture, located in the CPU
  51  architecture's subdirectory in the cpu/ directory.
  52  - <tt>Makefile.\$(APP)</tt> (where \$(APP) is the name of an
  53  application in the apps/ directory): rules for applications in the
  54  apps/ directories. Each application has its own makefile.
  55
  56  The Makefile in the project's directory is intentionally simple. It
  57  specifies where the Contiki source code resides in the system and
  58  includes the system-wide Makefile, <tt>Makefile.include</tt>. The
  59  project's makefile can also define in the <tt>APPS</tt> variable a
  60  list of applications from the apps/ directory that should be included
  61  in the Contiki system. The Makefile used in the hello-world example
  62  project looks like this:
  63
  64  \code
  65 CONTIKI = ../..
  66 all: hello-world
  67 include $(CONTIKI)/Makefile.include
  68  \endcode
  69
  70  First, the location of the Contiki source code tree is given by
  71  defining the <tt>CONTIKI</tt> variable. Next, the name of the
  72  application is defined. Finally, the system-wide
  73  <tt>Makefile.include</tt> is included.
  74
  75  The <tt>Makefile.include</tt> contains definitions of the C files of
  76  the core Contiki system. <tt>Makefile.include</tt> always reside in
  77  the root of the Contiki source tree. When <tt>make</tt> is run,
  78  <tt>Makefile.include</tt> includes the <tt>Makefile.\$(TARGET)</tt>
  79  as well as all makefiles for the applications in the <tt>APPS</tt>
  80  list (which is specified by the project's <tt>Makefile</tt>).
  81
  82  <tt>Makefile.\$(TARGET)</tt>, which is located in the
  83  platform/\$(TARGET)/ directory, contains the list of C files that the
  84  platform adds to the Contiki system. This list is defined by the
  85  <tt>CONTIKI_TARGET_SOURCEFILES</tt> variable. The
  86  <tt>Makefile.\$(TARGET)</tt> also includes the
  87  <tt>Makefile.\$(CPU)</tt> from the cpu/\$(CPU)/ directory.
  88
  89  The <tt>Makefile.\$(CPU)</tt> typically contains definitions for the
  90  C compiler used for the particular CPU. If multiple C compilers are
  91  used, the <tt>Makefile.\$(CPU)</tt> can either contain a conditional
  92  expression that allows different C compilers to be defined, or it can
  93  be completely overridden by the platform specific makefile
  94  <tt>Makefile.\$(TARGET)</tt>.
  95 @{
  96  */
  97
  98  /**
  99  @}
 100  */
 101