Initial import of documentation

docs/BuildSystem.rst

@@ -0,0 +1,83 @@
+***********************************
+Identifying the required components
+***********************************
+
+`revamb` requires three main components: LLVM, QEMU and one or more GCC
+toolchains.
+
+LLVM
+====
+
+LLVM should be automatically detected if it's a standard location. If you want
+to use a custom build in a non-standard location use the ``LLVM_DIR`` option,
+making it point to the directory containing ``LLVMConfig.cmake`` in the install
+directory (typically ``$INSTALL_PATH/share/llvm/cmake``):
+
+.. code-block:: sh
+
+    cmake -DLLVM_DIR=/home/me/llvm-install/share/llvm/cmake ../
+
+QEMU
+====
+
+By default the build system will look for the system QEMU installation (i.e., in
+``/usr/``). If this is not what you want you can customize the QEMU install path
+using the ``QEMU_INSTALL_PATH`` variable:
+
+.. code-block:: sh
+
+    cmake -DQEMU_INSTALL_PATH="/home/me/qemu-install/" ../
+
+GCC
+===
+
+The `revamb` build system will try to automatically detect toolchains to compile
+code for the supported architectures. The toolchains are required to correctly
+run the `revamb` test suite.
+
+The autodetction mechanism looks in all the directories in the ``PATH``
+environment variable for an executable matching the pattern ``$ARCH*-musl*-gcc``
+or ``$ARCH*-uclibc*-gcc`` (glibc is currently unsupported).
+
+It's possible to force the usage of a specific compiler for a certain
+architecture using the CMake variable ``C_COMPILER_$ARCH``:
+
+.. code-block:: sh
+
+    cmake -DC_COMPILER_mips="/home/me/my-mips-compiler" \
+          -DC_COMPILER_miparm="/home/me/my-arm-compiler" \
+          -DC_COMPILER_x86_64="/home/me/my-x86_64-compiler" \
+          ../
+
+The `revamb` build system also provides an option to specify additional flags to
+employ when using the above mentioned commpilers for compilation and linking of
+test binaries. This can be done using the variables ``TEST_CFLAGS_$ARCH`` (for
+compile-time flags) and ``TEST_LINK_LIBRARIES_$ARCH`` (for linking).
+
+This is particularly useful to force x86-64 binaries to compile with software
+floating point, which can be achieved with GCC as follows:
+
+.. code-block:: sh
+
+    cmake -DTEST_CFLAGS_x86_64="-msoft-float -mfpmath=387 -mlong-double-64" \
+          -DTEST_LINK_LIBRARIES_x86_64="-lc $LLVM_INSTALL_PATH/lib/linux/libclang_rt.builtins-x86_64.a" \
+          ../
+
+********************
+Common CMake options
+********************
+
+In the following we provide some useful-to-know CMake variables, that are not
+specific to `revamb`. They can be specified using the ``-D`` flag, e.g.:
+
+.. code-block:: sh
+
+    cmake -DCMAKE_INSTALL_PREFIX=/tmp ../
+
+:CMAKE_INSTALL_PREFIX: Specify the install path. This is the destination
+                       directory where all the necessary files will be copied
+                       upon ``make install``.
+:CMAKE_BUILD_TYPE: Specify the type of build. The two most useful values are
+                   ``Debug``, for an unoptimized build with debugging
+                   information, and ``RelWithdebinfo``, for an optimized build
+                   with debugging information.