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 libboost-thread-dev uuid-dev libssl-dev libtool
   9
  10     Build release binaries:
  11       $ scons
  12 (Note: C sdk requires tinycbor. Please follow the instruction in the build
  13 message to install tinycbor)
  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.8)
  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 tinycbor library is needed.
 120 Please download tinycbor if it is not present in extlibs/tinycbor folder
 121 by doing the following:
 122         $ git clone https://github.com/01org/tinycbor.git extlibs/tinycbor/tinycbor
 123
 124
 125 * 3. External libraries
 126 IoTivity project depends on some external libraries, such as boost ...
 127 During building, the existence of external library will be checked, if it doesn't
 128 exist, the build script will try to download, unpack and build the library or
 129 notify user to install it.
 130
 131 Downloading and unpacking may fail due to network problem or required unpacking
 132 tool isn't installed. An message will be displayed, please follow the message
 133 to skip it.
 134
 135
 136 === Build IoTivity project ===
 137
 138 Linux:
 139  * Possible values for <TARGET_TRANSPORT> are: ALL, IP, BLE
 140
 141 1. Go to root directory
 142     $ cd <top directory of the project>
 143     $ sudo apt-get install libboost-dev libboost-thread-dev libssl-dev libtool
 144
 145 2. Execute following command(s) to start build based on transport selection required
 146
 147     -> Building for all transports :
 148     $ scons TARGET_OS=linux TARGET_TRANSPORT=ALL
 149
 150     -> Building for a specific transport :
 151     $ scons TARGET_OS=linux TARGET_TRANSPORT=IP
 152
 153     -> Building for multiple transports :
 154     $ scons TARGET_OS=linux TARGET_TRANSPORT=IP,BLE TARGET_ARCH=xxx
 155
 156     -> Clean Build (all transports) :
 157     $ scons TARGET_OS=linux TARGET_TRANSPORT=ALL -c (for clean)
 158
 159 Android:
 160  * Possible values for <TARGET_TRANSPORT> are: ALL, IP, BT, BLE
 161  * Possible values for <TARGET_ARCH> are: x86, armeabi, armeabi-v7a, armeabi-v7a-hard
 162    (To see all of its allowed value, please execute command 'scons TARGET_OS=android -Q -h')
 163
 164 1. Go to root directory
 165     $ cd <top directory of the project>
 166
 167 2. Execute following command(s) to start build based on transport selection required
 168
 169     -> Building for all transports :
 170     $ scons TARGET_OS=android TARGET_TRANSPORT=ALL TARGET_ARCH=xxx
 171
 172     -> Building for a specific transport :
 173     $ scons TARGET_OS=android TARGET_TRANSPORT=IP TARGET_ARCH=xxx
 174
 175     -> Building for multiple transports :
 176     $ scons TARGET_OS=android TARGET_TRANSPORT=IP,BT,BLE TARGET_ARCH=xxx
 177
 178     -> Clean Build (all transports) :
 179     $ scons TARGET_OS=android TARGET_TRANSPORT=ALL -c (for clean)
 180
 181 Tizen:
 182  * Possible values for <TARGET_TRANSPORT> are: ALL, IP, BT, BLE
 183
 184  1. Go to root directory
 185     $ cd <top directory of the project>
 186
 187  2. Execute following command(s) to start build based on transport selection required
 188
 189     -> Building for all transports :
 190     $ scons TARGET_OS=tizen TARGET_TRANSPORT=ALL
 191
 192     -> Building for a specific transport :
 193     $ scons TARGET_OS=tizen TARGET_TRANSPORT=IP
 194
 195     -> Building for multiple transports :
 196     $ scons TARGET_OS=tizen TARGET_TRANSPORT=IP,BT,BLE TARGET_ARCH=xxx
 197
 198     -> Clean Build (all transports) :
 199     $ scons TARGET_OS=tizen TARGET_TRANSPORT=ALL -c (for clean)
 200
 201 (we provide the spec file required by gbs tool at toools/tizen directory.
 202 gbs is default build tool for Tizen platfrom, we can refer the following
 203 wiki to setup Tizen development environment:
 204 https://source.tizen.org/documentation/developer-guide/getting-started-guide)
 205
 206 Arduino:
 207  * Possible values for <TARGET_TRANSPORT> are: IP, BLE
 208  * Possible values for <TARGET_ARCH> are: arv, arm
 209     (arv: arduino due, arm: arduino mega)
 210  * Possible values for <BOARD> are: arduino_due_x_dbg, arduino_due_x, mega
 211  * Possible values for <SHIELD> are: ETH, WIFI
 212     (It is required in the case of the arduino due.)
 213
 214  1. Go to root directory
 215     $ cd <top directory of the project>
 216     $ sudo apt-get install dos2unix
 217
 218  2. Execute following command(s) to start build based on transport selection required
 219
 220     -> Building for a specific transport :
 221     $ scons TARGET_OS=arduino TARGET_ARCH=xxx BOARD=yyy SHIELD=zzz
 222
 223 (To get allowed values run: scons TARGET_OS=arduino TARGET_ARCH=xxx SHIELD=zzz -h.
 224 You may see a option 'CPU' in the output of above command line, that's due to
 225 some boards have different processors, to specify the processor, add 'CPU=zzz'
 226 in the command line. If no 'CPU' option exists, that means the board only
 227 support one kind of processor, it's unnecessary to specify it)
 228
 229 Mac OSX:
 230  * Possible values for <SYS_VERSION> are: OSX version, e.g. 10.9
 231
 232  1. Go to root directory
 233     $ cd <top directory of the project>
 234
 235  2. Execute following command(s) to start build based on transport selection required
 236
 237     -> Building for a specific transport :
 238     $ scons SYS_VERSION=yyy
 239
 240 IOS:
 241  * Possible values for <TARGET_ARCH> are: i386, x86_64, armv7, armv7s, arm64
 242  * Possible values for <SYS_VERSION> are: IOS version, e.g. 7.0
 243
 244  1. Go to root directory
 245     $ cd <top directory of the project>
 246
 247  2. Execute following command(s) to start build based on transport selection required
 248
 249     -> Building for a specific transport :
 250     $ scons TARGET_OS=ios TARGET_ARCH=xxx SYS_VERSION=yyy
 251
 252 * Additional options
 253  * VERBOSE=true or false (Show compilation)
 254  * RELEASE=true or false (Build for release?)
 255  * LOGGING=true or false (Enable stack logging)
 256  * SECURED=1 or 0 (Build with DTLS)
 257  * TEST=1 or 0 (Run unit tests)
 258  * SECURED=1 or 0 (Build with DTLS)
 259  * BUILD_SAMPLE=ON or OFF (Build with sample)
 260  * ROUTING=GW or EP (Enable routing)
 261  * WITH_TCP=true or false (Enable CoAP over TCP Transport, arduino is not supported)
 262  * WITH_RA=true or false (Build with Remote Access module)
 263  * WITH_RD=1 or 0 (Build including Resource Directory)
 264  * SIMULATOR=true or false (Build with simulator module)
 265
 266 Note1: Currently most IoTivity project doesn't support Windows, so you can't set
 267 TARGET_OS to 'windows' except the project support Windows.
 268
 269 That's to say if the project doesn't support Windows, run:
 270       $ scons TARGET_OS=windows ....
 271 or run on Windows
 272       $ scons
 273 may always fail.
 274
 275 Note2:
 276 1) for convenience, a script (auto_build.sh) is provided to run possible build
 277 at once. Following is the usage:
 278
 279 To build:
 280      $ auto_build.sh <path-to-android-ndk>
 281 To clean:
 282      $ auto_build.sh -c