diff --git a/README.build.txt b/README.build.txt new file mode 100644 index 0000000..9befebd --- /dev/null +++ b/README.build.txt @@ -0,0 +1,84 @@ + =========================== + 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 +** 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 + diff --git a/README.txt b/README.txt index 0c4f9fd..909511a 100644 --- a/README.txt +++ b/README.txt @@ -1,61 +1,44 @@ ==================================== Research on Self-Awareness Framework ==================================== +Build Dependencies: +------------------ + +* CMake (minimum version 2.8.8) +* Build system of your choice with a standard C++ compiler (targeted by CMake) + +Runtime Dependencies: +-------------------- + +Nothing yet :) + Build: ----- -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. - -Prerequisites: -------------- - -Nothing yet. - -Build options: -------------- - -Beyond the usual CMake options, 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 environment variables CC and CXX, -respectively. Use the CMake variable CMAKE_BUILD_TYPE for single-configuration -generators to set the type of build: Debug, Release. +The framework is delivered with a CMake project, which can be used to generate +build projects to build the framework. Consult README.build for details. Using YCM: --------- If you happen to use YMC, just make a copy of the provided ycm_extra_conf.py.template file as .ycm_extra_conf.py in the project directory, and set the following two variables in it: * compilation_database_folder: the absolute path of your build directory * extra_system_include_dirs: any system include directory which might not be search by libclang. See: https://github.com/Valloric/YouCompleteMe/issues/303; use the following command to figure out the used system directories: 'echo | clang -std=c++11 -v -E -x c++ -'. You probably want compile with clang if you use YCM, so run cmake with environment variables CC=clang and CXX=clang++ set. -Also note that headers file in the include directory are compiled for YCM with +Also note that header files in the include directory are compiled for YCM with the compiler flags of a corresponding source file in the lib directory, if any. Header files in other locations are supposed to have a corresponding source file in the same directory. If the project's include directory (include/rosa) would be ever changed, then that needs to be also modified in the YCM configuration file.