Add documentation for using SOCI as a CMake subdirectory

docs/installation.md

@@ -295,7 +295,8 @@ In the example above, regression tests for the sample Empty backend and SQLite 3
 CMake build produces set of shared and static libraries for SOCI core and backends separately.
 On Unix, for example, `build/lib` directory will consist of the static libraries named like `libsoci_core.a`, `libsoci_sqlite3.a` and shared libraries with names like `libsoci_core.so.4.0.0`, `libsoci_sqlite3.so.4.0.0`, and so on.
 
-If your project also uses CMake, you can simply use `find_package(SOCI)` to check for SOCI availability and `target_link_libraries()` to link with the SOCI libraries available under the names `SOCI::soci_core` and `SOCI::soci_<backend>` and ensure that SOCI headers can be included (i.e. there is no need to use `target_include_directories()` explicitly). An example of a very simple CMake-based project using SOCI is provided in the `examples/connect` directory.
+If your project also uses CMake, you can simply use `find_package(SOCI)` to check for SOCI availability and `target_link_libraries()` to link with the SOCI libraries available under the names `SOCI::soci_core` and `SOCI::soci_<backend>` and ensure that SOCI headers can be included (i.e. there is no need to use `target_include_directories()` explicitly). An example of a very simple CMake-based project using SOCI is provided in the `examples/connect` directory. \
+Alternatively, you can add SOCI as a subdirectory to your project and include it via `add_subdirectory()`. As before, `target_link_libraries() ` is used to link with the SOCI libraries available under the names `soci_core` and `soci_<backend>` (note: the alias  `SOCI::` has to be omitted here). In order for SOCI to also find its header files that get generated by CMake, `target_include_directories()` needs to add SOCI's built include directory `${CMAKE_BINARY_DIR/path/to/soci/include}`. An example of this can be found in the directory `examples/subdir-include`.
 
-Otherwise, in order to use SOCI in your program, you need to specify the paths to SOCI headers and libraries in your build configuration and to
+If you don't use CMake but want to use SOCI in your program, you need to specify the paths to the SOCI headers and libraries in your build configuration and to
 tell the linker to link against the libraries you want to use in your program.

examples/subdir-include/CMakeLists.txt

@@ -0,0 +1,29 @@
+# This is a very simple example of using SOCI in a CMake-based project
+# when placing SOCI in a subdirectory lib/soci/ of your project.
+# For this example, the SOCI backend called Empty is used.
+
+cmake_minimum_required(VERSION 2.8 FATAL_ERROR)
+
+project(SOCIExampleSubdirectoryInclude)
+
+# All compile options need to be set before the SOCI directory gets included.
+# The backend you want to use needs to be enabled here.
+option(SOCI_CXX11 "Build to the C++11 standard" ON)
+option(SOCI_EMPTY "Build the sample backend called Empty" ON)
+add_subdirectory(lib/soci)
+
+add_executable(subdir_include subdir-include.cpp)
+
+# SOCI's built include/ directory has to be added to the project explicitly.
+# This is needed so that SOCI can find the file soci/soci-config.h that gets generated by CMake.
+target_include_directories(subdir_include
+    PRIVATE
+        ${CMAKE_BINARY_DIR}/soci/include
+)
+
+# Link the soci_<backend> libraries you want to use here.
+target_link_libraries(subdir_include
+    PRIVATE
+        soci_core
+        soci_empty
+)

examples/subdir-include/lib/soci/README.md

@@ -0,0 +1 @@
+For this example, we assume, that the whole SOCI repository is located in this repository.

examples/subdir-include/subdir-include.cpp

@@ -0,0 +1,44 @@
+#include <soci/soci.h>
+#include <soci/empty/soci-empty.h>
+
+#include <cstdlib>
+#include <iostream>
+#include <stdexcept>
+#include <string>
+
+int main(int argc, char* argv[])
+{
+    if (argc != 2)
+    {
+        std::cerr << "usage: " << argv[0] << " <connection-string>\n";
+        return EXIT_FAILURE;
+    }
+
+    std::string connectString{argv[1]};
+
+    try
+    {
+        soci::session sql(soci::empty, connectString);
+
+        std::cout << "Successfully connected to \"" << connectString << "\", "
+                  << "using \"" << sql.get_backend_name() << "\" backend.\n";
+
+        return EXIT_SUCCESS;
+    }
+    catch (const soci::soci_error& e)
+    {
+        std::cerr << "Connection to \"" << connectString << "\" failed: "
+                  << e.what() << "\n";
+    }
+    catch (const std::runtime_error& e)
+    {
+        std::cerr << "Unexpected standard exception occurred: "
+                  << e.what() << "\n";
+    }
+    catch (...)
+    {
+        std::cerr << "Unexpected unknown exception occurred.\n";
+    }
+
+    return EXIT_FAILURE;
+}