/*
 *  Copyright 2011-15 ARM Limited and Contributors.
 *  All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are met:
 *    * Redistributions of source code must retain the above copyright
 *      notice, this list of conditions and the following disclaimer.
 *    * Redistributions in binary form must reproduce the above copyright
 *      notice, this list of conditions and the following disclaimer in the
 *      documentation and/or other materials provided with the distribution.
 *    * Neither the name of ARM Limited nor the
 *      names of its contributors may be used to endorse or promote products
 *      derived from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY ARM LIMITED AND CONTRIBUTORS "AS IS" AND
 *  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 *  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 *  DISCLAIMED. IN NO EVENT SHALL ARM LIMITED AND CONTRIBUTORS BE LIABLE FOR ANY
 *  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 *  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 *  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 *  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/*
 * NE10 Library : BuildingNe10.txt
 */

=========================BUILDING METHOD=================================

NE10 uses CMake to describe the build in a platform independent manner.

First download and install cmake from cmake.org.
In Ubuntu, you can install cmake by "sudo apt-get install cmake"

---------------------------NATIVE-COMPILING------------------------------

=Unix platforms=

For Unix platforms, say the following on a terminal:
(Replace $NE10PATH with the directory where this file is located.)
    cd $NE10PATH
    mkdir build && cd build
    export NE10_LINUX_TARGET_ARCH=armv7
    cmake -DGNULINUX_PLATFORM=ON ..
    make
Then the libNE10.a is placed in ./modules/ and a sample program
"NE10_test_static" is placed in ./samples/. you can run it. And default building
will build release version, if you want to build debug version, you can add
-DDEBUG=ON option to cmake.
You might want to add -DNE10_BUILD_SHARED=ON to the cmake call to generate the
dynamic library and test program "NE10_test_dynamic".
For AArch64, set NE10_LINUX_TARGET_ARCH to aarch64 instead of armv7.

=Android platforms=

It's not common do native compiling on android, Ne10 also doesn't support it.

---------------------------CROSS-COMPILING------------------------------

=Unix platforms=

For cross-compiling for unix platforms, the process is in the following:
    cd $NE10PATH

Open the GNUlinux_config.cmake and change the compiler toolchain to yourself. My
toolchain is Linaro GCC 4.6.
In Ubuntu 12.10 you can install it by "sudo apt-get install gcc-arm-linux-gnueabihf".
    set( CMAKE_C_COMPILER arm-linux-gnueabihf-gcc )
    set( CMAKE_CXX_COMPILER arm-linux-gnueabihf-g++ )
    set( CMAKE_ASM_COMPILER arm-linux-gnueabihf-as )

    find_program(CMAKE_AR NAMES "arm-linux-gnueabihf-ar")
    mark_as_advanced(CMAKE_AR)

    find_program(CMAKE_RANLIB NAMES "arm-linux-gnueabihf-ranlib")
    mark_as_advanced(CMAKE_RANLIB)

Now you can use the following commands to generate makefile.
    mkdir build && cd build
    cmake -DCMAKE_TOOLCHAIN_FILE=../GNUlinux_config.cmake ..
    make

For system uses soft float point, you should modify the add following option to
CMAKE_C_FLAGS and CMAKE_ASM_FLAGS for GNULINUX_PLATFORM in the root
CMakeLists.txt:

    -mfloat-abi=softfp -mfpu=neon

Then the libNE10.a is placed in ./modules/ and a sample program
"NE10_test_static" is placed in ./samples/. you can copy these to the target and
run it.

You might want to add -DNE10_BUILD_SHARED=ON to the cmake call to generate the
dynamic library and test program "NE10_test_dynamic".

Note:
- When you run NE10_test_dynamic on the target, you might meet the error:
    "NE10_test_dynamic: error while loading shared libraries:
     libNE10_shared.so.10: cannot open shared object file:  No such file or
     directory"
  You can run the following command:
    export LD_LIBRARY_PATH=$NE10PATH/build/modules

- default building will build release version, if you want to build debug
  version, you can add -DDEBUG=ON option to cmake.

=Android platforms=

For cross-compiling for android, the note to Unix platforms also applies and
before cross-compiling, you must have the android NDK installed. And then:
   cd $NE10PATH
   export ANDROID_NDK=/absolute/path/of/android-ndk
   export NE10_IOS_TARGET_ARCH=armv7
   mkdir build && cd build
   cmake -DCMAKE_TOOLCHAIN_FILE=path/of/android_config.cmake ..
   make

For AArch64, set NE10_IOS_TARGET_ARCH to aarch64 instead of armv7.
There are also two other environment variable:
   ANDROID_API_LEVEL: used to specify android api level, default value is: 14,
                      for AArch64, android api level must be >= 21
   ARM_ANDROID_TOOLCHAIN_VERSION: used be specify gcc version, default is: 4.6,
                                  for AArch64, gcc version must be >=4.8

And default building will build release version, if you want to build debug
version, you can add -DDEBUG=ON option to cmake.

=iOS platforms=

For cross-compiling for iOS, the note to Unix platforms also applies and before
cross-compiling, you must have the Xcode installed. Our assembly code is written
for GNU as(gas) initially, the assembler for iOS platform doesn't support it
very well. However we get our code worked under Apple LLVM version 4.2
(clang-425.0.28) (based on LLVM 3.2svn) now, other toolchain(such as llvm-gcc)
may not work. After Xcode installed, you should set the IOS_DEVELOPER_PATH
environment variable to your Xcode path, if you haven't changed the default
install path, it should be "/Applications/Xcode.app/Contents/Developer".
As follow:
   cd $NE10PATH
   export IOS_DEVELOPER_PATH=/absolute/path/of/ios/developer/path
   export NE10_IOS_TARGET_ARCH=armv7
   mkdir build && cd build
   cmake -DCMAKE_TOOLCHAIN_FILE=/path/of/ios_config.cmake ..
   make

Note:
- for cmake step: if cmake warns: ignoring CMAKE_OSX_SYSROOT value and that
  directory does not exist, you should check your SDKs directory. And if
  necessary, you can specify this path in ios_config.cmake. That is changing the
  variable CMAKE_IOS_SDK_PATH to your configuration.
- we provide a option called: MIN_IOS_VER, which is used to specify minimal
  target iOS version. For example, you can add -DMIN_IOS_VER=5.0 when run cmake.
  MIN_IOS_VER's default value is 5.0. And when your target is older than iOS 7.0
  you should not define MIN_IOS_VER to iOS 7.0. Otherwise, it would lead runtime
  error.
- for AArch64, set NE10_IOS_TARGET_ARCH to aarch64 instead of armv7.

=Ne10 demo=

There are 2 demos include Ne10, one for Android and one for iOS. Both demos need
Ne10 library and it's native side interface library installed, to do that, after
build NE10, you should run "make install" in the same directory. And after that,
you can import or open the project file in android SDK or Xcode as usually. And
please also note that your devices should be have access to internet to run the
demo.

---------------------------UNIT TEST------------------------------

The unit test framework of Ne10 is based on seatest
(http://code.google.com/p/seatest/).
But I also made some modifications to be more suitable for Ne10.

The unit test consists of smoke test, regression test and performance test.
If you want to do the test, you just need to add the following options when you
compile the library.

smoke test       -------->> -DNE10_BUILD_UNIT_TEST=on -DNE10_SMOKE_TEST=on
regression test  -------->> -DNE10_BUILD_UNIT_TEST=on -DNE10_REGRESSION_TEST=on
performance test -------->> -DNE10_BUILD_UNIT_TEST=on -DNE10_PERFORMANCE_TEST=on

example:
run the following commands.
    mkdir build && cd build
    cmake -DNE10_BUILD_UNIT_TEST=on -DNE10_SMOKE_TEST=on ..
    make

Then the corresponding test program will be generated in the directory ./test/

--------------------------------END--------------------------------------
