Work on README.md

Author: scheibel

README.md

@@ -40,6 +40,7 @@ The cmake-init template assumes you want to setup a project using
   * [Maintainer Modules](#maintainer-modules)
     * [cmake-init Template Check](#cmake-init-template-check)
   * [Development Modules](#development-modules)
+    * [Version Control System Integration](#version-control-system-integration)
     * [Build Targets](#build-targets)
     * [Documentation](#documentation)
     * [Tests](#tests)
@@ -72,18 +73,18 @@ Alternatively, you can update the required modules selectively.
 
 In order to be usable in a deterministic, idiomatic fashion, cmake-init avoids the following approaches and features:
 
-### Super-Build
+## Super-Build
 
 Due to the current semantics of targets and CMake internals, combining multiple
 cmake-init projects into one super-build project is not officially supported.
 There are limited and restricting workarounds.
 Actual solution: treat each project separately and use explicit dependency management.
 
-### High Abstraction
+## High Abstraction
 
 We use low abstractions to not build a language upon CMake a user has to learn.
 
-### File Glob
+## File Glob
 
 Explicit source specification prevents erroneous cases when adding and removing
 sources from the project tree.
@@ -124,8 +125,19 @@ include(GenerateExportHeader)
 include(WriteCompilerDetectionHeader)
 ```
 
+
+### CMake Backward Compatibility
+
 As some modules as `WriteCompilerDetectionHeader` may not be available, cmake-init suggests to use fallbacks and availability detection.
 
+Using this example, the module include
+
+```cmake
+include(WriteCompilerDetectionHeader)
+```
+
+is replaced by
+
 ```cmake
 set(WriterCompilerDetectionHeaderFound NOTFOUND)
 # This module is only available with CMake >=3.1, so check whether it could be found
@@ -135,12 +147,97 @@ if (${CMAKE_VERSION} VERSION_GREATER "3.2")
 endif()
 ```
 
-### CMake Backward Compatibility
+and the result can be later used with
+
+```cmake
+if (WriterCompilerDetectionHeaderFound)
+  # ...
+endif ()
+```
+
+Another issue with older CMake versions is the unavailability of then-unpublished language standards (e.g., C++11 and CMake 3.0). For those versions, the compile options has to be extended manually.
+
+For new projects, we suggest to require at least CMake 3.2 and to therefore adjust the minimum required version:
+
+```cmake
+cmake_minimum_required(VERSION 3.0 FATAL_ERROR)
+```
+
 
 ### Project Meta Information
 
+The declaration of project-wide information--that are used, e.g., within documentation, testing, and deployment--, is combined within the project meta information section in the main `CMakeLists.txt`.
+
+```cmake
+#
+# Project description and (meta) information
+#
+
+# Meta information about the project
+set(META_PROJECT_NAME        "template")
+set(META_PROJECT_DESCRIPTION "CMake Project Template")
+set(META_AUTHOR_ORGANIZATION "CG Internals GmbH")
+set(META_AUTHOR_DOMAIN       "https://github.com/cginternals/cmake-init/")
+set(META_AUTHOR_MAINTAINER   "[email protected]")
+set(META_VERSION_MAJOR       "2")
+set(META_VERSION_MINOR       "0")
+set(META_VERSION_PATCH       "0")
+set(META_VERSION_REVISION    "<REVISION>")
+set(META_VERSION             "${META_VERSION_MAJOR}.${META_VERSION_MINOR}.${META_VERSION_PATCH}")
+set(META_NAME_VERSION        "${META_PROJECT_NAME} v${META_VERSION} (${META_VERSION_REVISION})")
+set(META_CMAKE_INIT_SHA      "<CMAKE_INIT_REVISION>")
+
+string(MAKE_C_IDENTIFIER ${META_PROJECT_NAME} META_PROJECT_ID)
+string(TOUPPER ${META_PROJECT_ID} META_PROJECT_ID)
+```
+
+*cmake-init* supports the projects name, description, organization, domain, and maintainer email as well as detailed version information. For the version, we suggest to use [semantic versioning](https://semver.org/).
+Depending on your version control system, you may want to integrate the current revision of the software as well: see [Version Control System Integration](#version-control-system-integration). If you use the [cmake-init Template Check](#cmake-init-template-check) module, the cmake-init SHA is declared within this section, too.
+
+Last, *cmake-init* derives a project ID that complies with the naming schemes of C to be used within auto-generated and derived source code content (e.g., macro identifiers).
+
+
 ### Project Meta Information Code Generation
 
+The result of this module is the generation of a C header file that propagates the project meta information to your C and C++ projects.
+For this, the CMake file configuration feature is used on the `version.h.in` header template.
+
+```c
+#define ${META_PROJECT_ID}_PROJECT_NAME        "@META_PROJECT_NAME@"
+#define ${META_PROJECT_ID}_PROJECT_DESCRIPTION "@META_PROJECT_DESCRIPTION@"
+
+#define ${META_PROJECT_ID}_AUTHOR_ORGANIZATION "@META_AUTHOR_ORGANIZATION@"
+#define ${META_PROJECT_ID}_AUTHOR_DOMAIN       "@META_AUTHOR_DOMAIN@"
+#define ${META_PROJECT_ID}_AUTHOR_MAINTAINER   "@META_AUTHOR_MAINTAINER@"
+
+#define ${META_PROJECT_ID}_VERSION_MAJOR       "@META_VERSION_MAJOR@"
+#define ${META_PROJECT_ID}_VERSION_MINOR       "@META_VERSION_MINOR@"
+#define ${META_PROJECT_ID}_VERSION_PATCH       "@META_VERSION_PATCH@"
+#define ${META_PROJECT_ID}_VERSION_REVISION    "@META_VERSION_REVISION@"
+
+#define ${META_PROJECT_ID}_VERSION             "@META_VERSION@"
+#define ${META_PROJECT_ID}_NAME_VERSION        "@META_NAME_VERSION@"
+```
+
+The template file is configured with the project meta information and the result is stored within the build directory. Beware that this header is stored in a path derived from your project name. You should adopt this as required.
+
+```cmake
+# Generate version-header
+configure_file(version.h.in ${CMAKE_CURRENT_BINARY_DIR}/include/${META_PROJECT_NAME}/${META_PROJECT_NAME}-version.h)
+```
+
+We suggest to deploy this header disregarding its internal or even public use.
+
+```cmake
+#
+# Deployment
+#
+
+# Deploy generated headers
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/include/${META_PROJECT_NAME} DESTINATION include COMPONENT dev)
+```
+
+
 ### Project Build Options
 
 ## Maintainer Modules
@@ -172,6 +269,17 @@ Correctly configures, this module adds a cmake build target named `check-templat
 
 ## Development Modules
 
+### Version Control System Integration
+
+```cmake
+# Get git revision
+get_git_head_revision(GIT_REFSPEC GIT_SHA1)
+string(SUBSTRING "${GIT_SHA1}" 0 12 GIT_REV)
+if(NOT GIT_SHA1)
+    set(GIT_REV "0")
+endif()
+```
+
 ### Build Targets
 
 ### Documentation