Add guidelines for compilation, installation and linking.

README.md

@@ -25,18 +25,68 @@ extracted from [AFF3CT](https://github.com/aff3ct/aff3ct). Now that it is no
 longer specific to channel coding and digital communications, the project has 
 been renamed to `StreamPU`, which is a more meaningful name.
 
-## Linking with the Library
+## Library Compilation & Installation
+
+This project uses CMake as the main build system and it provides the following
+CMake options:
+- `SPU_COMPILE_STATIC_LIB`: Compile the static library (default = `ON`)
+- `SPU_COMPILE_SHARED_LIB`: Compile the shared library (default = `OFF`)
+- `SPU_LINK_HWLOC`: Link with the `hwloc` library (used for threads pinning) 
+  (default = `OFF`)
+- `SPU_COLORS`: Enable the colors in the terminal (default = `ON`)
+- `SPU_TESTS`: Enable the compilation of the tests (default = `ON`)
+- `SPU_STACKTRACE`: Print the stack trace when an exception is raised (and link 
+  with the `cpptrace` lib) (default = `ON`)
+- `SPU_STACKTRACE_SEGFAULT`: Try to print the stack trace when a segfault occurs 
+  (and link with the `cpptrace` lib) (default = `OFF`)
+- `SPU_SHOW_DEPRECATED`: Print message each time a deprecated function is called 
+  (default = `OFF`)
+- `SPU_FAST`: Remove checks to speedup the code (default = `OFF`)
+
+Build the library in `debug` mode:
+```bash
+mkdir build_debug
+cd build_debug
+cmake ..
+make -j4
+ctest
+```
+
+Build the library in `release` mode:
+```bash
+mkdir build_release
+cd build_release
+cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_CXX_FLAGS="-Wall -march=native -funroll-loops"
+make -j4
+ctest
+```
+
+Install the library on the system (`/usr/local`):
+```bash
+cmake --install .
+```
+
+Install the library in a custom path (`/opt/streampu`):
+```bash
+cmake --install . --prefix /opt/streampu/
+```
+
+## Link with the Library
 
 `StreamPU` exposes two CMake targets:
-- `spu-shared-lib`: `StreamPU` shared library, includes and definitions
-- `spu-static-lib`: `StreamPU` static library, includes and definitions
+- `spu::spu-static-lib`: `StreamPU` static library, includes and definitions 
+  (compiled by default)
+- `spu::spu-shared-lib`: `StreamPU` shared library, includes and definitions
 
-For now, the recommended way to use `StreamPU` is to add it as a 
-`add_subdirectory` into your `CMakeList.txt` file. 
+It is possible to link with `StreamPU` from a sub-directory or from an installed
+library. Both methods are described in the next sections.
 
-Let us suppose that we want to produce the `my-exe` executable that links with 
-`StreamPU` static library, here is a minimal `CMakeLists.txt` file to 
-generate the `my-exe` executable:
+### From a Sub-directory
+
+Let us suppose that we want to produce the `my-exe` executable that will links 
+with `StreamPU` and that the `StreamPU` repository is located at 
+`my-exe-root/lib/streampu/`. Here is a minimal `CMakeLists.txt` file to 
+generate it:
 
 ```cmake
 cmake_minimum_required(VERSION 3.5)
@@ -50,15 +100,57 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 # create the `my-exe` executable from `src/main.cpp` --------------------------
 add_executable(my-exe ${CMAKE_CURRENT_SOURCE_DIR}/src/main.cpp)
 
-# compile `StreamPU` static lib --------------------------------------------
-option(SPU_COMPILE_STATIC_LIB "" ON) # compile the static lib
-option(SPU_COMPILE_SHARED_LIB "" OFF) # do NOT compile the shared lib
+# compile `StreamPU` static lib -----------------------------------------------
 option(SPU_TESTS "" OFF) # do NOT compile the tests
-# here we suppose that `StreamPU` sources are located in `lib/streampu/`
 add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/lib/streampu/)
 
-# `my-exe` links with `StreamPU` static lib --------------------------------
-target_link_libraries(my-exe PUBLIC spu-static-lib)
+# `my-exe` links with `StreamPU` static lib -----------------------------------
+target_link_libraries(my-exe PUBLIC spu::spu-static-lib)
+
+# `my-exe` links with `cpptrace` (`SPU_STACKTRACE=ON`) ------------------------
+if(SPU_STACKTRACE OR SPU_STACKTRACE_SEGFAULT)
+  target_link_libraries(my-exe PUBLIC cpptrace::cpptrace)
+endif()
+```
+
+### From an Installed Library
+
+Let us suppose that we want to produce the `my-exe` executable that links with 
+`StreamPU` static library installed on the system. Here is a minimal 
+`CMakeLists.txt` file to generate it:
+
+```cmake
+cmake_minimum_required(VERSION 3.5)
+
+project(my_project CXX)
+
+# require C++11 compiler ------------------------------------------------------
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# create the `my-exe` executable from `src/main.cpp` --------------------------
+add_executable(my-exe ${CMAKE_CURRENT_SOURCE_DIR}/src/main.cpp)
+
+# find and link with `cpptrace` if installed (if not, don't) ------------------
+find_package(cpptrace CONFIG 0.4.1)
+if (cpptrace_FOUND)
+  target_link_libraries(my-exe PUBLIC cpptrace::cpptrace)
+endif()
+
+# find and link with `StreamPU` -----------------------------------------------
+find_package(StreamPU CONFIG 0.1.0 REQUIRED)
+target_link_libraries(my-exe PUBLIC spu::spu-static-lib)
+```
+
+If `StreamPU` is installed in a specific location (for instance: 
+`/opt/streampu`), you can help CMake to find it as follow:
+```bash
+cmake .. -DStreamPU_DIR=/opt/streampu/lib/cmake/streampu
+```
+
+Or, if StreamPU has been compiled with the `cpptrace` library:
+```bash
+cmake .. -DStreamPU_DIR=/opt/streampu/lib/cmake/streampu -Dcpptrace_DIR=/opt/streampu/lib/cmake/cpptrace
 ```
 
 ## Documentation
@@ -76,7 +168,7 @@ target_link_libraries(my-exe PUBLIC spu-static-lib)
 
 The project is licensed under the MIT license.
 
-## How to cite StreamPU
+## How to cite `StreamPU`
 
 The main contributions of this work are described in the following journal 
 article: