README-BUILDING

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