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