CMake cmake_parse_arguments localization is the practice of explaining reusable CMake function and macro keywords in the reader’s language without changing what the build system recognizes. Developers searching for cmake_parse_arguments examples, PARSE_ARGV, keyword validation, translated CMake errors, Unicode file paths or multilingual build instructions need to understand an important boundary: this command parses arguments to CMake functions and macros, not arbitrary shell command-line flags.
The built-in cmake_parse_arguments command classifies tokens into no-value options, one-value keywords and multi-value keywords. It creates prefixed variables containing parsed results and can report unparsed arguments or missing values. A translated build guide can help people use those tokens correctly, but translated prose does not register a different keyword, change the CMakeLists.txt interface or make invalid syntax work.
This guide teaches a harmless public-manifest example, then moves from elementary grammar to version-sensitive details, scoped variables, semicolon handling, clear diagnostics, source files, documentation consistency and release tests. Readers will learn how to tell a parser problem from a translation problem and how to make a multilingual build guide reliable across teams and platforms.
Immediate answer: rules for international CMake helper functions
- cmake_parse_arguments parses function or macro arguments inside the CMake language, not the shell command line directly.
- Keep published keywords such as LOCALE, DESTINATION and FILES stable unless the helper implements aliases.
- Separate option switches, one-value keywords and multi-value keywords in both code and explanations.
- Use PARSE_ARGV in functions when preserving special semicolon-containing arguments matters.
- Check UNPARSED_ARGUMENTS and KEYWORDS_MISSING_VALUES deliberately.
- Handle policy-sensitive empty values and CMake-version requirements explicitly.
- Use localized diagnostics for humans while preserving build variables, generated file names and machine-readable contracts.
A working CMake helper to learn from
cmake_minimum_required(VERSION 3.15)
project(public_manifest NONE)
function(prepare_public_manifest)
set(options VERBOSE)
set(one_value LOCALE DESTINATION)
set(multi_value FILES)
cmake_parse_arguments(PARSE_ARGV 0 arg
"${options}" "${one_value}" "${multi_value}")
if(arg_UNPARSED_ARGUMENTS)
message(FATAL_ERROR "Unknown arguments: ${arg_UNPARSED_ARGUMENTS}")
endif()
if(arg_KEYWORDS_MISSING_VALUES)
message(FATAL_ERROR "Missing values: ${arg_KEYWORDS_MISSING_VALUES}")
endif()
if(NOT DEFINED arg_DESTINATION)
message(FATAL_ERROR "DESTINATION is required")
endif()
if(NOT DEFINED arg_LOCALE)
set(arg_LOCALE "en")
endif()
if(NOT arg_LOCALE MATCHES "^(en|fr|ja)$")
message(FATAL_ERROR "Supported locales: en, fr, ja")
endif()
if(arg_VERBOSE)
message(STATUS "Manifest preview for ${arg_LOCALE}")
endif()
message(STATUS "Destination: ${arg_DESTINATION}")
endfunction()
prepare_public_manifest(LOCALE en DESTINATION preview VERBOSE
FILES "sample-one.csv" "example two.csv")This sample previews harmless configuration metadata; it does not copy or alter files and is not a finished localization service. Its visible messages remain English, so supplying LOCALE fr or ja does not magically translate them. The minimum version is chosen to cover the missing-value variable and PARSE_ARGV behavior discussed here; teams using newer features should raise their own version requirement accordingly.
Why keyword syntax and explanatory language must be distinct
CMake function calls are executable build instructions. A call such as prepare_public_manifest(LOCALE fr DESTINATION preview) has a token sequence the helper actually parses. Translating LOCALE into a reader’s preferred word inside a code block changes that call, unless the function has been programmed to recognize the new token. Natural-language explanations can be translated freely; execution keywords require deliberate compatibility decisions.
The same separation applies to filenames and generated artifacts. A path may contain Japanese or Arabic characters as legitimate data, but it should not be renamed merely because a translated paragraph describes it. Readers deserve exact examples: one valid invocation, a clear account of every required keyword and a failure they can repair on the next attempt.
Deep practical lessons
This is not a general CLI parser
cmake_parse_arguments is called from CMake code to interpret another CMake function or macro’s arguments. It is distinct from parsing terminal invocations of the cmake executable.
A multilingual tutorial that calls it a shell flag parser may lead readers to paste keywords after cmake -S or -B and expect the helper to see them.
Show a function definition and the function call on the same page. Explain separately how -D cache settings reach CMake scripts.
Run the example through CMake configuration, not as a standalone shell getopt demonstration, and verify which layer receives each token.
No-value options
The options list declares keywords that act as switches, such as VERBOSE. The resulting prefixed variable is true when the token is present and false otherwise.
A translated instruction may tell a reader to add TRUE after the switch, accidentally making TRUE an unparsed token or another value.
Show VERBOSE alone and explain its Boolean result in prose. Do not invent a required argument for a no-value keyword.
Compare function calls with and without VERBOSE and inspect the generated arg_VERBOSE value and any unparsed tokens.
One-value keywords
A keyword in one_value takes one following argument, such as DESTINATION preview. Its value is stored under a corresponding prefixed variable.
A localized guide that swaps the order of the keyword and its value to match a natural sentence breaks the actual CMake call.
Put the exact token order in a code sample and provide a separate sentence translating its meaning.
Pass one valid destination, then omit the value and inspect the missing-keyword report before any filesystem action.
Multi-value keywords
A keyword in multi_value introduces a sequence of values until another recognized keyword interrupts the list. FILES may therefore receive several source names.
A document that treats the whole list as one string may produce incorrect working assumptions, especially for paths containing spaces or semicolons.
Explain each list element and show quoted paths as separate CMake arguments. Name the point at which a subsequent keyword ends the list.
Call FILES with two filenames and then with FILES followed by DESTINATION, comparing the resulting list and missing values.
Unique keyword names
The three keyword sets should not contain duplicates across categories. CMake warns about conflicting declarations because parsing cannot be reliably explained otherwise.
A translator may introduce a localized synonym that duplicates another recognized keyword, creating a grammar collision rather than better accessibility.
Maintain a reviewed keyword inventory and ensure new aliases are unique across options, one-value and multi-value lists.
Declare a duplicate in a synthetic test fixture and inspect the warning, then restore a unique documented grammar.
The prefix controls variable names
The parser writes variables by joining its prefix and recognized keyword, for example arg_DESTINATION. The prefix is therefore part of scoping and implementation hygiene.
Two helpers in the same scope can overwrite similarly named parsed variables, leading to a misleading report that appears unrelated to translation.
Use a clear distinctive prefix where necessary, especially inside macros, and name it consistently in examples.
Create two small helpers with overlapping keywords and verify that parsed results do not leak between them.
PARSE_ARGV belongs to functions
The PARSE_ARGV form reads numbered ARGV entries from the calling function beginning at a specified offset. It is intended for function bodies.
A tutorial may copy this signature inside a macro and imply it is interchangeable with the classic argument-list signature.
State the function-only restriction and show a working function. When documenting a macro, use the appropriate form and consider its scope effects.
Configure one function example and one macro example with the correct signatures, then compare their results.
Version requirements for PARSE_ARGV
PARSE_ARGV was added in CMake 3.7, after native cmake_parse_arguments was introduced. Earlier version constraints can make otherwise sound code unusable.
An article that silently assumes a newer feature works on an older build environment causes errors that international readers may mistake for mistranslation.
State the minimum CMake version needed for the exact examples and keep fallback guidance separate from the primary code.
Run CI with the minimum advertised version and at least one newer version, checking every invocation and diagnostic.
Version requirements for missing values
The KEYWORDS_MISSING_VALUES result was added in CMake 3.15. It gives applications a way to report keywords that appeared without expected values.
A guide targeting an older release may promise that a useful missing-value list exists when it does not, hiding why an error message is incomplete.
Use a minimum version that supports the variable or implement a separately tested fallback. Do not pretend all releases expose identical diagnostics.
Invoke DESTINATION without a value under the stated supported versions and confirm the helper reports it clearly.
PARSE_ARGN in newer CMake
Current documentation describes PARSE_ARGN for functions, added in CMake 4.4, to start parsing after the function’s named parameters.
A tutorial can present it as universally available even when readers use older 3.x or early 4.x installations.
Treat PARSE_ARGN as a version-specific alternative and provide a working PARSE_ARGV route when compatibility requires it.
Check cmake –version before using the newer signature and test the offset against the declared function parameters.
ARGV offsets
In PARSE_ARGV N, the index N tells the parser where to begin in the function’s argument sequence. Choosing zero differs from skipping named arguments.
If a helper has a fixed leading parameter and a translated guide uses the wrong offset, the leading value may be mistaken for a keyword.
Draw the argument sequence with positions before choosing N, then use the same positional explanation in every language.
Run a helper with a fixed destination and two keywords; inspect which arguments become parsed and which remain unknown.
Semicolon preservation
CMake commonly represents lists using semicolons. PARSE_ARGV is designed to preserve special characters such as semicolons in actual arguments.
A naive expansion of ARGN can split values in ways that change the meaning of a translated example or a path supplied by a caller.
Use PARSE_ARGV for function arguments when that preservation is important and test values containing literal semicolons carefully.
Pass a harmless argument with a semicolon and inspect the resulting variable using a test that reveals the exact stored value.
CMake quoted arguments
CMake quoting and list expansion are separate from translated sentences. A path with spaces must be represented in syntax that creates the intended argument.
A code block may look fluent and readable but lose quotation marks during editing, changing the number of values seen by the parser.
Keep executable quotations literal, and explain examples in prose instead of rewriting them to follow translated punctuation conventions.
Try a path with spaces and compare the resulting FILES list with the count and values the page describes.
Missing versus empty one-value data
A keyword absent from a call is not the same concept as a keyword supplied with an empty string. Version policy can affect whether a corresponding variable is defined.
A validator based only on truthiness may reject a deliberately empty value or accept a missing required value without a useful message.
Decide whether emptiness is meaningful for each keyword. Use explicit presence checks and document acceptable empty values.
Compare omitted DESTINATION, DESTINATION followed by an empty argument, and a normal value under the target policy setting.
Policy CMP0174
CMake policy CMP0174 affects how empty string values of one-value keywords are represented. It was introduced in CMake 3.31.
A translation that says the variable is always absent or always defined for an empty value can be technically wrong across supported policy settings.
Mention the relevant policy when teaching version-sensitive empty values, and write validation that matches the selected project policy.
Configure the empty-value fixture under the policy modes you claim to support and record whether the variable is defined.
UNPARSED_ARGUMENTS
Any remaining arguments not consumed as recognized keywords or their values appear in the prefixed unparsed-arguments variable.
Silently ignoring this variable can allow a misspelled keyword to pass as an unused token, making a user believe a requested option was applied.
Choose whether unknown tokens should be rejected and make that decision visible. For strict helper APIs, fail with an actionable message.
Pass a deliberate typo such as LOCALEE en and ensure the error identifies the unrecognized input before work begins.
KEYWORDS_MISSING_VALUES
When recognized keywords requiring values have none, the parser can expose their names through the prefixed missing-values variable.
A generic translated error like incorrect call gives a novice no way to distinguish an omitted value from an unknown keyword.
Report missing keywords by their exact executable spellings and provide the smallest corrected call that illustrates recovery.
Call a helper with FILES at the end and with DESTINATION lacking a value; observe the correct missing-keyword report.
Keyword order
Recognized keywords can appear in different orders, but lists end when another recognized keyword begins. The resulting grammar must be documented as executable behavior.
A multilingual page may reorder parts of a sample to make the prose flow and accidentally move a filename into the wrong value group.
Keep a known-good call in a code block, then use complete sentences outside it to explain each group.
Test two valid keyword orders and inspect the same resulting values; test one invalid boundary that should produce an error.
Unknown keyword versus value
A token that looks like an English command word is still only a token until the parser recognizes it as a keyword. Otherwise it may be unparsed or part of a list.
Someone may translate DESTINATION in a function call and find that the translated word is swallowed as a file value rather than producing an obvious error.
Do not rely solely on messages from the parser. Validate the relevant output variables and unknown arguments before using them.
Supply a translated-but-unregistered keyword in a fixture and observe the parsed variables, not just the visible status.
Macro scope collisions
Macros execute in the caller’s scope, making generated variables more likely to collide with unrelated code. Functions provide their own variable scope.
A guide that changes a helper from function to macro as an editorial simplification can introduce hidden state changes throughout a project.
Prefer functions for isolated public helper APIs when suitable, and use distinctive prefixes when macros are necessary.
Build a fixture with two helpers sharing a keyword and confirm whether the intended variables remain isolated after each call.
Function variable scope
Variables created inside a function do not automatically become caller-visible results. A helper must explicitly define its return or output contract.
A translation may imply that a parsed LOCALE value becomes globally available to the whole build merely because the sample function uses it.
Explain what the function computes locally and how intended results are returned. Avoid broad promises about project-wide configuration.
Call the helper and inspect caller scope before and after; verify only the documented outputs are available.
Cache variables are different
A -DNAME=value invocation populates cache-related configuration and is not automatically the same as passing NAME value to a custom function.
An international reader may copy -DLOCALE=fr into the CMake command and expect a nested function’s LOCALE keyword to receive it.
Document how a cache input is explicitly read and passed when supported. Show terminal invocation and helper call as separate examples.
Test the helper with and without a -D setting and verify whether the code actually transfers that value.
Configure-time versus build-time
Many CMake messages and helper calls run at configuration or generation time. A translated guide must not claim they happen when the compiled program is later executed.
A reader may wait for a build command to show help that is only emitted during configuration, believing the localization is broken.
State which phase the sample operates in and which commands trigger it. Keep build output and application runtime separate.
Run cmake -S . -B build and then the build step, recording when each message appears.
Message FATAL_ERROR
message(FATAL_ERROR …) stops configuration with an error. That is appropriate for invalid required arguments but not merely for optional informational help.
A translated message may use mild phrasing while terminating the build, leaving the reader unsure whether files were generated or an operation completed.
Use clear severity wording, name the wrong keyword and show a corrected invocation. Keep failure states honest across languages.
Cause a missing required destination and assert nonzero configuration status plus a specific error before any generated artifact is claimed.
Message STATUS
message(STATUS …) prints a status message during configuration. It is useful for informational progress, but wording must match actual operations.
A status line saying manifest created is false when the example merely validates arguments and prints a preview.
Use verbs such as checking, planning or previewing until the corresponding action has finished successfully.
Run the preview fixture and verify that message wording never implies a file was written when none was produced.
Message catalog selection
cmake_parse_arguments does not select translations. LOCALE is just a parsed variable until user code chooses appropriate messages.
A sample with LOCALE ja can still print English. Calling this automatically localized would be inaccurate and unhelpful.
Implement a small reviewed lookup layer or message dictionary, then use the validated code when producing human-facing diagnostics.
Run the helper under two real message sets and verify that only presentation changes while keyword parsing remains constant.
Language-tag validation
Values such as en, fr and ja need a supported set and a fallback policy. The parser does not treat them as language tags intrinsically.
A translated guide may display full language names as sample argument values, even though the function accepts abbreviated identifiers.
Use accepted codes in copyable CMake calls and give translated names separately. Reject unsupported values with a useful list.
Test en, fr, ja, a misspelling and a mixed-case tag, recording whether normalization is intentionally supported.
Identifiers versus captions
LOCALE, DESTINATION and FILES are recognized keywords, whereas the prose around them is an explanation for humans.
If a translation replaces the keyword with a synonym, the command’s meaning has changed even if the sentence sounds better.
Preserve exact spelling in code and localize descriptions, headings and task instructions. Register a real alias only through deliberate design.
Have a second reviewer copy the translated call into a clean project and compare the observed parser variables.
Naming an alias
A helper can intentionally recognize multiple keyword names, but then it must define how they map to one meaning and what happens when both are supplied.
A localized synonym that overlaps with another accepted keyword can make parsing ambiguous, especially in multi-value sequences.
Prefer one stable canonical name. If aliases are required, validate precedence and conflicts after parsing and document them for every audience.
Test both tokens individually and together in different orders, verifying the helper’s actual conflict rule.
Code blocks and punctuation
Executable CMake tokens can include quotes, parentheses, braces, variable expansions and semicolons. Editorial typography must not silently transform them.
Replacing ASCII quotes with curly quotation marks for visual style can make an example impossible to paste directly.
Use literal code blocks with correct encoding. Translate full sentences outside the code rather than decorating the syntax itself.
Copy code from the published page into a clean CMakeLists.txt and configure it successfully.
Generator expressions
CMake generator expressions such as $<…> belong to the build language and have their own evaluation rules. They are not natural-language placeholders.
A translator may mistake angle brackets in a generator expression for replaceable words and corrupt a build configuration.
Clearly separate CMake expression syntax, ordinary variable references and editorial placeholders in the documentation.
Use a harmless supported generator expression in a fixture and check that the translated page preserves its exact token sequence.
Variable expansions
The syntax ${name} expands a CMake variable. Quotation marks and expansion timing can change how arguments are grouped and passed.
A target-language page may translate the variable identifier inside braces while leaving the actual CMake project unchanged, creating a missing value.
Keep registered variable identifiers stable in executable examples and provide localized captions outside the expression.
Compare the expanded value in a test configuration and confirm that the documented example does not silently produce an empty string.
CMake list semantics
Multi-value output is often represented with CMake list semantics. A semicolon can be a delimiter or part of a carefully preserved argument.
A guide that treats all list values as a single natural-language phrase may hide how downstream functions interpret each element.
Show examples with distinct filenames and inspect the list elements. Avoid unexplained string joins and splits in code users are meant to copy.
Test two ordinary items and one item requiring special-character handling; examine the actual downstream argument boundaries.
Unicode CMake files
CMake source files and their containing paths may include Unicode. Correct handling depends on the file encoding and supported toolchain, not only the translation text.
A Japanese path can display correctly in a browser but fail in a compiler or downstream tool invoked later in the build.
Test the whole toolchain with harmless Unicode fixtures and distinguish a CMake parser result from a separate compiler or filesystem limitation.
Configure and build a minimal project using a Unicode path; record the first component that changes or rejects the value.
Windows and Unix paths
Platform-specific separators, drive prefixes, quoting and case sensitivity can alter how sample paths behave. Those details are independent of human language.
A tutorial may substitute a Windows-style path into Unix code without adapting the actual build environment, creating a false impression of a localization defect.
Label platform-specific snippets and prefer portable CMake path operations when possible. Explain any unavoidable platform boundaries.
Run the same public-manifest fixture on the supported platforms and compare path values without touching private directories.
Relative path resolution
A relative destination may be interpreted with respect to a particular source or binary directory. Translation does not establish which directory is used.
A reader can believe preview means a new folder in their working directory when the code actually resolves it elsewhere.
Document the base directory and use a safe synthetic path in teaching examples. Do not claim file creation unless implemented.
Print or inspect the resolved path in a development fixture and compare it with the documentation’s precise explanation.
Build presets and JSON
CMakePresets.json has structured field names and an explicit schema. Those keys must not be localized merely because a team uses translated explanatory pages.
A localized preset tutorial that renames configurePresets breaks parsing, even though the surrounding caption is grammatical.
Translate descriptions and user-facing display text where supported, but preserve the actual JSON schema and preset references.
Run preset validation with the translated guide’s exact snippet and compare parsed fields against the canonical example.
Policy and version disclosures
CMake behavior can change under policy settings and new versions. Readers need to know whether a sample requires a particular policy state.
A vague promise that all CMake installations behave identically can be more harmful than admitting a small documented compatibility boundary.
Name the minimum tested version and any policy relevant to empty or parsed values. Give a stable primary path rather than a blend of conflicting examples.
Configure the same fixture under every claimed supported version and record warnings, defined variables and status.
Diagnostics with real recovery
A good error names the helper, the offending keyword and the next valid form. That structure is useful in any language.
A translation that reports only invalid arguments makes the user search the whole documentation again to learn what they did wrong.
Use short actionable text and one corrected CMake call. Do not assume the reader already knows whether a keyword needs one or many values.
Ask a reader to correct LOCALE without a value using only the localized message, then run the resulting call.
Unknown token review
A function can intentionally accept free arguments, but that should be an explicit contract. Otherwise unknown tokens need review before build steps proceed.
If an extra word is silently dropped, the documentation can appear to succeed while an expected file or setting was never used.
Either reject unparsed tokens or describe their supported meaning. Keep the choice consistent across language versions.
Pass an extra harmless token and ensure the resulting configuration follows the documented rule rather than quietly ignoring it.
Reviewing optional switches
A switch like VERBOSE may affect messages without changing the manifest or build artifact. That is a sensible international command design.
A translated help page can promise that verbose mode enables additional files or changes configuration when it only increases diagnostics.
Describe exactly what verbosity changes, and keep operation results independent from display-level detail where practical.
Compare the same helper invocation with and without VERBOSE and verify the underlying validated values are identical.
File-list safety
Even a harmless example may inspire users to adapt it to copying or deleting files. Parsed paths must not be trusted solely because their keyword was recognized.
A misleading localized success message can conceal that a path was outside the intended working area or that validation was skipped.
Validate allowed locations and types before side effects in real implementations, and use a preview mode for teaching.
Test synthetic paths outside a permitted fixture and confirm the operation rejects them without writing or deleting anything.
Error translations with values
Errors often include a keyword and a value. In some languages the placeholder belongs in a different grammatical position than in English.
Building sentences by concatenating English fragments around ${value} produces awkward or ambiguous instructions, especially with right-to-left scripts.
Translate whole messages with controlled interpolation and keep literal CMake tokens visually isolated from surrounding text.
Review errors with a short code, a long path and a mixed-script filename in the actual terminal output.
Multilingual terminal width
CMake status messages can contain wide characters, combining marks and different punctuation conventions. Long lines may wrap on narrow terminals.
A visually aligned English table can become unreadable when translated, making an error appear attached to the wrong keyword.
Prefer short sentences and explicit labels over fragile spacing. Avoid relying on colors or alignment to communicate severity.
Capture output at several terminal widths in two languages and inspect the no-color representation.
Right-to-left code mixing
Arabic or Hebrew instructions may appear beside left-to-right CMake keywords, braces and path fragments. Visual rearrangement can confuse copying.
A browser rendering that looks acceptable may not predict how a terminal displays the same mixed-direction message.
Keep executable calls in isolated code blocks and review copy/paste fidelity, not merely visual attractiveness.
Copy a command from the published page into an editor, inspect its bytes and run the exact call.
Continuous integration matrix
A build guide should be tested on the versions and platforms it claims to support. Translation quality depends on reproducible technical behavior.
A documentation change can be approved by language review alone while a CMake upgrade breaks a keyword or warning in real builds.
Run the helper fixture under a small version and platform matrix, then validate localized error text separately.
Record invocation, CMake version, process status, parsed variables and output for success and failure cases.
Maintaining a keyword inventory
Every public helper keyword is a small API. It needs ownership, examples and a change history when its behavior is modified.
Adding a keyword in code without updating translated documentation can leave international users guessing why the official examples omit it.
Keep a compact table of canonical keywords, value cardinality, defaults and validators, and synchronize it with help and tests.
Compare the inventory against actual parser declarations and try every documented example in a clean checkout.
Meaningful negative examples
Learners understand parser boundaries faster by seeing one invalid invocation beside the corrected form. Errors are part of the interface.
A tutorial that shows only success paths leaves the impression that CMake will repair malformed input automatically.
Demonstrate unknown keywords, missing values, duplicate concepts and wrong ordering with harmless fixtures.
Assert that every failure produces a nonzero configuration result and a message naming the concrete repair.
Release documentation and packaging
Translated build instructions may be distributed as repository Markdown, generated documentation or CI logs. Each surface needs consistent runnable calls.
A local document can be accurate while an older generated website retains a removed keyword and confuses users.
Review all public surfaces when the helper changes, including examples, source comments and localized messages.
Copy the installed or released documentation examples into a fresh checkout rather than testing only a development branch.
When not to use cmake_parse_arguments
A small helper with positional inputs may not need a keyword parser. Adding an elaborate international grammar can obscure a simple task.
A guide becomes unhelpful when it implies that every CMake variable or terminal argument should be routed through cmake_parse_arguments.
Use the parser when a named function interface genuinely benefits from options and keyword groups. Keep separate concerns separate.
Write a minimal positional version and a keyword-driven version, then choose based on actual error clarity and maintenance needs.
A complete workshop: prove the translated helper works
Create a new empty project with a CMakeLists.txt containing the sample function. Configure it with a clean build directory and read the STATUS output. Then run a second variant with LOCALE fr, and verify that the parser still records fr without falsely assuming the English messages will translate. A real locale catalog can be added afterward, but that is a distinct implementation task.
Next make three controlled errors. Omit DESTINATION, supply an unrecognized token and give LOCALE an unsupported value. Each should stop with a different explanation: missing required keyword, unknown argument or unsupported locale. Capture the actual stderr, process status and version information. If a translated page says only something went wrong, rewrite it so the reader can produce a corrected invocation.
Finally test a file name with spaces and a semicolon-containing argument where your helper promises support. Compare the PARSE_ARGV result with a deliberately unsafe argument expansion in a separate temporary fixture, then restore the safe implementation. Test on the minimum advertised CMake version and at least one newer release. This evidence is much stronger than a screenshot showing attractive help text.
Frequently asked questions
Does cmake_parse_arguments parse cmake -D flags?
No. It classifies the arguments supplied to a CMake function or macro. Connecting -D cache values to that function is separate code.
When should PARSE_ARGV be used?
Inside a function, especially when preserving individual arguments containing special characters such as semicolons matters.
What is PARSE_ARGN?
A newer function-only form documented from CMake 4.4 that starts after named function arguments; check your minimum CMake version.
How do I reject a misspelled keyword?
Check the prefixed UNPARSED_ARGUMENTS result and respond with a specific corrective message.
How can I detect a keyword without a value?
On supported versions, inspect KEYWORDS_MISSING_VALUES and distinguish a missing keyword from a keyword supplied with no value.
Can I translate DESTINATION in executable code?
Only by actually registering and validating an alias; otherwise keep the keyword and translate its explanatory caption.
Why do empty strings behave differently by version?
The relevant CMP0174 policy affects how empty one-value arguments are represented; test the documented project policy.
How should a new user test the guide?
Configure a clean minimal project, copy the literal function call, inspect parsed variables and check status plus failure diagnostics.
Primary references and continued learning
- CMake: cmake_parse_arguments reference
- CMake message() reference
- CMake CMP0174 policy
- Master Art of Translation — meaning and accuracy
- Translate Like a Pro — specialist guides
The central lesson is that a build helper’s grammar should not change unpredictably when its explanation changes language. Teach literal calls, name version boundaries, localize complete errors and test the result in the toolchain readers actually use. International documentation succeeds when people can act correctly and understand a failure without needing to guess which word was meant.