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
   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         oic-resource/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 output.
  60
  61
  62 === Prerequites ===
  63
  64 * 1. Scons
  65
  66 Please refer to the following page to install scons:
  67    http://www.scons.org/doc/production/HTML/scons-user.html#chap-build-install
  68 (Note: on Windows, install Python 2.x before installing scons)
  69
  70 * 2. IDE/SDK Prerequites
  71 To build for some OS (Android / Arduino / IOS ...), an IDE/SDK may be required,
  72 please go to the relative page to download and install the required IDE/SDK.
  73
  74 Android:
  75 To build for Android, Andorid NDK and SDK are required.
  76   Android NDK: http://developer.android.com/tools/sdk/ndk/index.html
  77   Android SDK: http://developer.android.com/sdk/index.html
  78 (Note: as in some IoTivity projects, C++11 features are used, recommend Android
  79  NDK >= r10, according to our test result r10c is the best one currently)
  80
  81 Arduino:
  82 To build for Arduino, Arduino IDE is required.
  83   Arduino IDE: http://arduino.cc/en/Main/Software
  84   (Note: recommend install Arduino IDE >=1.5.7)
  85
  86 Arduino builds are dependent on latest Time library. Download it from here:
  87     http://www.pjrc.com/teensy/td_libs_Time.html
  88 and extract to <arduino_ide_root>/libraries/
  89
  90 (Note: If you are using Arduino IDE 1.5.8 BETA on Windows, it may pop up some
  91 dll isn't found. please copy relative dll from the IDE directory to
  92 C:\Windows\SysWOW64. IDE 1.5.7 doesn't have this issue. Other version IDE isn't
  93 tested.)
  94
  95 Apple:
  96 To build for Mac OSX or IOS, Xcode is required.
  97   Xcode: https://developer.apple.com/xcode/downloads/
  98
  99 Java:
 100 To build the Java code, JDK is required.
 101   JDK: http://www.oracle.com/technetwork/java/javase/downloads/index.html
 102 (If the project doesn't include Java code or you wouldn't like build the
 103 Java codes, this isn't required)
 104
 105 (Note: for convenience, suggest add the IDE/SDK path in environment variable,
 106 so you don't need to add it in command line each time. The build script will
 107 guide you to do that.)
 108
 109 * 3. External libraries
 110 For Android and IOS build, most of the external libraries are provided as
 111 binary in oic-utilities project (https://oic-review.01.org/gerrit/oic-utilities).
 112 Please download it in the same directory as other IoTivity projects. If it's
 113 in different directory, an additional option (OIC_UITLS) will be required. The
 114 build command should be:
 115       $ scons OIC_UITLS=<path to oic-utilities> [other options] [target]
 116
 117 (Note: for convenience, you can also add it in environment variable. So you
 118 don't need to add this option in command line each time.)
 119   e.g.:
 120       $ export OIC_UITLS=<path to oic-utilities project>
 121
 122
 123 === Build IoTivity project on Linux(Ubuntu) ===
 124
 125 Generally, it's required to specify the target OS and target ARCH, that's to say
 126 tell Scons which OS and which ARCH you'd like build this project for. By default,
 127 the target OS and ARCH is the same as the host.
 128
 129 Some more options may be required, please care the 'error' notification when build.
 130 For help about how to set an option, please run:
 131         $ scons TARGET_OS=xxx TARGET_ARCH=yyy [XXX=zzz ...] -h
 132
 133 1. Build IoTivity project for Linux
 134       $ cd <top directory of the project>
 135       $ sudo apt-get install libboost-dev libboost-program-options-dev libexpat1-dev libboost-thread-dev
 136       $ scons
 137
 138 2. Build IoTivity project for Android
 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. To see all of its
 142 allowed value, please execute command 'scons TARGET_OS=android -Q -h')
 143
 144 Note: Currently as x86_64/arm64_v8a external library binaries aren't provided,
 145 you may meet link problem if build executable binary which depends on external
 146 library for x86_64/arm64_v8a.
 147
 148 3. Build IoTivity project for Arduino
 149       $ cd <top directory of the project>
 150       $ scons TARGET_OS=arduino TARGET_ARCH=xxx BOARD=yyy
 151 (xxx can be avr, arm; yyy is the name of the board, to get its allowed value
 152 run: scons TARGET_OS=arduino TARGET_ARCH=xxx -h. You may see a option 'CPU' in
 153 the output of above command line, that's due to some boards have different
 154 processors, to specify the processor, add 'CPU=zzz' in the command line. If no
 155 'CPU' option exists, that means the board only support one kind of processor,
 156 it's unnecessary to specify it)
 157
 158 4. Build Iotivity project for Tizen
 159       $ cd <top directory of the project>
 160       $ gbs build -A xxx --packaging-dir tools/tizen/
 161 (xxx can be i586 or armv7l, we provide the spec file required by gbs tool at
 162 toools/tizen directory. gbs is default build tool for Tizen platfrom, we can
 163 refer the following wiki to setup Tizen development environment:
 164 https://source.tizen.org/documentation/developer-guide/getting-started-guide)
 165
 166 === Build IoTivity project on Windows ===
 167
 168 1. Build IoTivity project for Android(It's the same as on Ubuntu)
 169       $ cd <top directory of the project>
 170       $ scons TARGET_OS=android TARGET_ARCH=xxx
 171 (xxx can be x86, armeabi, armeabi-v7a, armeabi-v7a-hard ...)
 172
 173 2. Build IoTivity project for Arduino(It's the same as on Ubuntu)
 174       $ cd <top directory of the project>
 175       $ scons TARGET_OS=arduino TARGET_ARCH=xxx BOARD=yyy
 176 (xxx can be avr, arm; yyy is the name of the board, to get its allowed value
 177 run: scons TARGET_OS=arduino TARGET_ARCH=xxx -h. You may see a option 'CPU' in
 178 the output of above command line, that's due to some boards have different
 179 processor, to specify the processor, add 'CPU=zzz' in the command line. If no
 180 'CPU' option exists, that means the board only support one kind of processor,
 181 it's unnecessary to specify it)
 182
 183
 184 Note: Currently most IoTivity project doesn't support Windows, so you can't set
 185 TARGET_OS to 'windows' except the project support Windows.
 186
 187 That's to say if the project doesn't support Windows, run:
 188       $ scons TARGET_OS=windows ....
 189 or run on Windows
 190       $ scons
 191 may always fail.
 192
 193
 194 === Build IoTivity project on Mac OSX ===
 195
 196 1. Build IoTivity project for Mac OSX
 197       $ cd <top directory of the project>
 198       $ scons SYS_VERSION=yyy
 199 (yyy is the OSX version, e.g. 10.9)
 200
 201 2. Build IoTivity project for Android(It's the same as on Ubuntu)
 202       $ cd <top directory of the project>
 203       $ scons TARGET_OS=android TARGET_ARCH=xxx
 204 (xxx can be x86, armeabi, armeabi-v7a, armeabi-v7a-hard)
 205
 206 3. Build IoTivity project for IOS
 207       $ cd <top directory of the project>
 208       $ scons TARGET_OS=ios TARGET_ARCH=xxx SYS_VERSION=yyy
 209 (xxx can be i386, x86_64, armv7, armv7s, arm64, yyy is IOS version, e.g. 7.0)
 210
 211 Note:
 212 1) for convenience, a script (auto_build.sh) is provided to run possible build
 213 at once. Following is the usage:
 214
 215 To build:
 216      $ auto_build.sh <path-to-android-ndk> <path-to-arduino-home>
 217 To clean:
 218      $ auto_build.sh -c
 219
 220 2) For Arduino build, the Time library should >=1.3. The old can only be built
 221 with Arduino IDE 1.0.x