save

jcbhmr · web-flow · commit 6ece892da888 · 2025-01-07T23:00:17.000Z
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -1,4 +1,17 @@
 {
-    "image": "mcr.microsoft.com/devcontainers/cpp",
-    "updateContentCommand": "cargo install mdbook mdbook-cmdrun"
+    "image": "mcr.microsoft.com/devcontainers/cpp:ubuntu",
+    "features": {
+        "ghcr.io/devcontainers/features/rust": {},
+        "ghcr.io/devcontainers/features/python": {}
+    },
+    "updateContentCommand": "./.devcontainer/updateContentCommand.sh",
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "dnut.rewrap-revived",
+                "xaver.clang-format",
+                "twxs.cmake"
+            ]
+        }
+    }
 }
diff --git a/.devcontainer/hello-world/devcontainer.json b/.devcontainer/hello-world/devcontainer.json
@@ -1,5 +1,6 @@
 {
-    "name": "Hello world",
-    "image": "mcr.microsoft.com/devcontainers/cpp",
-    "workspaceFolder": "${localWorkspaceFolder}/src/hello-world"
+    "image": "mcr.microsoft.com/devcontainers/cpp:ubuntu",
+    "workspaceMount": "source=${localWorkspaceFolder}/src/hello-world,target=/workspace,type=bind,consistency=cached",
+    "workspaceFolder": "/workspaces/hello-world",
+    "updateContentCommand": "curl -fsSL https://apt.kitware.com/kitware-archive.sh | sh"
 }
diff --git a/.devcontainer/logging/devcontainer.json b/.devcontainer/logging/devcontainer.json
@@ -0,0 +1,6 @@
+{
+    "image": "mcr.microsoft.com/devcontainers/cpp:ubuntu",
+    "workspaceMount": "source=${localWorkspaceFolder}/src/logging,target=/workspace,type=bind,consistency=cached",
+    "workspaceFolder": "/workspaces/logging",
+    "updateContentCommand": "curl -fsSL https://apt.kitware.com/kitware-archive.sh | sh"
+}
diff --git a/.devcontainer/updateContentCommand.sh b/.devcontainer/updateContentCommand.sh
@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -ex
+
+(
+    cd "$(mktemp -d)"
+    wget https://apt.kitware.com/kitware-archive.sh
+    chmod +x ./kitware-archive.sh
+    ./kitware-archive.sh
+    rm -rf "$PWD"
+)
+sudo apt-get install -y cmake
+
+cargo install mdbook
+cargo install mdbook-cmdrun mdbook-codename
+
+(
+    cd ~
+    mkdir -p cosmocc
+    cd cosmocc
+    wget https://cosmo.zip/pub/cosmocc/cosmocc.zip
+    unzip cosmocc.zip
+    rm cosmocc.zip
+)
+
+curl -sS https://webi.sh/zig | sh
+source ~/.config/envman/PATH.env
+
+sudo apt-get update
+sudo apt-get install -y clang-format
+
+pipx install cmakelang
diff --git a/.github/workflows/mdbook.yml b/.github/workflows/mdbook.yml
@@ -33,10 +33,11 @@ jobs:
 
       - name: Setup mdBook
         uses: peaceiris/actions-mdbook@v2
-      # https://github.com/FauconFan/mdbook-cmdrun
-      - run: cargo install mdbook-cmdrun
+      - run: cargo install mdbook-cmdrun mdbook-codename
       # Included CMake version is OK.
       # Included GCC version is OK.
+      - uses: bjia56/setup-cosmocc@main
+      - uses: mlugg/setup-zig@v1
 
       - name: Setup Pages
         id: pages
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -0,0 +1,7 @@
+{
+    "recommendations": [
+        "dnut.rewrap-revived",
+        "xaver.clang-format",
+        "twxs.cmake"
+    ]
+}
diff --git a/README.md b/README.md
@@ -7,9 +7,17 @@
 ![mdBook](https://img.shields.io/static/v1?style=for-the-badge&message=mdBook&color=000000&logo=mdBook&logoColor=FFFFFF&label=)
 ![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.
+Make sure you've installed:
 
-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.
+- [CMake](https://cmake.org/download/)
+- [mdBook](https://rust-lang.github.io/mdBook/)
+- [mdbook-cmdrun](https://github.com/FauconFan/mdbook-cmdrun)
+- [mdbook-codename](https://github.com/smallkirby/mdbook-codename)
+- clang-format
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/jcbhmr/cmakebyexample.jcbhmr.com?quickstart=1&devcontainer_path=.devcontainer%2Fdevcontainer.json)
+
+The custom `theme/highlight.js` is needed because the default mdBook `highlight.js` doesn't include the some languages. To regenerate a custom build of `theme/highlight.js` use `./task.cmake generate`.
 
 To create a new example ("Cool feature" in this example):
 
diff --git a/book.toml b/book.toml
@@ -11,3 +11,6 @@ edit-url-template = "https://github.com/jcbhmr/cmakebyexample.jcbhmr.com/edit/ma
 
 # https://github.com/FauconFan/mdbook-cmdrun
 [preprocessor.cmdrun]
+
+# https://github.com/smallkirby/mdbook-codename
+[preprocessor.codename]
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -16,16 +16,18 @@
 - [Arrays]()
 - [Functions]()
 - [Macros]()
+- [Set C/C++ standard]()
 - [Toolchain files]()
 - [Custom targets]()
 - [Post-build commands]()
 - [FetchContent dependency]()
+- [FindPackage dependency]()
 - [Conan dependency]()
 - [Vcpkg dependency]()
 - [Xrepo dependency]()
-- [FindPackage dependency]()
-- [cosmocc toolchain]()
-- [Zig toolchain]()
+- [Testing-only dependencies]()
+- [cosmocc toolchain](cosmocc-toolchain/README.md)
+- [Zig toolchain](zig-toolchain/README.md)
 - [Spawning processes]()
 - [HTTP requests]()
 - [String functions]()
@@ -43,4 +45,4 @@
 - [Packaging]()
 - [Release GitHub Actions]()
 - [Install target]()
-- [Scripts]()
+- [Scripts](scripts/README.md)
diff --git a/src/cosmocc-toolchain/CMakeLists.txt b/src/cosmocc-toolchain/CMakeLists.txt
@@ -0,0 +1,5 @@
+cmake_minimum_required(VERSION 3.30)
+
+project(cosmocc-toolchain)
+
+add_executable(cosmocc-toolchain main.c)
diff --git a/src/cosmocc-toolchain/README.md b/src/cosmocc-toolchain/README.md
@@ -0,0 +1,39 @@
+# cosmocc toolchain
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/jcbhmr/cmakebyexample.jcbhmr.com?quickstart=1&devcontainer_path=.devcontainer%2Fcosmocc-toolchain%2Fdevcontainer.json)
+
+```cmake:cmake/cosmocc.cmake
+{{#include cmake/cosmocc.cmake}}
+```
+
+```cmake:cmake/cosmocc-override.cmake
+{{#include cmake/cosmocc-override.cmake}}
+```
+
+<details>
+
+```c:main.c
+{{#include main.c}}
+```
+
+```cmake:CMakeLists.txt
+{{#include CMakeLists.txt}}
+```
+
+</details>
+
+```sh:
+cmake --toolchain ./cmake/cosmocc.cmake -B ./build/
+```
+
+```
+<!-- cmdrun cmake --fresh --toolchain ./cmake/cosmocc.cmake -B ./build/ -->
+```
+
+```sh:
+cmake --build ./build/
+```
+
+```
+<!-- cmdrun cmake --build ./build/ --clean-first -->
+```
diff --git a/src/cosmocc-toolchain/cmake/cosmocc-override.cmake b/src/cosmocc-toolchain/cmake/cosmocc-override.cmake
@@ -0,0 +1,3 @@
+set(CMAKE_ASM_OUTPUT_EXTENSION ".o")
+set(CMAKE_C_OUTPUT_EXTENSION ".o")
+set(CMAKE_CXX_OUTPUT_EXTENSION ".o")
diff --git a/src/cosmocc-toolchain/cmake/cosmocc.cmake b/src/cosmocc-toolchain/cmake/cosmocc.cmake
@@ -0,0 +1,9 @@
+set(CMAKE_SYSTEM_NAME Generic)
+unset(CMAKE_SYSTEM_PROCESSOR)
+set(CMAKE_ASM_COMPILER cosmocc)
+set(CMAKE_C_COMPILER cosmocc)
+set(CMAKE_CXX_COMPILER cosmoc++)
+set(CMAKE_USER_MAKE_RULES_OVERRIDE
+    "${CMAKE_CURRENT_LIST_DIR}/cosmocc-override.cmake")
+find_program(CMAKE_AR cosmoar REQUIRED)
+find_program(CMAKE_RANLIB cosmoranlib REQUIRED)
diff --git a/src/cosmocc-toolchain/main.c b/src/cosmocc-toolchain/main.c
@@ -0,0 +1,15 @@
+#include <stdio.h>
+// cosmocc adds a cosmo.h header.
+#include <cosmo.h>
+
+int main() {
+    printf("IsLinux()=%d\n", IsLinux());
+    printf("IsMetal()=%d\n", IsMetal());
+    printf("IsWindows()=%d\n", IsWindows());
+    printf("IsBsd()=%d\n", IsBsd());
+    printf("IsXnu()=%d\n", IsXnu());
+    printf("IsFreebsd()=%d\n", IsFreebsd());
+    printf("IsOpenbsd()=%d\n", IsOpenbsd());
+    printf("IsNetbsd()=%d\n", IsNetbsd());
+    return 0;
+}
diff --git a/src/hello-world/README.md b/src/hello-world/README.md
@@ -2,37 +2,52 @@
 
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/jcbhmr/cmakebyexample.jcbhmr.com?quickstart=1&devcontainer_path=.devcontainer%2Fhello-world%2Fdevcontainer.json)
 
-```c
+```c:main.c
 {{#include main.c}}
 ```
 
-```cmake
+```cmake:CMakeLists.txt
 {{#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
+```sh:
+# 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" or
+# "generation". 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.
 cmake -B ./build/
 ```
 
 ```
-<!-- cmdrun cmake -B ./build/ -->
+<!-- cmdrun cmake --fresh -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
+```sh:
+# 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/`.
 cmake --build ./build/
 ```
 
 ```
-<!-- cmdrun cmake --build ./build/ -->
+<!-- cmdrun cmake --build ./build/ --clean-first -->
 ```
 
-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
+```sh:
+# 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`. (You _can_ override
+# this with the `OUTPUT_NAME` target property.)
 ./build/hello-world
 ```
 
diff --git a/src/hello-world/main.c b/src/hello-world/main.c
@@ -1,12 +1,15 @@
 // 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
+//
+//     gcc -o hello-world main.c
+//     ./hello-world
+//
+// ...but that can quickly become unweildly when you add more .c files,
+// dependencies, include directories, etc. That's where CMake really shines.
 
 #include <stdio.h>
 
 int main() {
-    puts("Hello, World!");
-    return 0;
+  puts("Hello, World!");
+  return 0;
 }
diff --git a/src/logging/CMakeLists.txt b/src/logging/CMakeLists.txt
@@ -0,0 +1,40 @@
+cmake_minimum_required(VERSION 3.30)
+
+project(logging)
+
+# message() can be placed anywhere! Remember, CMake is procedural: it executes
+# commands like a programming language. It's not JSON. That means we can place
+# message() commands anywhere in the CMakeLists.txt file to print messages to
+# the console. This is very useful for debugging and understanding what's
+# happening in the GENERATION phase of CMake.
+message("Hello, World!")
+
+add_executable(logging main.c)
+
+# message() takes an optional log level as the first argument. Here's all of
+# them in one big list. Uncomment the FATAL_ERROR and SEND_ERROR lines to see
+# how they cause the build process to fail.
+
+# message(FARAL_ERROR "CMake Error, stop processing and generation. The cmake(1) executable will return a non-zero exit code.")
+# message(SEND_ERROR "CMake Error, continue processing, but skip generation.")
+message(WARNING "CMake Warning, continue processing.")
+message(AUTHOR_WARNING "CMake Warning (dev), continue processing.")
+message(DEPRECATION "CMake Deprecation Error or Warning if variable CMAKE_ERROR_DEPRECATED or CMAKE_WARN_DEPRECATED is enabled, respectively, else no message.")
+message("Important message printed to stderr to attract user's attention.")
+message(NOTICE "Important message printed to stderr to attract user's attention.")
+message(STATUS "The main interesting messages that project users might be interested in. Ideally these should be concise, no more than a single line, but still informative.")
+message(VERBOSE "Detailed informational messages intended for project users. These messages should provide additional details that won't be of interest in most cases, but which may be useful to those building the project when they want deeper insight into what's happening.")
+message(DEBUG "Detailed informational messages intended for developers working on the project itself as opposed to users who just want to build it. These messages will not typically be of interest to other users building the project and will often be closely related to internal implementation details.")
+message(TRACE "Fine-grained messages with very low-level implementation details. Messages using this log level would normally only be temporary and would expect to be removed before releasing the project, packaging up the files, etc.")
+
+# But what if you want to print a message during the build process? You can't. I
+# mean, you *can* but you really shouldn't. If you're looking to debug what
+# CMake's "cmake --build" is doing under the hood then use
+# set(CMAKE_EXPORT_COMPILE_COMMANDS ON) or -DCMAKE_EXPORT_COMPILE_COMMANDS=ON to
+# generate a compile_commands.json file. Then you can inspect compile_commands.json
+# and see what's going on. Tools like Visual Studio Code can also utilize this
+# file to provide code completion and other features.
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+# In fact, the CMake Visual Studio Code extension will add
+# "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON" to its CMake configuration by default.
diff --git a/src/logging/README.md b/src/logging/README.md
@@ -1 +1,33 @@
 # Logging
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/jcbhmr/cmakebyexample.jcbhmr.com?quickstart=1&devcontainer_path=.devcontainer%2Flogging%2Fdevcontainer.json)
+
+```cmake:CMakeLists.txt
+{{#include CMakeLists.txt}}
+```
+
+<details>
+
+```c:main.c
+{{#include main.c}}
+```
+
+</details>
+
+```sh:
+# During the CONFIGURE stage is then the message() command will print things.
+cmake -B ./build/
+```
+
+```
+<!-- cmdrun cmake --fresh -B ./build/ -->
+```
+
+```sh:
+# Notice that none of the message() calls show up here.
+cmake --build ./build/
+```
+
+```
+<!-- cmdrun cmake --build ./build/ --clean-first -->
+```
diff --git a/src/logging/main.c b/src/logging/main.c
@@ -0,0 +1,4 @@
+// This is just a no-op target. See CMakeLists.txt for how message() works.
+int main() {
+    return 0;
+}
diff --git a/src/scripts/README.md b/src/scripts/README.md
diff --git a/src/scripts/cat.cmake b/src/scripts/cat.cmake
diff --git a/src/scripts/raven.txt b/src/scripts/raven.txt
diff --git a/src/values.md b/src/values.md
diff --git a/src/zig-toolchain/README.md b/src/zig-toolchain/README.md
diff --git a/task.cmake b/task.cmake
diff --git a/theme/highlight.js b/theme/highlight.js

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,6 @@`
`1`	`1`	`{`
`2`		`- "name": "Hello world",`
`3`		`- "image": "mcr.microsoft.com/devcontainers/cpp",`
`4`		`- "workspaceFolder": "${localWorkspaceFolder}/src/hello-world"`
	`2`	`+ "image": "mcr.microsoft.com/devcontainers/cpp:ubuntu",`
	`3`	`+ "workspaceMount": "source=${localWorkspaceFolder}/src/hello-world,target=/workspace,type=bind,consistency=cached",`
	`4`	`+ "workspaceFolder": "/workspaces/hello-world",`
	`5`	`+ "updateContentCommand": "curl -fsSL https://apt.kitware.com/kitware-archive.sh \| sh"`
`5`	`6`	`}`