From f116060ff852eebb9fd4865ff939881508cdba34 Mon Sep 17 00:00:00 2001
From: Marco Clemencic <marco.clemencic@cern.ch>
Date: Sun, 22 Dec 2019 17:28:45 +0100
Subject: [PATCH] Updated README

---
 README.md | 35 +++++++++++++++++++++++++++++++----
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 9885916..70638d4 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,35 @@
-These files set the environment for a build on a specific platform
+# LCG Toolchains
 
-Usage (when at the top of the source tree):
+[CMake][] [toolchain files][CMake toolchains] to build a standard CMake project on top of LCG releases.
+
+## Usage
+To enable a toolchain it's enough to add the option `-DCMAKE_TOOLCHAIN_FILE=path/to/the/toolchain.cmake` to the call to `cmake`, e.g.:
 ```
-cmake -S . -B build.<platform> -D CMAKE_TOOLCHAIN_FILE=cmake/toolchains/<version>/<platform>.cmake
+cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=/opt/lcg-toolchains/LCG_96/x86_64-centos7-gcc8-opt.cmake
 ```
 
-NB: you still need to have command like grep and awk in your path
+The toolchain code will create a few helper scripts in the build tree, under the directory `${CMAKE_BINARY_DIR}/toolchain`:
+- wrappers for the compilers
+- generic `wrapper` command
+- lib directory for `pkgconfig` workaround
+
+## Layout
+The toolchain files are organized in one directory per supported LCG version
+plus one directory ([`fragments`](fragments)) with the implementation details.
+
+The LCG version directory contains, for each binary tag, one symlink to a
+CMake fragment common to all platforms ([`fragments/main.cmake`](fragments/main.cmake)). 
+
+The main fragment then delegates to LCG version specific files for the
+configuration of the compiler, with the details in one file per specific version of
+the compiler. Then a file from the directory [`fragments/packages`](fragments/packages)
+is included for the specific settings for the external packages.
+
+The spacial file [`fragments/compilation_flags.cmake`](fragments/compilation_flags.cmake)
+is then included to set the LHCb specific compilation flags (e.g. architecture flags,
+warnings settings, etc.).
+
+The versions of the  
+
+[CMake]: https://cmake.org
+[CMake toolchains]: https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html
-- 
GitLab