Scol

h1. Start to build Scol using CMAKE

h2. Tools

h3. Common to all platforms

* "CMake":http://www.cmake.org/download/ (While installing, allow CMake to add the CMake directory to the PATH)

* Visual Studio Community 2015 Update 3

* "Tortoise SVN":http://tortoisesvn.net/ (or any SVN client)

* "Tortoise git":https://code.google.com/p/tortoisegit/ (or any Git client too)

* "Yasm":https://yasm.tortall.net/Download.html (download the exe version, rename it to "yasm.exe" and add its location to the PATH)

* "Nasm":https://www.nasm.us/ (once installed, add its location to the PATH)

h3. Windows target

* "DirectX9 SDK":https://www.microsoft.com/en-us/download/details.aspx?id=6812

If the installation fails: https://support.microsoft.com/fr-fr/help/2728613/s1023-error-when-you-install-the-directx-sdk-june-2010

* a Perl installation (such as "Strawberry Perl":http://strawberryperl.com/)

Be careful not to let Perl add paths to c headers and executables to your path as it can mess with your build environnement

* "MSYS2":https://www.msys2.org/ (once installed, launch an msys2.exe and install make with the command "pacman -S make")

The minimum compiler supported is the one in Visual Studio 2015.

You can try with a newer version at your own risks !

h3. Android target

_With standard tools_

i.e. free tools found on the web or provided by Google

* "Java Development Kit (JDK)":http://www.oracle.com/technetwork/java/javase/downloads

* "Android SDK":https://developer.android.com/sdk/installing

* "Native Development Kit (NDK)":https://developer.android.com/tools/sdk/ndk

* "Apache ANT":http://ant.apache.org/

_With Tegra Android Development Pack_

A package provided by Nvidia to build applications for Android. The download process requires authentication to the Nvidia Developper Network (it's free and not too spammy though)

* "TADP":https://developer.nvidia.com/gameworksdownload

* On setup, let it download everything or at least the tools described in the previous section.

_SDK preparation_

You should launch the SDK to download other tools like emulators for each API you want to target.

(Our target API is 19 so you can get any emulator above).

h3. Linux target

TODO.

h3. Mac OS target

TODO.

h2. Get the Scol sources

Scol uses Subversion for source control and you can use your SVN client to get the source code.

So first retrieve the sources from "https://svn.scolring.org/trunk/", accept the certificate and go take some coffee.

The source directories contains most of the dependencies, and since some of them are modified they are provided in the sources.

Some sources like curl use Git as source control and are downloaded when building, so make sure it's installed before building the project

h2. Dependencies search paths

h3. Windows

Once you get the sources, you can execute "setWindowsSearchPaths.bat" in the dependencies directory.

!!WARNING!! when you execute the bat file using the mouse the current directory is wrong.

You need to start a DOS command line "cmd.exe" as administrator and go to the dependencies directory to start the bat file manually.

This will add needed environment variables and paths.

Additionally, you need to add the folders where you installed Nasm and Yasm to your Path environment variable

h3. Android

If you downloaded the TADP, the following variables are likely to be defined already (or they should look alike).

If not, add these to the environment variables

* ANDROID_HOME : path/to/sdk

* ANDROID_SDK_HOME : path/to/sdk

* ANDROID_SDK : path/to/sdk

* ANDROID_NDK : path/to/ndk

* ANT_HOME : path/to/ant

* JAVA_HOME : path/to/jdk -- should be something like "C:\Progra~1\Java\<jdkfolder>"

* CMAKE : path/to/cmake

Then you should add these variables into the PATH:

@%ANDROID_NDK%;%ANT_HOME%\bin;%ANDROID_SDK%\tools;%ANDROID_SDK%\platform-tools;%CMAKE%;%JAVA_HOME%\bin;@

h2. Build needed dependencies

h3. From Windows, for Windows

The following instructions are written to compile for 32 bits Windows. To compile for 64 bits Windows, use the 64 bits toolchain for each CMake configuration, and replace every instance of "x86" by "x64" in the instructions below.

Launch cmake-gui from a Visual Studio command line (it configures the environment so you can build things correctly)

# Specify the source folder to trunk/dependencies and the build to trunk/dependencies/build/windows/x86

# Hit Configure. In the message box, select your Visual Studio version as generator, and select "Specify toolchain file for cross-compiling". On the next screen, select trunk/dependencies/CMake/toolchain/win32.toolchain.cmake as the toolchain (for 64 bits, select the 64 bits variant of your VS version, and select trunk/dependencies/CMake/toolchain/win64.toolchain.cmake as the toolchain). This first configure will take a long time since it will download and compile some of the basic dependencies (probably about an hour depending on the power.

You will see a list of categories, under which are variables to tweak build parameters.

The category SCOLDEPS contains CMake variables that enable/disable the build of individual SCOL dependencies.

Some of these dependencies depend on one or several others. Since CMake needs to detect these "sub-dependencies" when configuring,

we need to make several build passes, in order to build said "sub-dependencies" before the dependencies that depend on them.

# Leave all variables at their default values.

# Keep hitting Configure until no variables are highlighted in red.

# Hit Generate to generate a Visual Studio project.

# Build the project in Visual Studio (Build->Batch Build, check debug and release for "INSTALL" configuration).

# When the build is done, in CMake, check HYDRAX and SKYX under SCOLDEPS (leave the other variables as they are).

# Hit Configure again. When configuring is done, you will see new variables appear in red. Leave them at their default values.

# Repeat steps 2 to 4.

# HYDRAX / SKYX build might fail due to header conflicts. To solve them, in Visual Studio :

## In the solution explorer, open the properties of the *RenderSystem_Direct3D11* project.

## In the properties window, Select *All configurations*.

## Under *Configuration Properties* > *C/C++* > *General*, modify the *Other include directories* entry.

## In the directories list, move the directory at the bottom all the way to the top.

## Save the changes.

## Repeat the same steps for the *RenderSystem_Direct3D9* project.

## Re-run the build.

# Optionnal: Check SCOLDEPS_BUILD_TUIO and SCOLDEPS_BUILD_TUIO, hit configure and repeat steps 2 to 4.

Now every required dependency should be built. The ones that we left unchecked aren't needed.

h3. From Windows, for Android

Supported ABIs : armeabi-v7a, arm64-v8a, x86, x86_64

Android API version : 19 (21 for 64 bits ABIs)

Do the same as for Windows target, but

* If you did not already make a Windows build, run trunk/dependencies/boost/bootstrap.bat from a Visual Studio command line

* Set source folder to trunk/dependencies and build folder to trunk/scol/build/android/<target ABI> (More generally, replace every instance of "windows/x86" in the build and install paths by "android/<target ABI>")

* Specify the generator : "NMake"

* The toolchain for crosscompile : trunk/dependencies/CMake/toolchain/android.<target ABI>.toolchain.cmake

* When building the Scol dependencies uncheck CAUDIO_ENABLE_REROUTE_STL_ALLOCATIONS

* Build dependencies with "nmake install" command from a Visual Studio command line.

h2. Build the Scol project

As for the dependencies:

h3. Windows target

* Set source folder to trunk/scol and build folder to trunk/scol/build/windows/x86

* Hit configure and provide the toolchain, the same as for the dependencies

* Generate and build from Visual Studio

h3. Android target

* Set source folder to trunk/scol and build folder to trunk/scol/build/android/<target abi>

* If you're using Nsight with Visual Studio (TADP), some build paramaters should be modified for each build if you want to install and test the project on a device :

  - Open ScolLauncher subproject -> properties

  - Configuration Properties -> General -> Configuration Type -> Make Application (ndk-build -> .apk|.so|.a)

  - Configuration Properties -> Deployment -> Fast Deploy -> No

  - Configuration Properties -> Ant Build -> Skip Ant Step -> No

* Without TADP, after it's build, go to trunk/scol/build/android/<target abi>/App/bin, and run "ant debug install" if you wish to install the project on an emulator or your device  

h1. Start your new plugin

h2. Source paths

Start by creating a directory with your new plugin name in the trunk/scol/plugins folder.

For example trunk/scol/plugins/myPlugin

Usually we prefer to separate the sources and the includes.

So creates a "src" and "include" directory in your plugin folder.

Creates the empty files you will need for your project, usually :

- include/myplugin.h for your classes declaration

- src/myplugin.cpp for your classes definition

- src/scolplugin.cpp for the Scol binding functions

h2. Dependencies

If your project need an external SDK or dependencies, add then in the trunk/dependencies directory.

Then create a findMydepname.cmake file in trunk\scol\CMake\Packages.

You can copy and change an existing Find.cmake file to make yours.

Start from a simple one like FindMyo.cmake for example.

h2. Cmake files

It's time to creates the CMAKE script for your plugin.

Create a "CMakeLists.txt" file in the plugin directory.

trunk/scol/plugins/myPlugin/CMakeLists.txt

And edit the file with a text editor.

<pre>

#-------------------------------------------------------------------

# This file is part of the CMake build system for Scol

#

# The contents of this file are placed in the public domain. Feel

# free to make use of it in any way you like.

#-------------------------------------------------------------------

############################################################

# CmakeList file for Myplugin

############################################################

#Your project name

PROJECT(myPLugin)

# define header and source files for the library

set (MYPLUGIN_HEADER_FILES

  include/myplugin.h

)

set (MYPLUGIN_SOURCE_FILES

  src/myplugin.cpp

  src/scolplugin.cpp

)

# Add includes directories from dependencies

#  include_directories(include ${MYDEP_INCLUDE_DIRS})

# Add definition for P4 optimizations, warnings removal.

add_definitions(-DOPTI_P4 -D_CRT_SECURE_NO_WARNINGS -D)

# Add dependencies libraries

#  set(LIBRARIES

#    ${MYDEP_LIBRARIES}

#    ${ZLIB_LIBRARIES}

#    ${PNG_LIBRARIES}

#  )

# setup Scol plugin target

add_library(myPLugin

  ${Scol_LIB_TYPE}

  ${MYPLUGIN_HEADER_FILES}

  ${MYPLUGIN_SOURCE_FILES}

)

add_dependencies(myPLugin kernel)

# set the dll version.

set_target_properties(myPLugin PROPERTIES VERSION ${Scol_VERSION} SOVERSION ${Scol_VERSION_MAJOR})

target_link_libraries(myPLugin ${LIBRARIES})

# install Scol

scol_config_plugin(myPLugin)

install(FILES ${MYPLUGIN_HEADER_FILES} DESTINATION include/SCOL/plugins/myPLugin)

</pre>

Now we need to declare this new plugin in the common Scol cmake files.

Edit the trunk/scol/CMakeLists.txt file and add your plugin definition like the following.

If you don't have dependencies.

<pre>

option(Scol_BUILD_MYPLUGIN "Build myPluginplugin, my library" TRUE)

</pre>

If you have depencies

<pre>

cmake_dependent_option(Scol_BUILD_MYPLUGIN "Build myPlugin, my library." TRUE "MYDEP_FOUND;ZLIB_FOUND;PNG_FOUND" FALSE)

</pre>

Now edit the trunk/scol/plugin/CMakeLists.txt file and add the following.

<pre>

# Configure myPlugin plugin build

if (Scol_BUILD_MYPLUGIN)

  add_subdirectory(myPlugin)

endif ()

</pre>

Only if you have dependencies, edit the trunk/scol/CMake/ScolDependencies.cmake file and add the dependencies resolution as the following

<pre>

# Find MyDep

find_package(MYDEP)

macro_log_feature(MYDEP_FOUND "Mydep" "MydepLibrary" "http://Mydep.org/" FALSE "" "")

</pre>

h2. Almost done

Open the CMAKE-gui again.

Hit the "Configure button" and check if you found your plugin in the scol group.

Then hit the generate button, and open the scol.sln project again.

You should have the project added in Visual Studio.