Add documentation for the cmake.toml format

Author: mrexodia

docs/.gitignore

@@ -1,2 +1,2 @@
 _site/
-.jekyll-metadata
+.jekyll-metadata

docs/Gemfile

@@ -11,3 +11,5 @@ end
 
 gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
 gem "just-the-docs"
+
+gem "webrick", "~> 1.7"

docs/Gemfile.lock

@@ -262,6 +262,7 @@ GEM
       unf_ext
     unf_ext (0.0.7.7)
     unicode-display_width (1.7.0)
+    webrick (1.7.0)
     zeitwerk (2.4.2)
 
 PLATFORMS
@@ -275,6 +276,7 @@ DEPENDENCIES
   tzinfo (~> 1.2)
   tzinfo-data
   wdm (~> 0.1.1)
+  webrick (~> 1.7)
 
 BUNDLED WITH
-   2.1.2
+   2.2.26

docs/cmake-toml.md

@@ -0,0 +1,170 @@
+---
+layout: page
+title: cmake.toml
+permalink: /cmake-toml/
+nav_order: 3
+---
+
+# cmake.toml
+
+This page is supposed to be a reference for the options in the `cmake.toml` file. If you think anything is missing or unclear, please [edit this page](https://github.com/build-cpp/cmkr/edit/main/docs/cmake-toml.md) or open an [issue](https://github.com/build-cpp/cmkr/issues).
+
+See the [examples](/examples) section for more real-world examples.
+
+## CMake configuration
+
+```toml
+[cmake]
+version = "3.15"
+cmkr-include = "cmkr.cmake"
+```
+
+## Project configuration
+
+```toml
+[project]
+name = "myproject"
+version = "1.0.0"
+description = "Description of the project"
+languages = ["C", "CXX"]
+cmake-before = """
+message(STATUS "CMake injected before the project() call")
+"""
+cmake-after = """
+message(STATUS "CMake injected after the project() call")
+"""
+include-before = ["cmake/before-project.cmake"]
+include-after = ["cmake/after-project.cmake"]
+```
+
+## Conditions
+
+```toml
+[conditions]
+arch64 = "CMAKE_SIZEOF_VOID_P EQUALS 8"
+arch32 = "CMAKE_SIZEOF_VOID_P EQUALS 4"
+```
+
+## Subdirectories
+
+```toml
+[subdir.mysubdir]
+condition = "linux"
+cmake-before = """
+message(STATUS "CMake injected before the add_subdirectory() call"
+"""
+cmake-after = """
+message(STATUS "CMake injected after the add_subdirectory() call")
+"""
+include-before = ["cmake/before-subdir.cmake"]
+include-after = ["cmake/after-subdir.cmake"]
+```
+
+## Vcpkg
+
+```toml
+[vcpkg]
+version = "2021.05.12"
+url = "https://github.com/microsoft/vcpkg/archive/refs/tags/2021.05.12.tar.gz"
+packages = ["fmt", "zlib"]
+```
+
+The vcpkg `version` will automatically generate the `url` from the official repository. For a custom registry you can specify your own `url` (and omit the `version`).
+
+## Packages
+
+```toml
+[find-package]
+mypackage = { version = "1.0", required = true, config = true, components = ["mycomponent"] }
+
+# Alternative syntax
+[find-package.mypackage]
+version = "1.0"
+required = true
+config = true
+components = ["mycomponent"]
+```
+
+## FetchContent
+
+**Note**: The `[fetch-content]` feature is unpolished and will likely change in a future release.
+
+```toml
+[fetch-content]
+gitcontent = { git = "https://github.com/myuser/gitcontent", tag = "v0.1" }
+svncontent = { svn = "https://svn-host.com/url", rev = "svn_rev" }
+urlcontent = { url = "https://content-host.com/urlcontent.zip", hash = "123123123123" }
+
+# Alternative syntax
+[fetch-content.gitcontent]
+git = "https://github.com/myuser/gitcontent"
+tag = "v0.1"
+```
+
+## Targets
+
+```toml
+[target.mytarget]
+condition = "linux"
+alias = "mytarget::mytarget"
+type = "static" # executable, library, shared, static, interface, custom
+headers = ["src/mytarget.h"]
+sources = ["src/mytarget.cpp"]
+
+# The keys below match the target_xxx CMake commands
+# Keys prefixed with private- will get PRIVATE visibility
+compile-definitions = [""]
+private-compile-definitions = [""]
+compile-features = [""]
+private-compile-features = [""]
+compile-options = [""]
+private-compile-options = [""]
+include-directories = [""]
+private-include-directories = [""]
+link-directories = [""]
+private-link-directories = [""]
+link-libraries = [""]
+private-link-libraries = [""]
+link-options = [""]
+private-link-options = [""]
+precompile-headers = [""]
+private-precompile-headers = [""]
+
+cmake-before = """
+message(STATUS "CMake injected before the target")
+"""
+cmake-after = """
+message(STATUS "CMake injected after the target")
+"""
+include-before = "cmake/target-before.cmake"
+include-after = "cmake/target-after.cmake"
+
+# See https://cmake.org/cmake/help/latest/manual/cmake-properties.7.html#properties-on-targets for a list of target properties
+[target.mytarget.properties]
+CXX_STANDARD = 17
+CXX_STANDARD_REQUIRED = true
+FOLDER = "MyFolder"
+```
+
+## Tests and installation (unfinished)
+
+**Note**: The `[[test]]` and `[[install]]` are unfinished features and will likely change in a future release.
+
+```toml
+# You can declare as many as you want like this, but the name has to be unique
+[[test]]
+name = "mytest"
+command = "$<TARGET_FILE:mytest>"
+arguments = ["arg1", "arg2"]
+configurations = ["Debug", "Release", "RelWithDebInfo", "MinSizeRelease"]
+working-directory = "mytest-dir"
+```
+
+```toml
+[[install]]
+targets = ["mytarget", "mytest"]
+destination = ["bin"]
+files = ["content/my.png"]
+dirs = [""]
+configs = [""]
+```

docs/command-line.md

@@ -5,7 +5,7 @@ permalink: /command-line/
 nav_order: 2
 ---
 
-## Command line
+# Command line
 
 Optionally you can install `cmkr` in your `PATH` and use it as a utility from the command line:
 

docs/getting-started.md

@@ -5,7 +5,7 @@ permalink: /getting-started/
 nav_order: 1
 ---
 
-## Getting started
+# Getting started
 
 The easiest way to get started is to use the [cmkr_for_beginners](https://github.com/build-cpp/cmkr_for_beginners) template repository. Either open it in [Gitpod](https://gitpod.io/#https://github.com/build-cpp/cmkr_for_beginners), or clone the repository and run: