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://oic-review.01.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 version>/
  10 e.g.
  11         oic-resource/out/android/armeabi-v7a/release/.
  12
  13 This document takes oic-resource 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 1. Build Iotivity project for Linux
  96       $ cd <top directory of the project>
  97       $ sudo apt-get install libboost-dev libboost-program-options-dev
  98       $ scons
  99
 100 2. Build Iotivity project for Android
 101       $ cd <top directory of the project>
 102       $ scons TARGET_OS=android TARGET_ARCH=xxx
 103 (xxx can be x86, armeabi, armeabi-v7a, armeabi-v7a-hard. To see all of its
 104 allowed value, please execute command 'scons TARGET_OS=android -Q -h'.
 105
 106 Note: Currently as x86_64/arm64_v8a external library binaries aren't provided,
 107 you may meet link problem if build executable binary which depends on external
 108 library for x86_64/arm64_v8a.
 109
 110 3. Build Iotivity project for Arduino
 111       $ cd <top directory of the project>
 112       $ scons TARGET_OS=arduino TARGET_ARCH=xxx BOARD=yyy
 113 (xxx can be avr, arm; yyy is the name of the board, to get its allowed value
 114 run: scons TARGET_OS=arduino TARGET_ARCH=xxx -h. You may see a option 'CPU' in
 115 the output of above command line, that's due to some boards have different
 116 processor, to specify the processor, add 'CPU=zzz' in the command line. If no
 117 'CPU' option exists, that means the board only support one kind of processor,
 118 it's unnecessary to specify it)
 119
 120 4. Build Iotivity project for Tizen
 121       $ cd <top directory of the project>
 122       $ gbs build -A xxx --packaging-dir tools/tizen/
 123 (xxx can be i586 or armv7l, we provide the spec file required by gbs tool at
 124 toools/tizen directory. gbs is default build tool for Tizen platfrom, we can
 125 refer the following wiki to setup Tizen development environment:
 126 https://source.tizen.org/documentation/developer-guide/getting-started-guide)
 127
 128 === Build Iotivity project on Windows ===
 129
 130 1. Build Iotivity project for Android(It's the same as on Ubuntu)
 131       $ cd <top directory of the project>
 132       $ scons TARGET_OS=android TARGET_ARCH=xxx
 133 (xxx can be x86, armeabi, armeabi-v7a, armeabi-v7a-hard ...)
 134
 135 2. Build Iotivity project for Arduino(It's the same as on Ubuntu)
 136       $ cd <top directory of the project>
 137       $ scons TARGET_OS=arduino TARGET_ARCH=xxx BOARD=yyy
 138 (xxx can be avr, arm; yyy is the name of the board, to get its allowed value
 139 run: scons TARGET_OS=arduino TARGET_ARCH=xxx -h. You may see a option 'CPU' in
 140 the output of above command line, that's due to some boards have different
 141 processor, to specify the processor, add 'CPU=zzz' in the command line. If no
 142 'CPU' option exists, that means the board only support one kind of processor,
 143 it's unnecessary to specify it)
 144
 145
 146 Note: Currently most Iotivity project doesn't support Windows, so you can't set
 147 TARGET_OS to 'windows' except the project support Windows.
 148
 149 That's to say if the project doesn't support Windows, run:
 150       $ scons TARGET_OS=windows ....
 151 or run on Windows
 152       $ scons
 153 may always fail.
 154
 155
 156 === Build Iotivity project on Mac OSX ===
 157
 158 1. Build Iotivity project for Mac OSX
 159       $ cd <top directory of the project>
 160       $ scons SYS_VERSION=yyy
 161 (yyy is the OSX version, e.g. 10.9)
 162
 163 2. Build Iotivity project for Android(It's the same as on Ubuntu)
 164       $ cd <top directory of the project>
 165       $ scons TARGET_OS=android TARGET_ARCH=xxx
 166 (xxx can be x86, armeabi, armeabi-v7a, armeabi-v7a-hard)
 167
 168 3. Build Iotivity project for IOS
 169       $ cd <top directory of the project>
 170       $ scons TARGET_OS=ios TARGET_ARCH=xxx SYS_VERSION=yyy
 171 (xxx can be i386, x86_64, armv7, armv7s, arm64, yyy is IOS version, e.g. 7.0)
 172
 173 Note:
 174 1) for convenience, a script (auto_build.sh) is provided to run possible build
 175 at once. Following is the usage:
 176
 177 To build:
 178      $ auto_build.sh <path-to-android-ndk> <path-to-arduino-home>
 179 To clean:
 180      $ auto_build.sh -c
 181
 182 2) Last sync and test with commit e9403ce6d4d7a1a0ac8d12c5acc876af7f7a8f76
 183 If you meet build error with newest code, it may due to the scripts are not up
 184 to date. Please try commit 5f16c38a5380e4b5c0d82e2cfea4af5fdc30c9ac or send mail
 185 to <OIC-OSD@list.01.org>.
 186
 187 3) The build scripts for services have been provided. As the services code is
 188 out of date, it must the sync with newest resource code, otherwise, it can't
 189 pass the build, currently, the build scripts for services aren't enabled. Please
 190 remove the '#' at line 31 in 'SConstruct' file to enable it after the code is
 191 updated.
 192
 193 4) For Arduino build, the Time library should >=1.3. The old can only be built
 194 with Arduino IDE 1.0.x