Scol

h1. Start to build Scol using CMAKE

h2. Prepare all the necessary tools

Before going any further, you should take care of having everything ready for the builds.

h3. Windows

On Windows, the Scol project is built with CMake and Visual Studio 2010.

* You can get CMake freely at http://www.cmake.org/download/

* However Visual Studio 2010 is not free. If you don't have it you can still get Visual Studio 2010 express at https://www.visualstudio.com/downloads/download-visual-studio-vs (there is VS 2010 express down the page) or the complete edition by -getting the torrent- having a good friend who still has the software at home. Because as far as I know you can't even buy it anymore. Hopefully the express edition should suffice. Eventually the build will migrate to a newer VS edition (like VS 2013 community edition, which is free as soon as you are not doing commercial products).

It should be about it.

h3. Android

On Android you need to download more stuff. The configurator is also CMake but you can build the final project with almost anything.

At I-Maginer we're using Visual Studio 2013 community edition with some Nvidia plugins, and NMake (which is provided by any version of Visual Studio).

First thing is then to download CMake and a version of Visual Studio that suits you.

When it's done, you have got 2 options : either you want to rely on Visual Studio or only on NMake manual commands.

* If you opted for the first choice, it's quite simple, just go to https://developer.nvidia.com/gameworksdownload and download the Tegra Android Development Pack (TADP). It contains all you need to develop for android targets, available on Windows, Linux and Mac OS platforms. It will add the Visual Studio "Nsight Tegra" plugin, the android SDK and NDK and all the environment variables you'll need.

* If you chosed the second choice, well, it's the way of the hero.

¤ Download the JDK (Java Development Kit) at http://www.oracle.com/technetwork/java/javase/downloads

¤ Fetch the Android SDK (Software Development Kit) at https://developer.android.com/sdk/installing and go for "Stand-Alone SDK tools" -- when it's done, extract the content and put it in some memorable folder where you keep your dev SDK

¤ Same for the Android NDK (Native Development Kit) at https://developer.android.com/tools/sdk/ndk

¤ Finally get the ANT (Another Neat Tool) build system at http://ant.apache.org/

Now everything is downloaded, there's one last thing to do :

¤ Launch the Android SDK (you can find it in your Android SDK folder) and let it download all the things it wants. 

h2. Get the Scol sources

Scol use Subversion for source control and you can use "Tortoise SVN":http://tortoisesvn.net/ 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.

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.

h3. Android

(Don't take care about this if you downloaded the TADP thing)

For Android build on Windows, there's no such bat file for the moment (sorry). You will have to put the environment variables

yourself. Right click on Computer -> Properties (in file explorer for example) -> System Parameters -> Environment Variables

Then add these entries (into "system 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 add these variables into the PATH one (you can copy pasta the following) :

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

h2. Build needed dependencies

Most of the configure/build process is automated, but there is little manual actions to do.

First either launch cmake-gui from a Visual Studio command line (very important, Visual Studio command line adds environment variables important for a correct configuration) or prepare to run cmake from a command line if you are on Linux (or just a command-line masochist -- as I am but not enough for this huge project).

In cmake-gui, set the sources directory to trunk/dependencies and the build to trunk/dependencies/build/<target OS>/<target platform> and hit the "configure" button. After a moment, there should be lots of red variables on the gui. Don't change anything, hit configure again and finally "generate". Now take your terminal window, go to the build folder and run @nmake install@. If you're not doing the build on an IBM supercluster, you should go take another coffee.

When it's done, come check back on cmake-gui. Now look into "SCOLDEPS" variables and turn on libPng, curl, OpenAL and Ogre. Same as before, build the newly generated project and seriously make us a call if you're doing this with a supercomputer and tell us how Scol's doing on that beast.

Finally, check once again the cmake-gui and tell it to build SkyX, HydraX and CAUDIO. Now it's okay, the dependencies are ready.

h2. Build the projects using CMAKE 

Download and install "CMAKE":http://www.cmake.org/, there is a GUI for windows called "cmake-gui".

Now launch CMAKE and build the project using the sources and build path, for example :

souces : trunk/scol

binaries : trunk/scol/build

Hit the "Configure" button and choose "Visual Studio 10" as project target.

Hit "Configure" again until you don't have red lines anymore.

Then you can hit the "Generate" button.

h2. Build the sources

Open the Scol.sln file generated in the trunk/scol/build

And finally build the project.

The compiled binaries are exported under trunk/scol_sdk/bin/Release or Debug.

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.