1 == How to write IoTivity build script ==
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'.
7 This document only a brief reference. Detail about how to write scons script,
9 http://www.scons.org/doc/production/HTML/scons-user.html#
11 == Background: How to control source code compiling ==
13 Environment is a base conception of Scons. An environment is a collection of
14 values that can affect how a program is built.
16 e.g. There is a C file named hello.c, enter the following into a file named
19 env.Program('H', 'hello.c')
21 When run Scons in console, following will be executed:
22 cc -o hello.o -c hello.c
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:
28 env.AppendUnique(CFLAGS = ['-g'])
29 env.Program('H', 'hello.c')
31 When run Scons, following will be executed:
32 cc -o hello.o -c -g hello.c
35 In above example, 'CFLAGS' is changed. Following list the frequently used keys:
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.
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).
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'])
57 Still take the hello.c as example. Assume hello.h is in ./include/ directory,
59 int main(int argc, char** argv)
68 The Scons configure file should as following:
70 env.AppendUnique(CFLAGS = ['-g'])
71 env.AppendUnique(CPPPATH = ['include'])
72 env.AppendUnique(CPPDEFINES = ['LANG_FR'])
73 env.Program('H', 'hello.c')
75 When run Scons, following will be executed:
76 cc -o hello.o -c -g -Iinclude -DLANG_FR hello.c
79 === Get extra information ===
81 In above example, 'target_os' is used. How to get it?
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.
89 When write IoTivity project build script, you can get this environment as
93 You can use 'env' directly after import it. You can also clone a new environment
96 new_env1 = Clone('env')
97 new_env2 = Clone('env')
98 new_env1.AppendUnqiue(xxx = [...])
99 new_env2.AppendUnqiue(xxx = [...])
101 The 'env' environment contains platform specific configuration, besides, there is
102 some common information. You can get the information with following line:
107 XXX is the information name, below are the extra information added by IoTivity
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 RELEASE: build type, boolean. True - release build, False - debug build
112 TARGET_OS: the name of the target OS. The possible value depends on the host
113 platform. Bellow is the list of host and possible target OS. (darwin means
115 linux: linux / android / arduino / tizen
116 (the line means on Linux, you can build the project for Linux/Android/Arduino/Tizen)
117 windows: windows / winrt / android / arduino
118 darwin: darwin / ios / android / arduino
120 TARGET_ARCH: the target CPU arch. Its possible value depend on the target OS.
121 Bellow list the target OS and allowed CPU architecture.
122 linux: x86 / x86_64 / arm / arm64
123 (above line means if the target OS is Linux, the CPU arch can be x86/x86_64/arm/arm64)
124 android: x86 / x86_64 / armeabi / armeabi-v7a / armeabi-v7a-hard / arm64-v8a
125 windows: x86 / amd64 / arm
127 darwin: i386 / x86_64
128 ios: i386 / x86_64 / armv7 / armv7s / arm64,
131 === Extra functions ===
133 For convenience, in the common scripts, some extra functions are added.
135 PrintTargets(): print all targets in the help information.
136 AppendTarget(target): add 'target' into targets list, when use PrintTargets,
137 the 'target' will be print.
138 InstallTarget(files, name): it takes the same action as AppendTarget, besides,
139 it installs the 'files' to BUILD_DIR.
141 Following functions are only for Arduino:
142 ImportLib(lib): Arduino IDE includes many libraries. By default, no library is
143 compiled. If your project use some libraries, you can import the library by
144 this function. 'lib' is the name of the library to import. The 'include' path
145 will be auto added to the environment and the library will be built and linked
146 into the final binary.
148 CreateBin('bin', src): For Arduino, after build the program, it's required to
149 be converted into specific format (e.g .hex). This function will genearate the
150 required .hex (and .eep if target arch is avr) file.
152 UploadHelp(): For different board, the upload command line is different, this
153 function print the recommended upload command line. You can see the recommended
154 upload command line in the help information(the output of command "scons
157 ==== Scripts Hierarchy ====
159 Scons provides a function 'SConscript(scripts, [exports, variant_dir, duplicate])'
160 It tells scons to execute one or more subsidiary configuration files(A script,
161 usually named SConscript). Take below project hierarchy as example to show how
162 to organize the scripts.
166 | |--------sub_prj_11
167 | |--------sub_prj_..
168 | |--------sub_prj_1n
175 As above project hierarchy, in 'SConstruct' file in the 'prj' directory, there
176 should include some lines like these:
178 #Please change this part according to the organization of your projects.
179 #Note: To make the output is in build_dir, the path of the scripts should
180 #be relevant to build_dir
181 SConscript(build_dir + 'prj_1/SConscript')
182 SConscript(build_dir + 'prj_2/SConscript')
184 SConscript(build_dir + 'prj_n/SConscript')
187 It's the same, in the 'prj_1/SConscript', there should include lines like
189 SConscript('sub_prj_11/SConscript')
191 SConscript('sub_prj_1n/SConscript')
193 The path is relevant to 'prj_1/SConscript'. You can also use the full path
194 build_dir + 'prj_1/sub_prj_1x/SConscript', but it's not recommended.
196 Above just to show a recommended way to manage subsidiary scripts. You don't
197 need restrictly follow it.
199 ==== The content of a typical script ====
201 After run the scripts in build_common (usally it's done at the beginning of
202 SConstruct), an global environment 'env' is exported, 'env' has include the
203 default configuration of the target OS and arch. 'env' is used in all projects,
204 should avoid to change its keys. To avoid change 'env', usually clone 'env' and
205 update it accroding to the requirement of cuurent sub project. Then specify the
206 target(usually binary) to build.
209 # import the global enviroment 'env'
212 # Clone a new enviroment from 'env'
213 new_env = env.Clone()
215 # Update the new enviroment, usally include add header file paths,
216 # library path, libs to link and other compiler flags. This part is
217 # optional. If not present, the default configuration will be used
218 new_env.AppeneUnique(xxx = [ .... ])
220 # Specify the target(application, library, object or others) to build
221 ts = new_env.Program('progam_name', [source_list])
223 # Install the target (optional)
224 # If it's an important library or daemon to be published
225 new_env.InstallTarget(ts, 'target_name')
227 # If is't examples or test program or others will not be published
228 new_env.Alias('target_name', ts)
229 new_env.AppendTarget('target_name')
232 1. library order: if A lib use B lib, both A and B are linked to target T, the
233 when specify libraries, A should in front of B, otherwise there may be link
236 (1)'pthread' is in libc. So don't use '-lpthread' for android
237 (2)By default 'rtti' and 'exception' is disabled, to enable it, you need
238 add flags '-frtti' and '-fexceptions'
239 (3)If STL is used, need link 'gnustl_static' library