Update from latest iotivity-node.
[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
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 == How to build IoTivity projects ==
35
36 IoTivity includes a series of projects. You can find all these projects here:
37     https://gerrit.iotivity.org/gerrit/#/admin/projects/
38
39 You can build IoTivity project on Linux / Windows / MAC OSX for various OS(
40 Linux, Tizen, Android, Arduino, Windows, MAC OSX, IOS ...).
41 The output of the build is in:
42   <top directory of the project>/out/<target_os>/<target_arch>/<build_type>/
43 e.g.
44         iotivity/out/android/armeabi-v7a/release/.
45
46 This document takes 'iotivity' project as example, the way to build other
47 projects is almost the same.
48
49 === IoTivity project build tool scons ===
50
51 Scons is a cross-platform build tool, its usage is quite similar to GNU make.
52 To build a project, you just require to run following command at the directory
53 where a SConstruct file exists(SConstruct is the entrance of scons build, it's
54 equivalent to Makefile of 'make') :
55       $ scons [options] [target]
56
57 In additional, usually the scons build script of a project provides useful help
58 information(include build options). To see the help information:
59       $ scons [options] -h
60
61 Note: If no value is specified for an option, the default value will be used.
62 The change of options value may impact the help information and the behavior
63 of the building.
64
65 Generally, it's required to specify the target OS and target ARCH, that's to say
66 tell Scons which OS and which ARCH you'd like build this project for. By default,
67 the target OS and ARCH is the same as the host.
68
69 Some more options may be required, please care the 'error' notification when build.
70 For help about how to set an option, please run:
71      $ scons TARGET_OS=xxx TARGET_ARCH=yyy [XXX=zzz ...] -h
72
73
74 === Prerequites ===
75
76 * 1. Scons
77
78 Please refer to the following page to install scons:
79    http://www.scons.org/doc/production/HTML/scons-user.html#chap-build-install
80 (Note: on Windows, install Python 2.x before installing scons)
81
82 * 2. IDE/SDK Prerequites
83 To build for some OS (Android / Arduino / IOS ...), an IDE/SDK may be required,
84 please go to the relative page to download and install the required IDE/SDK.
85
86 Android:
87 To build for Android, Andorid NDK and SDK are required.
88   Android NDK: http://developer.android.com/tools/sdk/ndk/index.html
89   Android SDK: http://developer.android.com/sdk/index.html
90 (Note: as in some IoTivity projects, C++11 features are used, recommend Android
91  NDK >= r10)
92
93 Arduino:
94 To build for Arduino, Arduino IDE is required.
95   Arduino IDE: http://arduino.cc/en/Main/Software
96   (Note: recommend install Arduino IDE >=1.5.8)
97
98 Arduino builds are dependent on latest Time library. Download it from here:
99     http://www.pjrc.com/teensy/td_libs_Time.html
100 and extract to <arduino_ide_root>/libraries/
101
102 (Note: If you are using Arduino IDE 1.5.8 BETA on Windows, it may pop up some
103 dll isn't found. please copy relative dll from the IDE directory to
104 C:\Windows\SysWOW64. IDE 1.5.7 doesn't have this issue. Other version IDE isn't
105 tested.)
106
107 Apple:
108 To build for Mac OSX or IOS, Xcode is required.
109   Xcode: https://developer.apple.com/xcode/downloads/
110
111 Java:
112 To build the Java code, JDK is required.
113   JDK: http://www.oracle.com/technetwork/java/javase/downloads/index.html
114 (If the project doesn't include Java code or you wouldn't like build the
115 Java codes, this isn't required)
116
117 (Note: for convenience, suggest add the IDE/SDK path in environment variable,
118 so you don't need to add it in command line each time. The build script will
119 guide you to do that.)
120
121 Tizen:
122 To build for tizen platform tinycbor library is needed.
123 Please download tinycbor if it is not present in extlibs/tinycbor folder
124 by doing the following:
125         $ git clone https://github.com/01org/tinycbor.git extlibs/tinycbor/tinycbor
126
127
128 * 3. External libraries
129 IoTivity project depends on some external libraries, such as boost ...
130 During building, the existence of external library will be checked, if it doesn't
131 exist, the build script will try to download, unpack and build the library or
132 notify user to install it.
133
134 Downloading and unpacking may fail due to network problem or required unpacking
135 tool isn't installed. An message will be displayed, please follow the message
136 to skip it.
137
138
139 === Build IoTivity project ===
140
141 Linux:
142  * Possible values for <TARGET_TRANSPORT> are: ALL, IP, BLE
143
144 1. Go to root directory
145     $ cd <top directory of the project>
146     $ sudo apt-get install libboost-dev libboost-thread-dev libssl-dev libtool
147
148 2. Execute following command(s) to start build based on transport selection required
149
150     -> Building for all transports :
151     $ scons TARGET_OS=linux TARGET_TRANSPORT=ALL
152
153     -> Building for a specific transport :
154     $ scons TARGET_OS=linux TARGET_TRANSPORT=IP
155
156     -> Building for multiple transports :
157     $ scons TARGET_OS=linux TARGET_TRANSPORT=IP,BLE TARGET_ARCH=xxx
158
159     -> Clean Build (all transports) :
160     $ scons TARGET_OS=linux TARGET_TRANSPORT=ALL -c (for clean)
161
162 Android:
163  * Possible values for <TARGET_TRANSPORT> are: ALL, IP, BT, BLE
164  * Possible values for <TARGET_ARCH> are: x86, armeabi, armeabi-v7a, armeabi-v7a-hard
165    (To see all of its allowed value, please execute command 'scons TARGET_OS=android -Q -h')
166
167 1. Go to root directory
168     $ cd <top directory of the project>
169
170 2. Execute following command(s) to start build based on transport selection required
171
172     -> Building for all transports :
173     $ scons TARGET_OS=android TARGET_TRANSPORT=ALL TARGET_ARCH=xxx
174
175     -> Building for a specific transport :
176     $ scons TARGET_OS=android TARGET_TRANSPORT=IP TARGET_ARCH=xxx
177
178     -> Building for multiple transports :
179     $ scons TARGET_OS=android TARGET_TRANSPORT=IP,BT,BLE TARGET_ARCH=xxx
180
181     -> Clean Build (all transports) :
182     $ scons TARGET_OS=android TARGET_TRANSPORT=ALL -c (for clean)
183
184 Tizen:
185  * Possible values for <TARGET_TRANSPORT> are: ALL, IP, BT, BLE
186
187  1. Go to root directory
188     $ cd <top directory of the project>
189
190  2. Execute following command(s) to start build based on transport selection required
191
192     -> Building for all transports :
193     $ scons TARGET_OS=tizen TARGET_TRANSPORT=ALL
194
195     -> Building for a specific transport :
196     $ scons TARGET_OS=tizen TARGET_TRANSPORT=IP
197
198     -> Building for multiple transports :
199     $ scons TARGET_OS=tizen TARGET_TRANSPORT=IP,BT,BLE TARGET_ARCH=xxx
200
201     -> Clean Build (all transports) :
202     $ scons TARGET_OS=tizen TARGET_TRANSPORT=ALL -c (for clean)
203
204 (we provide the spec file required by gbs tool at toools/tizen directory.
205 gbs is default build tool for Tizen platform, we can refer the following
206 wiki to setup Tizen development environment:
207 https://source.tizen.org/documentation/developer-guide/getting-started-guide)
208
209 Arduino:
210  * Possible values for <TARGET_TRANSPORT> are: IP, BLE
211  * Possible values for <TARGET_ARCH> are: arv, arm
212     (arv: arduino due, arm: arduino mega)
213  * Possible values for <BOARD> are: arduino_due_x_dbg, arduino_due_x, mega
214  * Possible values for <SHIELD> are: ETH, WIFI
215     (It is required in the case of the arduino due.)
216
217  1. Go to root directory
218     $ cd <top directory of the project>
219     $ sudo apt-get install dos2unix
220
221  2. Execute following command(s) to start build based on transport selection required
222
223     -> Building for a specific transport :
224     $ scons TARGET_OS=arduino TARGET_ARCH=xxx BOARD=yyy SHIELD=zzz
225
226 (To get allowed values run: scons TARGET_OS=arduino TARGET_ARCH=xxx SHIELD=zzz -h.
227 You may see a option 'CPU' in the output of above command line, that's due to
228 some boards have different processors, to specify the processor, add 'CPU=zzz'
229 in the command line. If no 'CPU' option exists, that means the board only
230 support one kind of processor, it's unnecessary to specify it)
231
232 Mac OSX:
233  * Possible values for <SYS_VERSION> are: OSX version, e.g. 10.9
234
235  1. Go to root directory
236     $ cd <top directory of the project>
237
238  2. Execute following command(s) to start build based on transport selection required
239
240     -> Building for a specific transport :
241     $ scons SYS_VERSION=yyy
242
243 IOS:
244  * Possible values for <TARGET_ARCH> are: i386, x86_64, armv7, armv7s, arm64
245  * Possible values for <SYS_VERSION> are: IOS version, e.g. 7.0
246
247  1. Go to root directory
248     $ cd <top directory of the project>
249
250  2. Execute following command(s) to start build based on transport selection required
251
252     -> Building for a specific transport :
253     $ scons TARGET_OS=ios TARGET_ARCH=xxx SYS_VERSION=yyy
254
255 * Additional options
256  * VERBOSE=true or false (Show compilation)
257  * RELEASE=true or false (Build for release?)
258  * LOGGING=true or false (Enable stack logging)
259  * SECURED=1 or 0 (Build with DTLS)
260  * TEST=1 or 0 (Run unit tests)
261  * SECURED=1 or 0 (Build with DTLS)
262  * BUILD_SAMPLE=ON or OFF (Build with sample)
263  * ROUTING=GW or EP (Enable routing)
264  * WITH_TCP=true or false (Enable CoAP over TCP Transport, arduino is not supported)
265  * WITH_RA=true or false (Build with Remote Access module)
266  * WITH_RD=1 or 0 (Build including Resource Directory)
267  * SIMULATOR=true or false (Build with simulator module)
268  * Possible values for <WITH_MQ> are: PUB,SUB,BROKER (Build including Message Queue)
269    -> PUB : publisher, SUB : subscriber, BROKER : MQ broker(not supported yet)
270
271 Note1: Currently most IoTivity project doesn't support Windows, so you can't set
272 TARGET_OS to 'windows' except the project support Windows.
273
274 That's to say if the project doesn't support Windows, run:
275       $ scons TARGET_OS=windows ....
276 or run on Windows
277       $ scons
278 may always fail.
279
280 Note2:
281 1) for convenience, a script (auto_build.sh) is provided to run possible build
282 at once. Following is the usage:
283
284 To build:
285      $ auto_build.sh <path-to-android-ndk>
286 To clean:
287      $ auto_build.sh -c