save

Author: jcbhmr

.devcontainer/devcontainer.json

@@ -0,0 +1,4 @@
+{
+    "image": "mcr.microsoft.com/devcontainers/cpp",
+    "updateContentCommand": "cargo install mdbook mdbook-cmdrun"
+}

.devcontainer/hello-world/devcontainer.json

@@ -0,0 +1,5 @@
+{
+    "name": "Hello world",
+    "image": "mcr.microsoft.com/devcontainers/cpp",
+    "workspaceFolder": "${localWorkspaceFolder}/src/hello-world"
+}

README.md

@@ -8,3 +8,19 @@
 ![CMake](https://img.shields.io/static/v1?style=for-the-badge&message=CMake&color=064F8C&logo=CMake&logoColor=FFFFFF&label=)
 
 Make sure you've installed [mdBook](https://rust-lang.github.io/mdBook/guide/installation.html) and [CMake](https://cmake.org/download/). You'll also need to install [mdbook-cmdrun](https://github.com/FauconFan/mdbook-cmdrun). Run `mdbook serve` to see the live preview.
+
+The custom `theme/highlight.js` is needed because the default mdBook `highlight.js` doesn't include the `cmake` language. The current custom build includes [all of the mdBook defaults](https://rust-lang.github.io/mdBook/format/theme/syntax-highlighting.html#supported-languages) plus `cmake`. Generate it using https://highlightjs.org/download and use the `./highlight.min.js` file from the resulting `.zip` download.
+
+To create a new example:
+
+1. Come up with a slug like `cool-feature`.
+2. Add it to `src/SUMMARY.md` like `- [Cool feature](cool-feature/index.md)`.
+3. Create a new folder to hold the example like `src/cool-feature`.
+4. Add a `README.md` to the new folder.
+5. Create your example. Take note of any dependencies it needs (Clang, clang-format, Vcpkg, Conan, etc.).
+6. Add a lot of comments to your code files to explain what's going on. The `README.md` is for shell commands. The code files are for other prose.
+7. `{{#include filename.txt}}` any relevant files in the `src/cool-feature/README.md` inside `` ``` `` code blocks.
+8. Add any shell commands to interact with the example to the `src/cool-feature/README.md`. Make sure to document them.
+9. (Optional) Use `<!-- cmdrun cmake ... -->` or similar inside a `` ``` `` code block to run that command and use its output at build time.
+10. Create a corresponding `.devcontainer/cool-feature/devcontainer.json` that will open the example's folder. Add any necessary dependencies to the dev container.
+11. Add an "Open in Codespaces" button to the `src/cool-feature/README.md`.

src/README.md

@@ -0,0 +1,8 @@
+# CMake by Example
+
+CMake is an open source cross-platform meta build system that works on Windows, macOS, Linux, and more. It is designed to bridge the gap between the platform-specific build tools such as Ninja, GNU Make, BSD Make, Visual Studio, and Xcode. You can read more about CMake on the [official CMake.org website](https://cmake.org/). CMake is best known for its unmatched popularity as the primary C/C++ build tool.
+
+*CMake by Example* is a hands-on introduction to how to use CMake to build C/C++ projects using annotated example projects. Make sure you have [installed the latest version of CMake on your system](https://cmake.org/download/). Check out the first [Hello world](hello-world.md) example to get started.
+
+<!-- This works because our `SUMMARY.md` just so happens to match the format that we need here. -->
+{{#include SUMMARY.md:7:}}

src/SUMMARY.md

@@ -1,11 +1,12 @@
 # Summary
 
-[CMake by Example](index.md)
+[CMake by Example](README.md)
 
 ---
 
-- [Hello world](hello-world.md)
-- [Values](values.md)
+- [Hello world](hello-world/README.md)
+- [Logging](logging/README.md)
+- [Values](values/README.md)
 - [Variables]()
 - [Executables]()
 - [Libraries]()
@@ -29,7 +30,6 @@
 - [HTTP requests]()
 - [String functions]()
 - [JSON]()
-- [Logging]()
 - [Environment variables]()
 - [Feature detection]()
 - [clang-format]()

src/hello-world.md

@@ -0,0 +1,5 @@
+{
+    "name": "Hello world 2",
+    "image": "mcr.microsoft.com/devcontainers/cpp",
+    "workspaceFolder": "${localWorkspaceFolder}/src/hello-world"
+}

src/hello-world/.devcontainer.json

@@ -1,5 +1,27 @@
+# First we require a minimum version of CMake. It's a good idea to choose
+# something recent. You can find the latest version on the CMake website
+# https://cmake.org/download/. This function is HIGHLY RECOMMENDED. It should be
+# before even the project() function.
 cmake_minimum_required(VERSION 3.30)
 
+# Next we define a project. Think of a project as similar to a Python package, a
+# JavaScript package, a Rust package, etc. This project() function call will
+# define all subsequent targets (executables, libraries, etc.) in the scope of
+# this project. You may specify more than just a project name:
+#
+#     project(<PROJECT-NAME>
+#       [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
+#       [DESCRIPTION <project-description-string>]
+#       [HOMEPAGE_URL <url-string>]
+#       [LANGUAGES <language-name>...])
 project(hello-world)
 
-add_executable(hello-world main.c)
+# Finally, we add an executable target. This will create an executable named
+# hello-world from the source file main.c. You are able to specify more than one
+# source file if you wish:
+#
+#     add_executable(<name> <options>... <sources>...)
+#
+# For example: add_executable(hello-world main.c other.c). For now we only need
+# one main.c file.
+add_executable(hello-world main.c)

src/hello-world/CMakeLists.txt

@@ -0,0 +1,41 @@
+# Hello world
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/jcbhmr/cmakebyexample.jcbhmr.com?quickstart=1&devcontainer_path=src%2Fhello-world%2F.devcontainer.json)
+
+```c
+{{#include main.c}}
+```
+
+```cmake
+{{#include CMakeLists.txt}}
+```
+
+CMake isn't actually a build system itself. It's a meta build system. CMake takes your imperative build instructions from the CMakeLists.txt script and generates the complicated structure that each platform-specific build tool requires. For example, GNU Makefiles on Linux, Xcode projects on macOS, and Visual Studio solutions on Windows. This is called "configuring". You can perform the configure step by running `cmake`. **But** by default that creates a lot of files in the current working directory. That gets messy with complicated `.gitignore` patterns and such. It's much easier to perform an *out of source build* where we tell CMake to put those files in another folder like `./build/` instead of `./`. That's where the `-B build` flag comes in.
+
+```sh
+cmake -B ./build/
+```
+
+```
+<!-- cmdrun cmake -B ./build/ -->
+```
+
+Now that we've generated the platform-specific build system files in `./build/`, we can tell CMake to invoke `make`, `msbuild`, `ninja`, or another build command in that directory to finally build our project. This stage is aptly called "building". You can perform the build step by running `cmake --build <configure_output_folder>` where `<configure_output_folder>` is the folder you specified with the `-B` flag. In our case, that's `./build/`.
+
+```sh
+cmake --build ./build/
+```
+
+```
+<!-- cmdrun cmake --build ./build/ -->
+```
+
+And finally we can run the executable that was built in `./build/`. The executable is named `hello-world` because that's the target name we specified in the `add_executable()` function in `CMakeLists.txt`.
+
+```sh
+./build/hello-world
+```
+
+```
+<!-- cmdrun ./build/hello-world -->
+```

src/hello-world/README.md

@@ -1,12 +1,12 @@
+// You can compile and run this program directly without CMake using a C
+// compiler manually. Here's how you might do so with GCC:
+// 
+//   gcc -o hello-world main.c
+//   ./hello-world
+
 #include <stdio.h>
 
 int main() {
     puts("Hello, World!");
     return 0;
 }
-
-// You can compile and run this program directly without CMake using a C
-// compiler manually. Here's how you might do so with GCC:
-// 
-//   gcc -o hello-world main.c
-//   ./hello-world