Fix null pointer dereference
[iotivity.git] / Readme.scons.txt
1 == Quick guide: build and run IoTivity projects on Ubuntu ==
2
3 1. Build
4     Go to the top directory of 'iotivity' project(Note: should always run 'scons'
5     command in this directory)
6
7     Install build tools:
8       $ sudo apt-get install git-core scons ssh build-essential g++ doxygen valgrind
9
10     Install external libraries:
11       $ sudo apt-get install libboost-dev libboost-program-options-dev libboost-thread-dev uuid-dev libssl-dev libtool libglib2.0-dev libcap-dev libcurl4-openssl-dev autotools-dev autoconf
12
13     Build release binaries:
14       $ scons
15 (Note: C sdk requires tinycbor. Please follow the instruction in the build
16 message to install tinycbor)
17
18     Build debug binaries:
19       $scons RELEASE=false
20
21     Help:
22       $ scons -h
23
24     Clear:
25       $ scons -c
26
27 2. Run the samples
28       $ export LD_LIBRARY_PATH=<iotivity>/out/linux/x86_64/release
29       Run the c++ samples in <iotivity>/out/linux/x86_64/release/resource/examples
30       Run the c samples in <iotivity>/out/linux/x86_64/release/resource/csdk/stack/samples/linux/SimpleClientServer
31 ('<iotivity>' is the path to 'iotivity' project. If your device is x86, arm,
32 or arm64, please change 'x86_64' to the proper arch)
33
34 3. To build and test IoTivity with Security enabled (required for certification)
35 follow the instructions found in:
36   <iotivity>/resource/csdk/security/README-building-and-running-secure-IoTivity-stack.txt
37
38 == How to build IoTivity projects ==
39
40 IoTivity includes a series of projects. You can find all these projects here:
41     https://gerrit.iotivity.org/gerrit/#/admin/projects/
42
43 You can build IoTivity project on Linux / Windows / MAC OSX for various targets
44 (Linux, Tizen, Android, Windows, MAC OSX, iOS ...).
45 The output of the build is in:
46   <top directory of the project>/out/<target_os>/<target_arch>/<build_type>/
47 e.g.
48         iotivity/out/android/armeabi-v7a/release/.
49
50 This document takes 'iotivity' project as example, the way to build other
51 projects is almost the same.
52
53 === IoTivity project build tool scons ===
54
55 Scons is a cross-platform build tool, its usage is quite similar to GNU make.
56 To build a project, you just require to run following command at the directory
57 where a SConstruct file exists(SConstruct is the entrance of scons build, it's
58 equivalent to Makefile of 'make') :
59       $ scons [options] [target]
60
61 In additional, usually the scons build script of a project provides useful help
62 information(include build options). To see the help information:
63       $ scons [options] -h
64
65 Note: If no value is specified for an option, the default value will be used.
66 The change of options value may impact the help information and the behavior
67 of the building.
68
69 Generally, it's required to specify the target OS and target ARCH, that's to say
70 tell Scons which OS and which ARCH you'd like build this project for. By default,
71 the target OS and ARCH is the same as the host.
72
73 Some more options may be required, please care the 'error' notification when build.
74 For help about how to set an option, please run:
75      $ scons TARGET_OS=xxx TARGET_ARCH=yyy [XXX=zzz ...] -h
76
77
78 === Prerequites ===
79
80 * 1. Scons
81
82 Please refer to the following page to install scons:
83    http://www.scons.org/doc/production/HTML/scons-user.html#chap-build-install
84 (Note: on Windows, install Python 2.x before installing scons)
85
86 * 2. IDE/SDK Prerequites
87 To build for some OS (Android / iOS ...), an IDE/SDK may be required,
88 please go to the relative page to download and install the required IDE/SDK.
89
90 Android:
91 To build for Android, Andorid NDK and SDK are required.
92   Android NDK: http://developer.android.com/tools/sdk/ndk/index.html
93   Android SDK: http://developer.android.com/sdk/index.html
94 (Note: as in some IoTivity projects, C++11 features are used, recommend Android
95  NDK >= r10)
96
97 Apple:
98 To build for Mac OSX or IOS, Xcode is required.
99   Xcode: https://developer.apple.com/xcode/downloads/
100
101 Java:
102 To build the Java code, JDK is required.
103   JDK: http://www.oracle.com/technetwork/java/javase/downloads/index.html
104 (If the project doesn't include Java code or you wouldn't like build the
105 Java codes, this isn't required)
106
107 (Note: for convenience, suggest add the IDE/SDK path in environment variable,
108 so you don't need to add it in command line each time. The build script will
109 guide you to do that.)
110
111 Tizen:
112 To build for tizen platform tinycbor library is needed.
113 Please download tinycbor if it is not present in extlibs/tinycbor folder
114 by doing the following:
115         $ git clone https://github.com/01org/tinycbor.git extlibs/tinycbor/tinycbor
116
117
118 * 3. External libraries
119 IoTivity project depends on some external libraries, such as boost ...
120 During building, the existence of external library will be checked, if it doesn't
121 exist, the build script will try to download, unpack and build the library or
122 notify user to install it.
123
124 Downloading and unpacking may fail due to network problem or required unpacking
125 tool isn't installed. An message will be displayed, please follow the message
126 to skip it.
127
128
129 === Build IoTivity project ===
130
131 Linux:
132  * Possible values for <TARGET_TRANSPORT> are: ALL, IP, BLE
133
134 1. Go to root directory
135     $ cd <top directory of the project>
136     $ sudo apt-get install libboost-dev libboost-thread-dev libssl-dev libtool
137
138 2. Execute following command(s) to start build based on transport selection required
139
140     -> Building for all transports :
141     $ scons TARGET_OS=linux TARGET_TRANSPORT=ALL
142
143     -> Building for a specific transport :
144     $ scons TARGET_OS=linux TARGET_TRANSPORT=IP
145
146     -> Building for multiple transports :
147     $ scons TARGET_OS=linux TARGET_TRANSPORT=IP,BLE TARGET_ARCH=xxx
148
149     -> Clean Build (all transports) :
150     $ scons TARGET_OS=linux TARGET_TRANSPORT=ALL -c (for clean)
151
152 Android:
153  * Possible values for <TARGET_TRANSPORT> are: ALL, IP, BT, BLE
154  * Possible values for <TARGET_ARCH> are: x86, armeabi, armeabi-v7a, armeabi-v7a-hard
155    (To see all of its allowed value, please execute command 'scons TARGET_OS=android -Q -h')
156
157 1. Go to root directory
158     $ cd <top directory of the project>
159
160 2. Execute following command(s) to start build based on transport selection required
161
162     -> Building for all transports :
163     $ scons TARGET_OS=android TARGET_TRANSPORT=ALL TARGET_ARCH=xxx
164
165     -> Building for a specific transport :
166     $ scons TARGET_OS=android TARGET_TRANSPORT=IP TARGET_ARCH=xxx
167
168     -> Building for multiple transports :
169     $ scons TARGET_OS=android TARGET_TRANSPORT=IP,BT,BLE TARGET_ARCH=xxx
170
171     -> Clean Build (all transports) :
172     $ scons TARGET_OS=android TARGET_TRANSPORT=ALL -c (for clean)
173
174 Tizen:
175  * Possible values for <TARGET_TRANSPORT> are: ALL, IP, BT, BLE
176
177  1. Go to root directory
178     $ cd <top directory of the project>
179
180  2. Execute following command(s) to start build based on transport selection required
181
182     -> Building for all transports :
183     $ scons TARGET_OS=tizen TARGET_TRANSPORT=ALL
184
185     -> Building for a specific transport :
186     $ scons TARGET_OS=tizen TARGET_TRANSPORT=IP
187
188     -> Building for multiple transports :
189     $ scons TARGET_OS=tizen TARGET_TRANSPORT=IP,BT,BLE TARGET_ARCH=xxx
190
191     -> Clean Build (all transports) :
192     $ scons TARGET_OS=tizen TARGET_TRANSPORT=ALL -c (for clean)
193
194 (we provide the spec file required by gbs tool at toools/tizen directory.
195 gbs is default build tool for Tizen platform, we can refer the following
196 wiki to setup Tizen development environment:
197 https://source.tizen.org/documentation/developer-guide/getting-started-guide)
198
199 Mac OSX:
200  * Possible values for <SYS_VERSION> are: OSX version, e.g. 10.9
201
202  1. Go to root directory
203     $ cd <top directory of the project>
204
205  2. Execute following command(s) to start build based on transport selection required
206
207     -> Building for a specific transport :
208     $ scons SYS_VERSION=yyy
209
210 IOS:
211  * Possible values for <TARGET_ARCH> are: i386, x86_64, armv7, armv7s, arm64
212  * Possible values for <SYS_VERSION> are: IOS version, e.g. 7.0
213
214  1. Go to root directory
215     $ cd <top directory of the project>
216
217  2. Execute following command(s) to start build based on transport selection required
218
219     -> Building for a specific transport :
220     $ scons TARGET_OS=ios TARGET_ARCH=xxx SYS_VERSION=yyy
221
222 Windows:
223  * Possible values for <TARGET_ARCH> are: x86, amd64
224
225 For convenience to build projects supported on Windows a batch file (run.bat) is provided
226 to run many build combinations with TARGET_OS to 'windows'.
227
228 1. Go to root directory
229     $ cd <top directory of the project>
230 2. To clean before building:
231       $ run clean
232 3. To build debug amd64 binaries:
233       $ run build
234 4. To build x86 release/retail binaries and run unit tests:
235       $ run build -arch x86 -release
236 See run.bat for more example usage parameters
237
238 webOS:
239  * Possible values for <TARGET_TRANSPORT> are: ALL, IP
240
241 IoTivity build for webOS requires webOS build based on the open-embedded build
242 framework. So to speak, scons build is not directly triggered by user but by
243 the build recipe combinated with build environment. You can check the whole
244 procedure for building IoTivity over webOS at https://wiki.iotivity.org/webos.
245
246 * Additional options
247  * VERBOSE=true or false (Show compilation)
248  * RELEASE=true or false (Build for release?)
249  * LOGGING=true or false (Enable stack logging)
250  * SECURED=1 or 0 (Build with DTLS)
251  * TEST=1 or 0 (Run unit tests)
252  * BUILD_SAMPLE=ON or OFF (Build with sample)
253  * ROUTING=GW or EP (Enable routing)
254  * WITH_TCP=true or false (Enable CoAP over TCP Transport)
255  * RD_MODE=CLIENT or SERVER (Build including Resource Directory)
256  * SIMULATOR=true or false (Build with simulator module)
257  * Possible values for <WITH_MQ> are: PUB,SUB,BROKER (Build including Message Queue)
258    -> PUB : publisher, SUB : subscriber, BROKER : MQ broker(not supported yet)
259  * LOG_LEVEL=DEBUG or INFO or WARNING or ERROR or FATAL
260    (select log level to print, LOGGING option should be true)
261     ex) LOG_LEVEL=DEBUG : All logs including DEBUG, INFO, WARNING, ERROR, FATAL level is printed.
262         LOG_LEVEL=INFO : The logs including INFO, WARNING, ERROR, FATAL level is printed.
263         LOG_LEVEL=WARNING : The logs including WARNING, ERROR, FATAL level is printed.
264         LOG_LEVEL=ERROR : The logs including ERROR, FATAL level is printed.
265         LOG_LEVEL=FATAL : FATAL level is printed.
266    Log entries that have the OC_LOG_PRIVATE_DATA bit set, in addition to DEBUG, INFO, WARNING,
267    ERROR, or FATAL, contain confidential information and therefore are not printed by default.
268    The application has to call OCSetLogLevel() to enable printing of private information in the
269    log.
270
271 Note:
272 1) for convenience, a script (auto_build.sh) is provided to run possible build
273 at once. Following is the usage:
274
275 To build:
276      $ auto_build.sh <path-to-android-ndk>
277 To clean:
278      $ auto_build.sh -c