===========================
                        Building the RoSA Framework
                        ===========================

General notes:
-------------

The provided CMake project supports only out-of-tree builds, i.e. one needs to
create a build directory and run CMake in that using the source directory path
as argument.

CMake Variables:
---------------

Beyond the usual CMake variables, the following project-related options are
available:
  * ROSA_INCLUDE_TOOLS, defaults to ON
  * ROSA_INCLUDE_EXAMPLES, defaults to ON
  * ROSA_ENABLE_PEDANTIC, defaults to ON
  * ROSA_ENABLE_ASSERTIONS, defaults to ON only for debug builds, and
                            its value is respected only for non-debug builds
  * ROSA_LOG_LEVEL, defaults to none,
    use a valid integer value to enable logging
  ** 0 - ERROR
  ** 1 - WARNING
  ** 2 - INFO
  ** 3 - DEBUG
  ** 4 - TRACE

Set C and C++ compilers with the variables CC and CXX, respectively. Use the
CMake variable CMAKE_BUILD_TYPE for single-configuration generators to set the
type of build: Debug, Release.

Build on Linux with Make:
------------------------

Building the framework on Linux using Make is a straightforward process which
does not require performing any tricks. The framework compiles with Clang 3.8.0.

Follows an example how to build the framework once having the sources fetched
into a directory called rosa and Clang executables available via your PATH.

rosa$ cd ..
$ mkdir build.rosa
$ cd build.rosa
build.rosa$ CC=clang CXX=clang++ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DROSA_LOG_LEVEL="4" ../rosa/
[CMake configures and generates without errors]
$ make
[Make builds the project]

Build on Windows with Visual Studio:
-----------------------------------

Unfortunately, the native MSVC compiler cannot compile the framework. One needs
to use Clang with Visual Studio in order to build the framework. There are two
alternatives to this:
* using the Clang/C2 module for Visual Studio 2017,
* installing LLVM for Windows and using it as an external toolset for Visual
  Studio (necessary for older versions of Visual Studio).

For using Visual Studio 2017, which would be the preferred way, one needs to
select "Clang/C2 (experimental)" on the "Individual components" tab in Visual
Studio Installer.

For using LLVM for Windows, one downloads the official binary release from
http://llvm.org and consults with its documentation. The release provides
integration for Visual Studio versions between 2010 and 2014 (as of LLVM 4.0.0).

Having your build system prepared and RoSA sources fetched to your computer,
build the framework like this:
* Generate Visual Studio solution with CMake
** Define the source directory and a separate build directory in CMake
** Click Configure
** Select the proper generator for your version of Visual Studio
** Define your optional toolset (argument for -T)
*** Clang/C2 with VS2017: v141_clang_c2
*** LLVM for Windows with older VS: LLVM-vs<year>
** Click Finish
** Tune CMake variables as you will
** Click Generate
* Build the framework with Visual Studio
** Open the generated RoSA.sln from the build directory with Visual Studio
** Build the project ALL_BUILD