/pstat Resource CBOR fix
[iotivity.git] / Readme.scons.txt
index 27f89ce..5d92938 100644 (file)
@@ -1,16 +1,19 @@
 == Quick guide: build and run IoTivity projects on Ubuntu ==
 
 1. Build
-       Go to the top directory of 'iotivity' project(Note: should always run 'scons'
-command in this directory)
+    Go to the top directory of 'iotivity' project(Note: should always run 'scons'
+    command in this directory)
+
+    Install build tools:
+      $ sudo apt-get install git-core scons ssh build-essential g++ doxygen valgrind
 
     Install external libraries:
-      $ sudo apt-get install libboost-dev libboost-program-options-dev libexpat1-dev libboost-thread-dev
+      $ sudo apt-get install libboost-dev libboost-program-options-dev libboost-thread-dev uuid-dev libssl-dev libtool libglib2.0-dev libcap-dev libcurl4-openssl-dev autotools-dev autoconf
 
     Build release binaries:
       $ scons
-(Note: C++ sdk requires cereal. Please follow the instruction in the build
-message to install cereal)
+(Note: C sdk requires tinycbor. Please follow the instruction in the build
+message to install tinycbor)
 
     Build debug binaries:
       $scons RELEASE=false
@@ -28,6 +31,10 @@ message to install cereal)
 ('<iotivity>' is the path to 'iotivity' project. If your device is x86, arm,
 or arm64, please change 'x86_64' to the proper arch)
 
+3. To build and test IoTivity with Security enabled (required for certification)
+follow the instructions found in:
+  <iotivity>/resource/csdk/security/README-building-and-running-secure-IoTivity-stack.txt
+
 == How to build IoTivity projects ==
 
 IoTivity includes a series of projects. You can find all these projects here:
@@ -38,7 +45,7 @@ Linux, Tizen, Android, Arduino, Windows, MAC OSX, IOS ...).
 The output of the build is in:
   <top directory of the project>/out/<target_os>/<target_arch>/<build_type>/
 e.g.
-       oic-resource/out/android/armeabi-v7a/release/.
+       iotivity/out/android/armeabi-v7a/release/.
 
 This document takes 'iotivity' project as example, the way to build other
 projects is almost the same.
@@ -56,7 +63,16 @@ information(include build options). To see the help information:
       $ scons [options] -h
 
 Note: If no value is specified for an option, the default value will be used.
-The change of options value may impact the output.
+The change of options value may impact the help information and the behavior
+of the building.
+
+Generally, it's required to specify the target OS and target ARCH, that's to say
+tell Scons which OS and which ARCH you'd like build this project for. By default,
+the target OS and ARCH is the same as the host.
+
+Some more options may be required, please care the 'error' notification when build.
+For help about how to set an option, please run:
+     $ scons TARGET_OS=xxx TARGET_ARCH=yyy [XXX=zzz ...] -h
 
 
 === Prerequites ===
@@ -76,12 +92,12 @@ To build for Android, Andorid NDK and SDK are required.
   Android NDK: http://developer.android.com/tools/sdk/ndk/index.html
   Android SDK: http://developer.android.com/sdk/index.html
 (Note: as in some IoTivity projects, C++11 features are used, recommend Android
- NDK >= r10, according to our test result r10c is the best one currently)
+ NDK >= r10)
 
 Arduino:
 To build for Arduino, Arduino IDE is required.
   Arduino IDE: http://arduino.cc/en/Main/Software
-  (Note: recommend install Arduino IDE >=1.5.7)
+  (Note: recommend install Arduino IDE >=1.5.8)
 
 Arduino builds are dependent on latest Time library. Download it from here:
     http://www.pjrc.com/teensy/td_libs_Time.html
@@ -106,102 +122,186 @@ Java codes, this isn't required)
 so you don't need to add it in command line each time. The build script will
 guide you to do that.)
 
-=== Build IoTivity project on Linux(Ubuntu) ===
+Tizen:
+To build for tizen platform tinycbor library is needed.
+Please download tinycbor if it is not present in extlibs/tinycbor folder
+by doing the following:
+       $ git clone https://github.com/01org/tinycbor.git extlibs/tinycbor/tinycbor
 
-Generally, it's required to specify the target OS and target ARCH, that's to say
-tell Scons which OS and which ARCH you'd like build this project for. By default,
-the target OS and ARCH is the same as the host.
 
-Some more options may be required, please care the 'error' notification when build.
-For help about how to set an option, please run:
-       $ scons TARGET_OS=xxx TARGET_ARCH=yyy [XXX=zzz ...] -h
+* 3. External libraries
+IoTivity project depends on some external libraries, such as boost ...
+During building, the existence of external library will be checked, if it doesn't
+exist, the build script will try to download, unpack and build the library or
+notify user to install it.
 
-1. Build IoTivity project for Linux
-      $ cd <top directory of the project>
-      $ sudo apt-get install libboost-dev libboost-program-options-dev libexpat1-dev libboost-thread-dev
-      $ scons
+Downloading and unpacking may fail due to network problem or required unpacking
+tool isn't installed. An message will be displayed, please follow the message
+to skip it.
 
-2. Build IoTivity project for Android
-      $ cd <top directory of the project>
-      $ scons TARGET_OS=android TARGET_ARCH=xxx
-(xxx can be x86, armeabi, armeabi-v7a, armeabi-v7a-hard. To see all of its
-allowed value, please execute command 'scons TARGET_OS=android -Q -h')
-
-Note: Currently as x86_64/arm64_v8a external library binaries aren't provided,
-you may meet link problem if build executable binary which depends on external
-library for x86_64/arm64_v8a.
-
-3. Build IoTivity project for Arduino
-      $ cd <top directory of the project>
-      $ scons TARGET_OS=arduino TARGET_ARCH=xxx BOARD=yyy
-(xxx can be avr, arm; yyy is the name of the board, to get its allowed value
-run: scons TARGET_OS=arduino TARGET_ARCH=xxx -h. You may see a option 'CPU' in
-the output of above command line, that's due to some boards have different
-processors, to specify the processor, add 'CPU=zzz' in the command line. If no
-'CPU' option exists, that means the board only support one kind of processor,
-it's unnecessary to specify it)
-
-4. Build Iotivity project for Tizen
-      $ cd <top directory of the project>
-      $ gbs build -A xxx --packaging-dir tools/tizen/
-(xxx can be i586 or armv7l, we provide the spec file required by gbs tool at
-toools/tizen directory. gbs is default build tool for Tizen platfrom, we can
-refer the following wiki to setup Tizen development environment:
-https://source.tizen.org/documentation/developer-guide/getting-started-guide)
 
-=== Build IoTivity project on Windows ===
+=== Build IoTivity project ===
 
-1. Build IoTivity project for Android(It's the same as on Ubuntu)
-      $ cd <top directory of the project>
-      $ scons TARGET_OS=android TARGET_ARCH=xxx
-(xxx can be x86, armeabi, armeabi-v7a, armeabi-v7a-hard ...)
+Linux:
+ * Possible values for <TARGET_TRANSPORT> are: ALL, IP, BLE
 
-2. Build IoTivity project for Arduino(It's the same as on Ubuntu)
-      $ cd <top directory of the project>
-      $ scons TARGET_OS=arduino TARGET_ARCH=xxx BOARD=yyy
-(xxx can be avr, arm; yyy is the name of the board, to get its allowed value
-run: scons TARGET_OS=arduino TARGET_ARCH=xxx -h. You may see a option 'CPU' in
-the output of above command line, that's due to some boards have different
-processor, to specify the processor, add 'CPU=zzz' in the command line. If no
-'CPU' option exists, that means the board only support one kind of processor,
-it's unnecessary to specify it)
+1. Go to root directory
+    $ cd <top directory of the project>
+    $ sudo apt-get install libboost-dev libboost-thread-dev libssl-dev libtool
 
+2. Execute following command(s) to start build based on transport selection required
 
-Note: Currently most IoTivity project doesn't support Windows, so you can't set
-TARGET_OS to 'windows' except the project support Windows.
+    -> Building for all transports :
+    $ scons TARGET_OS=linux TARGET_TRANSPORT=ALL
 
-That's to say if the project doesn't support Windows, run:
-      $ scons TARGET_OS=windows ....
-or run on Windows
-      $ scons
-may always fail.
+    -> Building for a specific transport :
+    $ scons TARGET_OS=linux TARGET_TRANSPORT=IP
 
+    -> Building for multiple transports :
+    $ scons TARGET_OS=linux TARGET_TRANSPORT=IP,BLE TARGET_ARCH=xxx
 
-=== Build IoTivity project on Mac OSX ===
+    -> Clean Build (all transports) :
+    $ scons TARGET_OS=linux TARGET_TRANSPORT=ALL -c (for clean)
 
-1. Build IoTivity project for Mac OSX
-      $ cd <top directory of the project>
-      $ scons SYS_VERSION=yyy
-(yyy is the OSX version, e.g. 10.9)
+Android:
+ * Possible values for <TARGET_TRANSPORT> are: ALL, IP, BT, BLE
+ * Possible values for <TARGET_ARCH> are: x86, armeabi, armeabi-v7a, armeabi-v7a-hard
+   (To see all of its allowed value, please execute command 'scons TARGET_OS=android -Q -h')
+
+1. Go to root directory
+    $ cd <top directory of the project>
+
+2. Execute following command(s) to start build based on transport selection required
+
+    -> Building for all transports :
+    $ scons TARGET_OS=android TARGET_TRANSPORT=ALL TARGET_ARCH=xxx
+
+    -> Building for a specific transport :
+    $ scons TARGET_OS=android TARGET_TRANSPORT=IP TARGET_ARCH=xxx
+
+    -> Building for multiple transports :
+    $ scons TARGET_OS=android TARGET_TRANSPORT=IP,BT,BLE TARGET_ARCH=xxx
+
+    -> Clean Build (all transports) :
+    $ scons TARGET_OS=android TARGET_TRANSPORT=ALL -c (for clean)
+
+Tizen:
+ * Possible values for <TARGET_TRANSPORT> are: ALL, IP, BT, BLE
+
+ 1. Go to root directory
+    $ cd <top directory of the project>
 
-2. Build IoTivity project for Android(It's the same as on Ubuntu)
-      $ cd <top directory of the project>
-      $ scons TARGET_OS=android TARGET_ARCH=xxx
-(xxx can be x86, armeabi, armeabi-v7a, armeabi-v7a-hard)
+ 2. Execute following command(s) to start build based on transport selection required
 
-3. Build IoTivity project for IOS
-      $ cd <top directory of the project>
-      $ scons TARGET_OS=ios TARGET_ARCH=xxx SYS_VERSION=yyy
-(xxx can be i386, x86_64, armv7, armv7s, arm64, yyy is IOS version, e.g. 7.0)
+    -> Building for all transports :
+    $ scons TARGET_OS=tizen TARGET_TRANSPORT=ALL
+
+    -> Building for a specific transport :
+    $ scons TARGET_OS=tizen TARGET_TRANSPORT=IP
+
+    -> Building for multiple transports :
+    $ scons TARGET_OS=tizen TARGET_TRANSPORT=IP,BT,BLE TARGET_ARCH=xxx
+
+    -> Clean Build (all transports) :
+    $ scons TARGET_OS=tizen TARGET_TRANSPORT=ALL -c (for clean)
+
+(we provide the spec file required by gbs tool at toools/tizen directory.
+gbs is default build tool for Tizen platform, we can refer the following
+wiki to setup Tizen development environment:
+https://source.tizen.org/documentation/developer-guide/getting-started-guide)
+
+Arduino:
+ * Possible values for <TARGET_TRANSPORT> are: IP, BLE
+ * Possible values for <TARGET_ARCH> are: arv, arm
+    (arv: arduino due, arm: arduino mega)
+ * Possible values for <BOARD> are: arduino_due_x_dbg, arduino_due_x, mega
+ * Possible values for <SHIELD> are: ETH, WIFI
+    (It is required in the case of the arduino due.)
+
+ 1. Go to root directory
+    $ cd <top directory of the project>
+    $ sudo apt-get install dos2unix
+
+ 2. Execute following command(s) to start build based on transport selection required
+
+    -> Building for a specific transport :
+    $ scons TARGET_OS=arduino TARGET_ARCH=xxx BOARD=yyy SHIELD=zzz
+
+(To get allowed values run: scons TARGET_OS=arduino TARGET_ARCH=xxx SHIELD=zzz -h.
+You may see a option 'CPU' in the output of above command line, that's due to
+some boards have different processors, to specify the processor, add 'CPU=zzz'
+in the command line. If no 'CPU' option exists, that means the board only
+support one kind of processor, it's unnecessary to specify it)
+
+Mac OSX:
+ * Possible values for <SYS_VERSION> are: OSX version, e.g. 10.9
+
+ 1. Go to root directory
+    $ cd <top directory of the project>
+
+ 2. Execute following command(s) to start build based on transport selection required
+
+    -> Building for a specific transport :
+    $ scons SYS_VERSION=yyy
+
+IOS:
+ * Possible values for <TARGET_ARCH> are: i386, x86_64, armv7, armv7s, arm64
+ * Possible values for <SYS_VERSION> are: IOS version, e.g. 7.0
+
+ 1. Go to root directory
+    $ cd <top directory of the project>
+
+ 2. Execute following command(s) to start build based on transport selection required
+
+    -> Building for a specific transport :
+    $ scons TARGET_OS=ios TARGET_ARCH=xxx SYS_VERSION=yyy
+
+Windows:
+ * Possible values for <TARGET_ARCH> are: x86, amd64
+
+For convenience to build projects supported on Windows a batch file (run.bat) is provided
+to run many build combinations with TARGET_OS to 'windows'.
+
+1. Go to root directory
+    $ cd <top directory of the project>
+2. To clean before building:
+      $ run clean
+3. To build debug amd64 binaries:
+      $ run build
+4. To build x86 release/retail binaries and run unit tests:
+      $ run build -arch x86 -release
+See run.bat for more example usage parameters
+
+* Additional options
+ * VERBOSE=true or false (Show compilation)
+ * RELEASE=true or false (Build for release?)
+ * LOGGING=true or false (Enable stack logging)
+ * SECURED=1 or 0 (Build with DTLS)
+ * TEST=1 or 0 (Run unit tests)
+ * BUILD_SAMPLE=ON or OFF (Build with sample)
+ * ROUTING=GW or EP (Enable routing)
+ * WITH_TCP=true or false (Enable CoAP over TCP Transport, arduino is not supported)
+ * RD_MODE=CLIENT or SERVER (Build including Resource Directory)
+ * SIMULATOR=true or false (Build with simulator module)
+ * Possible values for <WITH_MQ> are: PUB,SUB,BROKER (Build including Message Queue)
+   -> PUB : publisher, SUB : subscriber, BROKER : MQ broker(not supported yet)
+ * LOG_LEVEL=DEBUG or INFO or WARNING or ERROR or FATAL
+   (select log level to print, LOGGING option should be true)
+    ex) LOG_LEVEL=DEBUG : All logs including DEBUG, INFO, WARNING, ERROR, FATAL level is printed.
+        LOG_LEVEL=INFO : The logs including INFO, WARNING, ERROR, FATAL level is printed.
+        LOG_LEVEL=WARNING : The logs including WARNING, ERROR, FATAL level is printed.
+        LOG_LEVEL=ERROR : The logs including ERROR, FATAL level is printed.
+        LOG_LEVEL=FATAL : FATAL level is printed.
+   Log entries that have the OC_LOG_PRIVATE_DATA bit set, in addition to DEBUG, INFO, WARNING,
+   ERROR, or FATAL, contain confidential information and therefore are not printed by default.
+   The application has to call OCSetLogLevel() to enable printing of private information in the
+   log.
 
 Note:
 1) for convenience, a script (auto_build.sh) is provided to run possible build
 at once. Following is the usage:
 
 To build:
-     $ auto_build.sh <path-to-android-ndk> <path-to-arduino-home>
+     $ auto_build.sh <path-to-android-ndk>
 To clean:
      $ auto_build.sh -c
-
-2) For Arduino build, the Time library should >=1.3. The old can only be built
-with Arduino IDE 1.0.x