/pstat Resource CBOR fix
[iotivity.git] / Readme.scons.txt
index 4ea28b1..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 uuid-dev libssl-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:
@@ -90,7 +97,7 @@ To build for Android, Andorid NDK and SDK are required.
 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
@@ -116,17 +123,14 @@ so you don't need to add it in command line each time. The build script will
 guide you to do that.)
 
 Tizen:
-To build for tizen platform cereal library is needed.
-Please download cereal if it is not present in extlibs/cereal folder
-and apply the patch as following:
-       $ git clone https://github.com/USCiLab/cereal.git extlibs/cereal/cereal
-       $ cd  extlibs/cereal/cereal
-       $ git reset --hard 7121e91e6ab8c3e6a6516d9d9c3e6804e6f65245
-       $ git apply ../../../resource/patches/cereal_gcc46.patch
+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
 
 
 * 3. External libraries
-IoTivity project depends on some external libraries, such as boost, expat ...
+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.
@@ -136,81 +140,162 @@ tool isn't installed. An message will be displayed, please follow the message
 to skip it.
 
 
-=== Build IoTivity project on Linux(Ubuntu) ===
+=== Build IoTivity project ===
 
-1. Build IoTivity project for Linux
-      $ cd <top directory of the project>
-      $ sudo apt-get install libboost-dev libexpat1-dev libboost-thread-dev libssl-dev
-      $ scons
+Linux:
+ * Possible values for <TARGET_TRANSPORT> are: ALL, IP, BLE
 
-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')
-
-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>
-      $ sh gbsbuild.sh
-(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)
+1. Go to root directory
+    $ cd <top directory of the project>
+    $ sudo apt-get install libboost-dev libboost-thread-dev libssl-dev libtool
 
-=== Build IoTivity project on Android ===
+2. Execute following command(s) to start build based on transport selection required
 
-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 ...)
+    -> Building for all transports :
+    $ scons TARGET_OS=linux TARGET_TRANSPORT=ALL
 
-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)
+    -> 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
 
-Note: Currently most IoTivity project doesn't support Windows, so you can't set
-TARGET_OS to 'windows' except the project support Windows.
+    -> Clean Build (all transports) :
+    $ scons TARGET_OS=linux TARGET_TRANSPORT=ALL -c (for clean)
 
-That's to say if the project doesn't support Windows, run:
-      $ scons TARGET_OS=windows ....
-or run on Windows
-      $ scons
-may always fail.
+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
 
-=== Build IoTivity project on Mac OSX ===
+    -> Clean Build (all transports) :
+    $ scons TARGET_OS=android 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)
+Tizen:
+ * Possible values for <TARGET_TRANSPORT> are: ALL, IP, BT, BLE
+
+ 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=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
 
-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)
+    -> Clean Build (all transports) :
+    $ scons TARGET_OS=tizen TARGET_TRANSPORT=ALL -c (for clean)
 
-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)
+(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
@@ -220,6 +305,3 @@ To build:
      $ 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