CCMAKE(1)

📦
version 4.4.5 · 21 versions
, in arch rolling

🎀 CCMAKE(1) — NAME 🎀

ccmake — the CMake Curses Dialog Command-Line Reference 💅 (yes bestie, this is the manual page for it, and yes your terminal is about to get cute)

✨ SYNOPSIS ✨

Like, here's how you actually summon it:

ccmake [<options>] -B <path-to-build> [-S <path-to-source>]
ccmake [<options>] <path-to-source | path-to-existing-build>

🦋 DESCRIPTION 🦋

okay so. The ccmake executable is the CMake curses interface — that's the whole vibe. Project configuration settings may be specified interactively through this GUI, which is lowkey iconic. Brief instructions are provided at the bottom of the terminal when the program is running, so you're never just standing there like 🧍 wondering what to do.

CMake is a cross-platform build system generator (a real main character of the build world, ngl). Projects specify their build process with platform-independent CMake listfiles included in each directory of a source tree with the name CMakeLists.txt. Users build a project by using CMake to generate a build system for a native tool on their platform. That's it, that's the whole deal 💖

🌈 OPTIONS 🌈

Grab a snack, there's a lot of them, but I promise they all matter 🍓

  • -S <path-to-source> — path to the root directory of the CMake project to build. That's your source, your origin story ✨
  • -B <path-to-build> — path to the directory which CMake will use as the root of the build directory. And listen: if the directory doesn't already exist, CMake will make it. It's giving "I'll build the folder AND the project." 💅
  • -C <initial-cache> — pre-load a script to populate the cache.

When CMake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project. This option may be used to specify a file from which to load cache entries before the first pass through the project's CMake listfiles. The loaded entries take priority over the project's default values 🙌

The given file should be a CMake script containing set() commands that use the CACHE option — not a cache-format file. Do not come in with the wrong format, I'm begging 🙈

References to CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR within the script evaluate to the top-level source and build tree. Cute, right? 🎀

  • -D <var>:<type>=<value>, -D <var>=<value> — create or update a CMake CACHE entry.

When CMake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project. This option may be used to specify a setting that takes priority over the project's default value. And you can repeat the option for as many CACHE entries as your heart desires 💖

If the :<type> portion is given it must be one of the types specified by the set() command documentation for its CACHE signature. If the :<type> portion is omitted the entry will be created with no type if it does not exist with a type already. If a command in the project sets the type to PATH or FILEPATH then the <value> will be converted to an absolute path. Slay, path math 🔥

This option may also be given as a single argument: -D<var>:<type>=<value> or -D<var>=<value>.

The cache HELPSTRING is populated as follows:

  • If the cache entry is known to CMake, its help string is set to a one-line description of the variable.

Added in version 4.4.

  • Otherwise, its help string is set to the generic default No help, variable specified on the command line.
⚠️ It's important to note that the order of -C and -D arguments is significant. They will be carried out in the order they are listed, with the last argument taking precedence over the previous ones. For example, if you specify -DCMAKE_BUILD_TYPE=Debug, followed by a -C argument with a file that calls:
set(CMAKE_BUILD_TYPE "Release" CACHE STRING "" FORCE)
then the -C argument will take precedence, and CMAKE_BUILD_TYPE will be set to Release. However, if the -D argument comes after the -C argument, it will be set to Debug. 😭 order matters fr fr

If a set(... CACHE ...) call in the -C file does not use FORCE, and a -D argument sets the same variable, the -D argument will take precedence regardless of order because of the nature of non-FORCE set(... CACHE ...) calls. iykyk 👑

  • -U <globbing_expr> — remove matching entries from CMake CACHE.

This option may be used to remove one or more variables from the CMakeCache.txt file — globbing expressions using * and ? are supported. The option may be repeated for as many CACHE entries as desired.

💀 Use with care, you can make your CMakeCache.txt non-working. Like, genuinely. Be careful bestie.
  • -G <generator-name> — specify a build system generator.

CMake may support multiple native build systems on certain platforms. A generator is responsible for generating a particular build system. Possible generator names are specified in the cmake-generators(7) manual.

If not specified, CMake checks the CMAKE_GENERATOR environment variable and otherwise falls back to a builtin default selection. It'll figure it out 🌸

  • -T <toolset-spec> — toolset specification for the generator, if supported.

Some CMake generators support a toolset specification to tell the native build system how to choose a compiler. See the CMAKE_GENERATOR_TOOLSET variable for details 🫶

  • -A <platform-name> — specify platform name if supported by generator.

Some CMake generators support a platform name to be given to the native build system to choose a compiler or SDK. See the CMAKE_GENERATOR_PLATFORM variable for details.

  • --toolchain <path-to-file> — Added in version 3.21.

Specify the cross compiling toolchain file — equivalent to setting the CMAKE_TOOLCHAIN_FILE variable. Relative paths are interpreted as relative to the build directory, and if not found, relative to the source directory. Two homes, basically 🦋

  • --install-prefix <directory> — Added in version 3.21.

Specify the installation directory, used by the CMAKE_INSTALL_PREFIX variable. Must be an absolute path. No relative nonsense, the universe insists ⭐

  • --project-file <project-file-name> — Added in version 4.0.

Specify an alternate project file name.

This determines the top-level file processed by CMake when configuring a project, and the file processed by add_subdirectory().

By default, this is CMakeLists.txt. If set to anything else, CMakeLists.txt will be used as a fallback whenever the specified file cannot be found within a project subdirectory.

📌 Note: This feature is intended for temporary use by developers during an incremental transition and not for publication of a final product. CMake will always emit a warning when the project file is anything other than CMakeLists.txt. It's giving "temporary setup, don't ship it" 🚧
  • -W<category> — promote the specified diagnostic category (and any children) to at least WARN severity. Note that this has no effect on diagnostics already set to a higher severity. It only ever turns the volume up, never down 🔊

See the cmake-diagnostics(7) manual for a list of accepted values for <category>.

  • -Wno-<category> — disable (ignore) all diagnostics of the specified category, including any child categories. Shhh, we don't talk about that category 🙈
  • -Werror=<category> — promote the specified diagnostic category (and any children) to at least SEND_ERROR severity. Note that this has no effect on diagnostics already set to a higher severity. Escalation era 🔥
  • -Wno-error=<category> — demote the specified diagnostic category (and any children) to at most WARN severity. Note that this has no effect on diagnostics already set to a lower severity. De-escalation era 🧊
  • -Wdev, -Wno-dev — Deprecated since version 4.4.

Compatibility synonyms for -Wauthor / -Wno-author. Old names, still valid, but like… deprecated 💀

  • -version[=json-v1] [<file>], --version[=json-v1] [<file>], /V[=json-v1] [<file>], /version[=json-v1] [<file>] — show program name/version banner and exit. If json-v1 is specified, print extended version information in JSON format. The JSON output contains the versions for the CMake and its dependencies. The output is printed to a named <file> if given. Machine-readable and gorgeous ✨

The JSON output format is described in machine-readable form by this JSON schema.

  • -h, -H, --help, -help, -usage, /? — print usage information and exit. Usage describes the basic command line interface and its options. When in doubt, hit the help 🎀
  • --help <keyword> [<file>] — print help for one CMake keyword.

<keyword> can be a property, variable, command, policy, generator or module. Any of them, we don't gatekeep 💅

The relevant manual entry for <keyword> is printed in a human-readable text format. The output is printed to a named <file> if given.

Changed in version 3.28: Prior to CMake 3.28, this option supported command names only. Glow-up achieved 🌟

  • --help-full [<file>] — print all help manuals and exit. All manuals are printed in a human-readable text format. The output is printed to a named <file> if given. Yes, all of them. Hydrate first 🍓
  • --help-manual <man> [<file>] — print one help manual and exit. The specified manual is printed in a human-readable text format. The output is printed to a named <file> if given.
  • --help-manual-list [<file>] — list help manuals available and exit. The list contains all manuals for which help may be obtained by using the --help-manual option followed by a manual name. The output is printed to a named <file> if given. A little menu of manuals, iconic 👑
  • --help-command <cmd> [<file>] — print help for one command and exit. The cmake-commands(7) manual entry for <cmd> is printed in a human-readable text format. The output is printed to a named <file> if given.
  • --help-command-list [<file>] — list commands with help available and exit. The list contains all commands for which help may be obtained by using the --help-command option followed by a command name. The output is printed to a named <file> if given.
  • --help-commands [<file>] — print cmake-commands manual and exit. The cmake-commands(7) manual is printed in a human-readable text format. The output is printed to a named <file> if given.
  • --help-module <mod> [<file>] — print help for one module and exit.

...so yeah, the cmake-modules(7) manual entry for <mod> gets printed in a human-readable text format, and if you gave it a named <file>, that's where the output goes. Byte-for-byte useful, zero vibes-based guessing ✨

  • --help-module-list [<file>] — lists all the modules that actually have help available, then dips out. The list contains every module you could get help for by using the --help-module option followed by a module name. Output goes to the named <file> if you gave one. It's giving "table of contents but make it a flex" 💅
  • --help-modules [<file>] — prints the cmake-modules manual and exits. The cmake-modules(7) manual, in a human-readable text format, output to the named <file> if given. The whole thing. No crumbs. 🎀
  • --help-policy <cmp> [<file>] — prints help for exactly one policy and exits. The cmake-policies(7) manual entry for <cmp> comes out in a human-readable text format, and the output lands in the named <file> if you passed one. Main character energy for a single policy, honestly iconic 👑
  • --help-policy-list [<file>] — lists all policies with help available and exits. The list contains all policies you can get help for via the --help-policy option followed by a policy name. Named <file>? That's where it goes.
  • --help-policies [<file>] — prints the cmake-policies manual and exits. The cmake-policies(7) manual, human-readable text format, output to the named <file> if given. Slay.
  • --help-property <prop> [<file>] — prints help for one property and exits. The cmake-properties(7) manual entries for <prop> get printed in a human-readable text format, and the output goes to the named <file> if given. Note the plural: entries, bestie, because properties can have more than one 😭
  • --help-property-list [<file>] — lists all properties with help available and exits. The list contains every property for which help may be obtained by using the --help-property option followed by a property name. Output to the named <file> if given. Lowkey the most useful one ngl 🫶
  • --help-properties [<file>] — prints the cmake-properties manual and exits. The cmake-properties(7) manual, in human-readable text format, output to the named <file> if given. All of it. Every last property. 🌈
  • --help-variable <var> [<file>] — prints help for one variable and exits. The cmake-variables(7) manual entry for <var> is printed in a human-readable text format, and the output is printed to the named <file> if given. One variable, one moment, one legend ⭐
  • --help-variable-list [<file>] — lists all variables with help available and exits. The list contains all variables for which help may be obtained by using the --help-variable option followed by a variable name. The output goes to the named <file> if given. There are... a lot of them. Hydrate first 💀
  • --help-variables [<file>] — prints the cmake-variables manual and exits. The cmake-variables(7) manual comes out in a human-readable text format, and output goes to the named <file> if given. Big manual energy, we respect it 🧚

🌸 SEE ALSO 🌸

The following resources are available to get help using CMake — like, actually, go touch these:

  • Home Page — <https://cmake.org> The primary starting point for learning about CMake. The origin story. The main character. Start here fr fr 💖
  • Online Documentation and Community Resources — <https://cmake.org/documentation> Links to available documentation and community resources may be found on this web page. It's the link hub, the group chat pinned message of CMake links 🔥
  • Discourse Forum — <https://discourse.cmake.org> The Discourse Forum hosts discussion and questions about CMake. Go ask your question, someone there has been waiting their whole life for it 🦋

2000-2026 Kitware, Inc. and Contributors

That's the whole copyright line, no notes, they ate and left absolutely no crumbs 👑

Okay bestie, that's the whole page 🎀 You made it to the end — v <rainbow>4.4.5</rainbow> of CCMAKE(1), dated Oct 28, 2026, per the footer. Go forth and --help-everything responsibly 🌸💅✨

📦 where this page comes from