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