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 whitch 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
 105 XXX is the information name, below are the extra information added by iotivity
 106 common scrirpts:
 107 BUILD_DIR: the path of the build directory
 108 SRC_DIR: the path of the top directory of the source code
 109 OIC_UTILS: the path of oic-utilities project
 110 RELEASE: boolean. True - release build, False - debug build
 111 TARGET_OS: the name of the target OS. The possible value depends on the host
 112         platform. Bellow is the list of host and possible target OS. (darwin means
 113         MAC OSX)
 114                 linux: linux / android / arduino
 115 (the line means on linux, you can build the project for linux/android/arduino)
 116                 windows: windows / winrt / android / arduino
 117                 darwin: darwin / ios / android / arduino
 118
 119 TARGET_ARCH: the target CPU arch. Its possible value depend on the target OS
 120         Bellow list the target OS and allowed CPU architecture.
 121                 linux: x86 / x86_64 / arm / arm64
 122 (above line means if the target OS is linux, the CPU arch can be x86/x86_64/arm/arm64)
 123                 android: x86 / x86_64 / armeabi / armeabi-v7a / armeabi-v7a-hard / arm64-v8a
 124                 windows: x86 / amd64 / arm
 125                 winrt: arm
 126                 darwin: i386 / x86_64
 127                 ios: i386 / x86_64 / armv7 / armv7s / arm64,
 128                 arduino: avr / arm
 129
 130 === Extra functions ===
 131
 132 For convenience, in the common scripts, some extra functions are added.
 133
 134 PrintTargets(): print all targets in the help information.
 135 AppendTarget(target): add 'target' into targets list, when use PrintTargets,
 136         the 'target' will be print.
 137 InstallTarget(files, name): it takes the same action as AppendTarget, besides,
 138         it installs the 'files' to BUILD_DIR.
 139
 140 Following functions are only for Arduino:
 141 ImportLib(lib): Arduino IDE includes many libraries. To control the binary size,
 142 by default, no library is used. If your project use some libraries, you can
 143 import the lib with this function. 'lib' is the name of the lib to import.
 144 The include path will be auto added to the environment and the library will be
 145 built and linked into the final binary.
 146
 147 CreateBin('bin', src): For Arduino, after build the program, it's required to
 148 be converted into specific format (e.g .hex). This function will genearate the
 149 required .hex (and .eep if target arch is avr) file.
 150
 151 UploadHelp(): For different board, the upload command line is different, this
 152 function print the recommended upload command line. You can see the recommended
 153 upload command line in the help information.
 154
 155 ==== Scripts Hierarchy ====
 156
 157 Scons provides a function 'SConscript(scripts, [exports, variant_dir, duplicate])'
 158 It tells scons to execute one or more subsidiary configuration files(A script,
 159 usually named SConscript). Take below project hierarchy as example to show how
 160 to organize the scripts.
 161
 162                 prj
 163                 |-------prj_1
 164                 |               |--------sub_prj_11
 165                 |               |--------sub_prj_..
 166                 |               |--------sub_prj_1n
 167                 |-------prj_2
 168                 |
 169                 | ... ...
 170                 |
 171                 |-------prj_n
 172
 173 As above project hierarchy, in 'SConstruct' file in the 'prj' directory, there
 174 should include some lines like these:
 175
 176 #Please change this part according to the organization of your projects.
 177 #Note: To make the output is in build_dir, the path of the scripts should
 178 #be relevant to build_dir
 179 SConscript(build_dir + 'prj_1/SConscript')
 180 SConscript(build_dir + 'prj_2/SConscript')
 181 ... ...
 182 SConscript(build_dir + 'prj_n/SConscript')
 183
 184
 185 It's the same, in the 'prj_1/SConscript', there should include lines like
 186 these:
 187 SConscript('sub_prj_11/SConscript')
 188 ... ...
 189 SConscript('sub_prj_1n/SConscript')
 190
 191 The path is relevant to 'prj_1/SConscript'. You can also use the full path
 192 build_dir + 'prj_1/sub_prj_1x/SConscript', but it's not recommended.
 193
 194 Above just to show a usual way to manage subsidiary scripts. You don't need
 195 restrictly follow it.
 196
 197 ==== The content of a typical script ====
 198
 199 After run the scripts in build_common (usally it's done at the beginning of
 200 SConstruct), an global environment 'env' is exported, 'env' has include the
 201 default configuration of the target OS and arch. 'env' is used in all projects,
 202 should avoid to change its keys. To avoid change 'env', usually clone 'env' and
 203 update it accroding to the requirement of cuurent sub project. Then specify the
 204 target(usually binary) to build.
 205
 206 Below is an example:
 207         # import the global enviroment 'env'
 208         Import('env')
 209
 210         # Clone a new enviroment from 'env'
 211         new_env = env.Clone()
 212
 213         # Update the new enviroment, usally include add header file paths,
 214         # library path, libs to link and other compiler flags. This part is
 215         # optional. If not present, the default configuration will be used
 216         new_env.AppeneUnique(xxx = [ .... ])
 217
 218         # Specify the target(application, library, object or others) to build
 219         ts = new_env.Program('progam_name', [source_list])
 220
 221         # Install the target (optional)
 222         new_env.InstallTarget(ts, 'target_name')
 223 or
 224         new_env.Alias('target_name', ts)
 225         new_env.AppendTarget('target_name')
 226
 227 ==== Tips ====
 228 1. library order: if A lib use B lib, both A and B are linked to target T, the
 229         when specify libraries, A should in front of B, otherwise there may be link
 230         error.
 231 2. On android:
 232         (1)'pthread' is in libc. So don't use '-lpthread' for android
 233         (2)By default 'rtti' and 'exception' is disabled, to enable it, you need
 234         add flags '-frtti' and '-fexceptions'
 235         (3)If STL is used, need link 'gnustl_static' library