Fix for tizen build failure issue.
[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 external libraries:
8       $ sudo apt-get install libboost-dev libboost-program-options-dev libexpat1-dev libboost-thread-dev uuid-dev
9
10     Build release binaries:
11       $ scons
12 (Note: C++ sdk requires cereal. Please follow the instruction in the build
13 message to install cereal)
14
15     Build debug binaries:
16       $scons RELEASE=false
17
18     Help:
19       $ scons -h
20
21     Clear:
22       $ scons -c
23
24 2. Run the samples
25       $ export LD_LIBRARY_PATH=<iotivity>/out/linux/x86_64/release
26       Run the c++ samples in <iotivity>/out/linux/x86_64/release/resource/examples
27       Run the c samples in <iotivity>/out/linux/x86_64/release/resource/csdk/stack/samples/linux/SimpleClientServer
28 ('<iotivity>' is the path to 'iotivity' project. If your device is x86, arm,
29 or arm64, please change 'x86_64' to the proper arch)
30
31 == How to build IoTivity projects ==
32
33 IoTivity includes a series of projects. You can find all these projects here:
34     https://gerrit.iotivity.org/gerrit/#/admin/projects/
35
36 You can build IoTivity project on Linux / Windows / MAC OSX for various OS(
37 Linux, Tizen, Android, Arduino, Windows, MAC OSX, IOS ...).
38 The output of the build is in:
39   <top directory of the project>/out/<target_os>/<target_arch>/<build_type>/
40 e.g.
41         iotivity/out/android/armeabi-v7a/release/.
42
43 This document takes 'iotivity' project as example, the way to build other
44 projects is almost the same.
45
46 === IoTivity project build tool scons ===
47
48 Scons is a cross-platform build tool, its usage is quite similar to GNU make.
49 To build a project, you just require to run following command at the directory
50 where a SConstruct file exists(SConstruct is the entrance of scons build, it's
51 equivalent to Makefile of 'make') :
52       $ scons [options] [target]
53
54 In additional, usually the scons build script of a project provides useful help
55 information(include build options). To see the help information:
56       $ scons [options] -h
57
58 Note: If no value is specified for an option, the default value will be used.
59 The change of options value may impact the help information and the behavior
60 of the building.
61
62 Generally, it's required to specify the target OS and target ARCH, that's to say
63 tell Scons which OS and which ARCH you'd like build this project for. By default,
64 the target OS and ARCH is the same as the host.
65
66 Some more options may be required, please care the 'error' notification when build.
67 For help about how to set an option, please run:
68      $ scons TARGET_OS=xxx TARGET_ARCH=yyy [XXX=zzz ...] -h
69
70
71 === Prerequites ===
72
73 * 1. Scons
74
75 Please refer to the following page to install scons:
76    http://www.scons.org/doc/production/HTML/scons-user.html#chap-build-install
77 (Note: on Windows, install Python 2.x before installing scons)
78
79 * 2. IDE/SDK Prerequites
80 To build for some OS (Android / Arduino / IOS ...), an IDE/SDK may be required,
81 please go to the relative page to download and install the required IDE/SDK.
82
83 Android:
84 To build for Android, Andorid NDK and SDK are required.
85   Android NDK: http://developer.android.com/tools/sdk/ndk/index.html
86   Android SDK: http://developer.android.com/sdk/index.html
87 (Note: as in some IoTivity projects, C++11 features are used, recommend Android
88  NDK >= r10)
89
90 Arduino:
91 To build for Arduino, Arduino IDE is required.
92   Arduino IDE: http://arduino.cc/en/Main/Software
93   (Note: recommend install Arduino IDE >=1.5.7)
94
95 Arduino builds are dependent on latest Time library. Download it from here:
96     http://www.pjrc.com/teensy/td_libs_Time.html
97 and extract to <arduino_ide_root>/libraries/
98
99 (Note: If you are using Arduino IDE 1.5.8 BETA on Windows, it may pop up some
100 dll isn't found. please copy relative dll from the IDE directory to
101 C:\Windows\SysWOW64. IDE 1.5.7 doesn't have this issue. Other version IDE isn't
102 tested.)
103
104 Apple:
105 To build for Mac OSX or IOS, Xcode is required.
106   Xcode: https://developer.apple.com/xcode/downloads/
107
108 Java:
109 To build the Java code, JDK is required.
110   JDK: http://www.oracle.com/technetwork/java/javase/downloads/index.html
111 (If the project doesn't include Java code or you wouldn't like build the
112 Java codes, this isn't required)
113
114 (Note: for convenience, suggest add the IDE/SDK path in environment variable,
115 so you don't need to add it in command line each time. The build script will
116 guide you to do that.)
117
118 Tizen:
119 To build for tizen platform cereal library is needed.
120 Please download cereal if it is not present in extlibs/cereal folder
121 and apply the patch as following:
122         $ git clone https://github.com/USCiLab/cereal.git extlibs/cereal/cereal
123         $ cd  extlibs/cereal/cereal
124         $ git reset --hard 7121e91e6ab8c3e6a6516d9d9c3e6804e6f65245
125         $ git apply ../../../resource/patches/cereal_gcc46.patch
126
127
128 * 3. External libraries
129 IoTivity project depends on some external libraries, such as boost, expat ...
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 on Linux(Ubuntu) ===
140
141 1. Build IoTivity project for Linux
142       $ cd <top directory of the project>
143       $ sudo apt-get install libboost-dev libexpat1-dev libboost-thread-dev
144       $ scons
145
146 2. Build IoTivity project for Android
147       $ cd <top directory of the project>
148       $ scons TARGET_OS=android TARGET_ARCH=xxx
149 (xxx can be x86, armeabi, armeabi-v7a, armeabi-v7a-hard. To see all of its
150 allowed value, please execute command 'scons TARGET_OS=android -Q -h')
151
152 3. Build IoTivity project for Arduino
153       $ cd <top directory of the project>
154       $ scons TARGET_OS=arduino TARGET_ARCH=xxx BOARD=yyy
155 (xxx can be avr, arm; yyy is the name of the board, to get its allowed value
156 run: scons TARGET_OS=arduino TARGET_ARCH=xxx -h. You may see a option 'CPU' in
157 the output of above command line, that's due to some boards have different
158 processors, to specify the processor, add 'CPU=zzz' in the command line. If no
159 'CPU' option exists, that means the board only support one kind of processor,
160 it's unnecessary to specify it)
161
162 4. Build Iotivity project for Tizen
163       $ cd <top directory of the project>
164       $ sh gbsbuild.sh
165 (we provide the spec file required by gbs tool at toools/tizen directory.
166 gbs is default build tool for Tizen platfrom, we can refer the following
167 wiki to setup Tizen development environment:
168 https://source.tizen.org/documentation/developer-guide/getting-started-guide)
169
170 === Build IoTivity project on Android ===
171
172 1. Build IoTivity project for Android(It's the same as on Ubuntu)
173       $ cd <top directory of the project>
174       $ scons TARGET_OS=android TARGET_ARCH=xxx
175 (xxx can be x86, armeabi, armeabi-v7a, armeabi-v7a-hard ...)
176
177 2. Build IoTivity project for Arduino(It's the same as on Ubuntu)
178       $ cd <top directory of the project>
179       $ scons TARGET_OS=arduino TARGET_ARCH=xxx BOARD=yyy
180 (xxx can be avr, arm; yyy is the name of the board, to get its allowed value
181 run: scons TARGET_OS=arduino TARGET_ARCH=xxx -h. You may see a option 'CPU' in
182 the output of above command line, that's due to some boards have different
183 processor, to specify the processor, add 'CPU=zzz' in the command line. If no
184 'CPU' option exists, that means the board only support one kind of processor,
185 it's unnecessary to specify it)
186
187
188 Note: Currently most IoTivity project doesn't support Windows, so you can't set
189 TARGET_OS to 'windows' except the project support Windows.
190
191 That's to say if the project doesn't support Windows, run:
192       $ scons TARGET_OS=windows ....
193 or run on Windows
194       $ scons
195 may always fail.
196
197
198 === Build IoTivity project on Mac OSX ===
199
200 1. Build IoTivity project for Mac OSX
201       $ cd <top directory of the project>
202       $ scons SYS_VERSION=yyy
203 (yyy is the OSX version, e.g. 10.9)
204
205 2. Build IoTivity project for Android(It's the same as on Ubuntu)
206       $ cd <top directory of the project>
207       $ scons TARGET_OS=android TARGET_ARCH=xxx
208 (xxx can be x86, armeabi, armeabi-v7a, armeabi-v7a-hard)
209
210 3. Build IoTivity project for IOS
211       $ cd <top directory of the project>
212       $ scons TARGET_OS=ios TARGET_ARCH=xxx SYS_VERSION=yyy
213 (xxx can be i386, x86_64, armv7, armv7s, arm64, yyy is IOS version, e.g. 7.0)
214
215 Note:
216 1) for convenience, a script (auto_build.sh) is provided to run possible build
217 at once. Following is the usage:
218
219 To build:
220      $ auto_build.sh <path-to-android-ndk>
221 To clean:
222      $ auto_build.sh -c
223
224 2) For Arduino build, the Time library should >=1.3. The old can only be built
225 with Arduino IDE 1.0.x