From 87db22f1349c96abae4c0d308a6de052a28cad4c Mon Sep 17 00:00:00 2001 From: Duncan Ogilvie Date: Sat, 28 Aug 2021 13:41:51 +0200 Subject: [PATCH] Add documentation for the cmake.toml format --- docs/.gitignore | 2 +- docs/Gemfile | 2 + docs/Gemfile.lock | 4 +- docs/cmake-toml.md | 170 ++++++++++++++++++++++++++++++++++++++++ docs/command-line.md | 2 +- docs/getting-started.md | 2 +- 6 files changed, 178 insertions(+), 4 deletions(-) create mode 100644 docs/cmake-toml.md diff --git a/docs/.gitignore b/docs/.gitignore index 377c423..75100cf 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,2 +1,2 @@ _site/ -.jekyll-metadata \ No newline at end of file +.jekyll-metadata diff --git a/docs/Gemfile b/docs/Gemfile index 95cc7ed..cc1531a 100644 --- a/docs/Gemfile +++ b/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" diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 1e20c2c..2529757 100644 --- a/docs/Gemfile.lock +++ b/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 diff --git a/docs/cmake-toml.md b/docs/cmake-toml.md new file mode 100644 index 0000000..71b5494 --- /dev/null +++ b/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 = "$" +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 = [""] +``` \ No newline at end of file diff --git a/docs/command-line.md b/docs/command-line.md index 0d8512d..a227225 100644 --- a/docs/command-line.md +++ b/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: diff --git a/docs/getting-started.md b/docs/getting-started.md index e4c9466..5e3a9c1 100644 --- a/docs/getting-started.md +++ b/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: