scons_script_how_to.txt

   1 == How to write IoTivity build script ==
   2
   3 IoTivity projects are built with Scons. Scons is a cross-platform build tool,
   4 it's quite similar to 'make'. 'SConstruct' is the entrance of scons build, it's
   5 equivalent to 'Makefile' to 'make'.
   6
   7 This document only a brief reference. Detail about how to write scons script,
   8 please refer to:
   9         http://www.scons.org/doc/production/HTML/scons-user.html#
  10
  11 == Background: How to control source code compiling ==
  12
  13 Environment is a base conception of Scons. An environment is a collection of
  14 values that can affect how a program is built.
  15
  16 e.g. There is a C file named hello.c, enter the following into a file named
  17 SConstruct:
  18         env = Environment()
  19         env.Program('H', 'hello.c')
  20
  21 When run Scons in console, following will be executed:
  22 cc -o hello.o -c hello.c
  23 cc -o H hello.o
  24
  25 If you would like keep debug information in the binary, '-g' flag should be added
  26 when build the source code. To do this, append a C compiler flags as following:
  27         env = Environment()
  28         env.AppendUnique(CFLAGS = ['-g'])
  29         env.Program('H', 'hello.c')
  30
  31 When run Scons, following will be executed:
  32 cc -o hello.o -c -g hello.c
  33 cc -o H hello.o
  34
  35 In above example, 'CFLAGS' is changed. Following list the frequently used keys:
  36
  37 CFLAGS: General options that are passed to the C compiler
  38 CCFLAGS: General options that are passed to the C & C++ compiler
  39 CXXFLAGS: General options that are passed to the C++ compiler
  40 CPPPATH: The directories that the preprocessor will search for include headers.
  41 CPPDEFINES: Platform independent specification of C preprocessor definitions.
  42
  43 Note: CPPPATH and CPPDEFINES is common for all compiler. But others are
  44 compiler specific, when change the key value, it may requried to specify the
  45 target platform(actually the compiler).
  46
  47 e.g.
  48         env.AppendUnique(CPPPATH = ['.', 'include'])
  49         env.AppendUnique(CPPDEFINES = ['NDEBUG', 'VER_TEST'])
  50 Above two lines are fine for all target platform. but below line:
  51         env.AppenUnique(CXXFLAGS = ['-g'])
  52 is only fine for gcc compiler, as '-g' is a gcc flag, other compiler may don't
  53 understand it. so it may should be:
  54         if target_os not in ['windows', 'winrt']:
  55                 env.AppenUnique(CXXFLAGS = ['-g'])
  56
  57 Still take the hello.c as example. Assume hello.h is in ./include/ directory,
  58 #include "hello.h"
  59 int main(int argc, char** argv)
  60 {
  61 #ifdef LANG_FR
  62     printf("Bonjour\n");
  63 #else
  64         printf("Hello\n");
  65 #endif
  66 }
  67
  68 The Scons configure file should as following:
  69         env = Environment()
  70         env.AppendUnique(CFLAGS = ['-g'])
  71         env.AppendUnique(CPPPATH = ['include'])
  72         env.AppendUnique(CPPDEFINES = ['LANG_FR'])
  73         env.Program('H', 'hello.c')
  74
  75 When run Scons, following will be executed:
  76 cc -o hello.o -c -g -Iinclude -DLANG_FR hello.c
  77 cc -o H hello.o
  78
  79 === Get extra information ===
  80
  81 In above example, 'target_os' is used. How to get it?
  82
  83 User can build IoTivity project on Linux / Windows / MAC OSX for various
  84 targets(Linux, Tizen, Android, Arduino, Windows, MAC OSX, IOS ...). Most
  85 platform specific configures have been done in the common scripts which are in
  86 build_common. The common scripts prepare an environment named 'env' with
  87 target platform specific configuration.
  88
  89 When write IoTivity project build script, you can get this environment as
  90 following:
  91         Import('env')
  92
  93 You can use 'env' directly after import it. You can also clone a new environment
  94 and update its keys.
  95
  96         new_env1 = Clone('env')
  97         new_env2 = Clone('env')
  98         new_env1.AppendUnqiue(xxx = [...])
  99         new_env2.AppendUnqiue(xxx = [...])
 100
 101 The 'env' environment contains platform specific configuration, besides, there is
 102 some common information. You can get the information with following line:
 103         env.get('XXX')
 104 or
 105         env['XXX']
 106
 107 XXX is the information name, below are the extra information added by IoTivity
 108 common scrirpts:
 109 BUILD_DIR: the path of the build directory, all output are in this directory
 110 SRC_DIR: the path of the top directory of the source code
 111 OIC_UTILS: the path of oic-utilities project
 112 RELEASE: build type, boolean. True - release build, False - debug build
 113 TARGET_OS: the name of the target OS. The possible value depends on the host
 114         platform. Bellow is the list of host and possible target OS. (darwin means
 115         MAC OSX)
 116                 linux: linux / android / arduino / tizen
 117 (the line means on Linux, you can build the project for Linux/Android/Arduino/Tizen)
 118                 windows: windows / winrt / android / arduino
 119                 darwin: darwin / ios / android / arduino
 120
 121 TARGET_ARCH: the target CPU arch. Its possible value depend on the target OS.
 122         Bellow list the target OS and allowed CPU architecture.
 123                 linux: x86 / x86_64 / arm / arm64
 124 (above line means if the target OS is Linux, the CPU arch can be x86/x86_64/arm/arm64)
 125                 android: x86 / x86_64 / armeabi / armeabi-v7a / armeabi-v7a-hard / arm64-v8a
 126                 windows: x86 / amd64 / arm
 127                 winrt: arm
 128                 darwin: i386 / x86_64
 129                 ios: i386 / x86_64 / armv7 / armv7s / arm64,
 130                 arduino: avr / arm
 131
 132 === Extra functions ===
 133
 134 For convenience, in the common scripts, some extra functions are added.
 135
 136 PrintTargets(): print all targets in the help information.
 137 AppendTarget(target): add 'target' into targets list, when use PrintTargets,
 138         the 'target' will be print.
 139 InstallTarget(files, name): it takes the same action as AppendTarget, besides,
 140         it installs the 'files' to BUILD_DIR.
 141
 142 Following functions are only for Arduino:
 143 ImportLib(lib): Arduino IDE includes many libraries. By default, no library is
 144 compiled. If your project use some libraries, you can import the library by
 145 this function. 'lib' is the name of the library to import. The 'include' path
 146 will be auto added to the environment and the library will be built and linked
 147 into the final binary.
 148
 149 CreateBin('bin', src): For Arduino, after build the program, it's required to
 150 be converted into specific format (e.g .hex). This function will genearate the
 151 required .hex (and .eep if target arch is avr) file.
 152
 153 UploadHelp(): For different board, the upload command line is different, this
 154 function print the recommended upload command line. You can see the recommended
 155 upload command line in the help information(the output of command "scons
 156 [options] -h")
 157
 158 ==== Scripts Hierarchy ====
 159
 160 Scons provides a function 'SConscript(scripts, [exports, variant_dir, duplicate])'
 161 It tells scons to execute one or more subsidiary configuration files(A script,
 162 usually named SConscript). Take below project hierarchy as example to show how
 163 to organize the scripts.
 164
 165                 prj
 166                 |-------prj_1
 167                 |               |--------sub_prj_11
 168                 |               |--------sub_prj_..
 169                 |               |--------sub_prj_1n
 170                 |-------prj_2
 171                 |
 172                 | ... ...
 173                 |
 174                 |-------prj_n
 175
 176 As above project hierarchy, in 'SConstruct' file in the 'prj' directory, there
 177 should include some lines like these:
 178
 179 #Please change this part according to the organization of your projects.
 180 #Note: To make the output is in build_dir, the path of the scripts should
 181 #be relevant to build_dir
 182 SConscript(build_dir + 'prj_1/SConscript')
 183 SConscript(build_dir + 'prj_2/SConscript')
 184 ... ...
 185 SConscript(build_dir + 'prj_n/SConscript')
 186
 187
 188 It's the same, in the 'prj_1/SConscript', there should include lines like
 189 these:
 190 SConscript('sub_prj_11/SConscript')
 191 ... ...
 192 SConscript('sub_prj_1n/SConscript')
 193
 194 The path is relevant to 'prj_1/SConscript'. You can also use the full path
 195 build_dir + 'prj_1/sub_prj_1x/SConscript', but it's not recommended.
 196
 197 Above just to show a recommended way to manage subsidiary scripts. You don't
 198 need restrictly follow it.
 199
 200 ==== The content of a typical script ====
 201
 202 After run the scripts in build_common (usally it's done at the beginning of
 203 SConstruct), an global environment 'env' is exported, 'env' has include the
 204 default configuration of the target OS and arch. 'env' is used in all projects,
 205 should avoid to change its keys. To avoid change 'env', usually clone 'env' and
 206 update it accroding to the requirement of cuurent sub project. Then specify the
 207 target(usually binary) to build.
 208
 209 Below is an example:
 210         # import the global enviroment 'env'
 211         Import('env')
 212
 213         # Clone a new enviroment from 'env'
 214         new_env = env.Clone()
 215
 216         # Update the new enviroment, usally include add header file paths,
 217         # library path, libs to link and other compiler flags. This part is
 218         # optional. If not present, the default configuration will be used
 219         new_env.AppeneUnique(xxx = [ .... ])
 220
 221         # Specify the target(application, library, object or others) to build
 222         ts = new_env.Program('progam_name', [source_list])
 223
 224         # Install the target (optional)
 225         # If it's an important library or daemon to be published
 226         new_env.InstallTarget(ts, 'target_name')
 227 or
 228         # If is't examples or test program or others will not be published
 229         new_env.Alias('target_name', ts)
 230         new_env.AppendTarget('target_name')
 231
 232 ==== Tips ====
 233 1. library order: if A lib use B lib, both A and B are linked to target T, the
 234         when specify libraries, A should in front of B, otherwise there may be link
 235         error.
 236 2. On android:
 237         (1)'pthread' is in libc. So don't use '-lpthread' for android
 238         (2)By default 'rtti' and 'exception' is disabled, to enable it, you need
 239         add flags '-frtti' and '-fexceptions'
 240         (3)If STL is used, need link 'gnustl_static' library