From 828aad50faf046869f67aefa5ea99e779d7ed2cc Mon Sep 17 00:00:00 2001
From: vonopr <vonopr@ya.ru>
Date: Fri, 15 Apr 2022 20:32:30 +0300
Subject: [PATCH] Add build instructions to README.md

---
 README.md | 122 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 122 insertions(+)

diff --git a/README.md b/README.md
index dac15a8..c687d01 100644
--- a/README.md
+++ b/README.md
@@ -4,3 +4,125 @@ This project is a stub illustrating how the building of nse-projects
 with CMake is (should be) organized. This one represents *nse-XXX-XXX* 
 (e.g. [nse-sphere3d-geo](http://tesla.parallel.ru/vonopr/nse-sphere3d-geo)) 
 head projects
+
+Throughout the example projects prefix *nse* is substituted with *exple*.
+
+## Dependencies
+
+The project depends on 
+[explelibx-common](http://tesla.parallel.ru/vonopr/explelibx-common) 
+and
+[explelibx-mgrid](http://tesla.parallel.ru/vonopr/explelibx-mgrid) projects.
+
+You must have git, cmake (>= 3.14) and C++ compiler on your system path.
+
+## Download
+
+Download the current project with
+
+```bash
+mkdir exple-cmake-build
+cd exple-cmake-build
+git clone http://tesla.parallel.ru/vonopr/exple-cmake-build.git
+cd ..
+```
+
+### Simple build
+
+After downloading the project build it with
+
+```bash
+mkdir exple-cmake-build/build
+cd exple-cmake-build/build
+cmake -B . -S ../exple-cmake-build
+cmake --build .
+```
+
+CMake should download the dependencies automatically during first invocation and generate
+executable files *exple-add-numbers* or *exple-add-numbers.exe* during build stage.
+Run it with `./exple-add-numbers` on UNIX or with `.\exple-add-numbers.exe` on Windows.
+The output should be
+```Multiplication of sum of 2 and 3 by 4 is... 20```
+
+
+### Build with depndencies local dependencies
+
+If you are a developer you might need a possibility to edit the sources provided by *nselibx-\** projects
+(*explelibx-\** here). This can be done by passing `-DDOWNLOAD_DEPS=OFF` to the CMake configuration command.
+
+Then dependencies should be located in `../..` relative to the local repository of *exple-cmake-build*.
+Thus the directory structure should be
+
+```tree
+.
+├── exple-cmake-build
+│   └── exple-cmake-build
+│       └── exple-cmake-build
+├── explelibx-common
+│   └── explelibx-common
+└── explelibx-mgrid
+    └── explelibx-mgrid
+```
+
+
+You can first [download the current project](#download) and then
+download dependencies and configure cmake with `-DDOWNLOAD_DEPS=OFF` 
+
+```bash
+git clone http://tesla.parallel.ru/vonopr/explelibx-common.git
+git clone http://tesla.parallel.ru/vonopr/explelibx-mgrid.git
+mkdir build
+cd build
+cmake -B . -S ../exple-cmake-build/exple-cmake-build -DDOWNLOAD_DEPS=OFF
+cmake --build .
+```
+
+During cmake configuration simillar messages should appear
+
+```
+-- Path to 'explelibx-common' project
+    COMMON_DIR: D:/nse/example-structures/explelibx-common
+-- Path to 'explelibx-mgrid' project
+    GRID_DIR: D:/nse/example-structures/explelibx-mgrid
+```
+
+### Custom paths to dependencies
+
+Otherwise, you can change the default paths with cmake's *COMMON_DIR* and
+*GRID_DIR* variables. Works only if download is disables, i.e. *DOWNLOAD_DEPS=OFF*
+
+E.g. if you want to build the sources' directory structure as follows
+
+```tree
+.
+├── exple-cmake-build
+│   └── exple-cmake-build
+│       └── exple-cmake-build
+├── explelibx-common
+│   └── explelibx-common
+└── explelibx-mgrid
+    └── explelibx-mgrid
+```
+
+do
+
+```bash
+git clone http://tesla.parallel.ru/vonopr/exple-cmake-build.git
+git clone http://tesla.parallel.ru/vonopr/explelibx-common.git
+git clone http://tesla.parallel.ru/vonopr/explelibx-mgrid.git
+mkdir build
+cd build
+cmake -B . -S ../exple-cmake-build -DDOWNLOAD_DEPS=OFF -DCOMMON_DIR=../explelibx-common -DGRID_DIR=../explelibx-mgrid 
+```
+
+(This time [the initial download step](#download) should be skipped)
+
+### Notes on building on Windows
+
+C++ compiler and cmake's default building generator may be incompatible. If so you should provide the appropriate
+generator with `-G` option. Visual Studio C++ Compiler should be used with `Visual Studio 17 2022`-like generators,
+Intel C++ Compiler should be used with `NMake Makefiles`, MinGW C++ should be used `MinGW Makefiles`:
+
+```
+cmake -B . -S ../exple-cmake-build -G"Visual Studio 17 2022"
+```
-- 
GitLab