Support string arrays in kit cmakeSettings for semicolon-separated CMake lists (#4823)

* Support string arrays in kit cmakeSettings for semicolon-separated CMake lists (#4503)

Co-authored-by: Omotola <[email protected]>

* Restore original yarn.lock

Co-authored-by: Omotola <[email protected]>

* Fix schema description for consistency

Co-authored-by: Omotola <[email protected]>

* Extract cmakeify to pure module for testability and improve documentation

Co-authored-by: Omotola <[email protected]>

* Add comment explaining why localization is omitted in cmakeValue.ts

Co-authored-by: Omotola <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: Omotola <[email protected]>
Co-authored-by: Omotola <[email protected]>

Author: Copilot

CHANGELOG.md

@@ -16,6 +16,7 @@ Features:
 - Support `targetName` argument for launch-target command substitutions (`cmake.launchTargetPath`, etc.) via `${input:...}` variables, enabling build-before-run for non-active executable targets without changing the active launch target. [#4656](https://github.com/microsoft/vscode-cmake-tools/issues/4656)
 - Complete Bookmarks context menu with "Set Build Target", "Set Launch/Debug Target", "Open CMakeLists.txt", and "Run Utility Target" actions to match the Project Outline. [#4788](https://github.com/microsoft/vscode-cmake-tools/issues/4788)
 - Relax `intelliSenseMode` validation in CMake Presets. [#4815](https://github.com/microsoft/vscode-cmake-tools/issues/4815) [@halflifefan](https://github.com/halflifefan)
+- Support string arrays in kit `cmakeSettings` to pass CMake lists without escaping semicolons (e.g., `"LLVM_ENABLE_PROJECTS": ["clang", "lld"]`). [#4503](https://github.com/microsoft/vscode-cmake-tools/issues/4503)
 
 Improvements:
 - Add `.github/copilot-instructions.md` to ground GitHub Copilot in the repo's architecture and coding conventions.

docs/kits.md

@@ -151,6 +151,32 @@ The following additional options may be specified:
 
 > This setting is most useful when the toolchain file respects additional options that can be passed as cache variables.
 
+> **Semicolon Handling:**
+>
+> CMake uses semicolons as list separators. The type of value you use determines how semicolons are handled:
+>
+> - **String values**: Semicolons are **escaped** (`;` → `\;`) to prevent CMake from treating them as list separators. Use this for single values that happen to contain semicolons.
+>
+> - **Array values**: Elements are joined with semicolons **without escaping**, producing a proper CMake list. Use this when you intentionally want to pass a CMake list.
+>
+> **Example - Passing a CMake list (use array notation):**
+> ```jsonc
+> "cmakeSettings": {
+>     // Array notation → semicolons NOT escaped → creates CMake list
+>     "LLVM_ENABLE_PROJECTS": ["clang", "lld"]
+>     // Produces: -DLLVM_ENABLE_PROJECTS:STRING=clang;lld
+> }
+> ```
+>
+> **Example - String with semicolons escaped:**
+> ```jsonc
+> "cmakeSettings": {
+>     // String notation → semicolons ARE escaped → treated as single value
+>     "MY_VAR": "value;with;semicolons"
+>     // Produces: -DMY_VAR:STRING=value\;with\;semicolons
+> }
+> ```
+
 `environmentVariables`
 
 > A JSON object of key-value pairs specifying additional environment variables to be defined when using this kit.

schemas/kits-schema.json

@@ -72,7 +72,19 @@
                 "type": "object",
                 "patternProperties": {
                     ".*": {
-                        "description": "Value for the CMake Setting"
+                        "oneOf": [
+                            {
+                                "type": "string",
+                                "description": "Value for the CMake Setting. Semicolons in strings are escaped."
+                            },
+                            {
+                                "type": "array",
+                                "items": {
+                                    "type": "string"
+                                },
+                                "description": "Values joined with semicolons to form a CMake list without escaping."
+                            }
+                        ]
                     }
                 }
             },

src/cmakeValue.ts

@@ -0,0 +1,99 @@
+/**
+ * Pure utility functions for CMake value conversion.
+ * This module has NO dependencies on 'vscode' or 'vscode-nls', making it safe
+ * to import in backend tests that cannot load the vscode module.
+ */
+
+/**
+ * Represents a CMake cache variable value with its type.
+ */
+export interface CMakeValue {
+    type: ('UNKNOWN' | 'BOOL' | 'STRING' | 'FILEPATH' | 'PATH' | '');  // There are more types, but we don't care ATM
+    value: string;
+}
+
+/**
+ * Escape a string so it can be used as a regular expression
+ */
+function escapeStringForRegex(str: string): string {
+    return str.replace(/([.*+?^=!:${}()|\[\]\/\\])/g, '\\$1');
+}
+
+/**
+ * Replace all occurrences of `needle` in `str` with `what`
+ */
+function replaceAll(str: string, needle: string, what: string): string {
+    const pattern = escapeStringForRegex(needle);
+    const re = new RegExp(pattern, 'g');
+    return str.replace(re, what);
+}
+
+/**
+ * Checks if the given value is a string.
+ */
+function isString(x: unknown): x is string {
+    return Object.prototype.toString.call(x) === "[object String]";
+}
+
+/**
+ * Converts a given value to a CMake-compatible value.
+ *
+ * **Semicolon Handling:**
+ * - **String values**: Semicolons are escaped (`;` → `\;`) to prevent CMake from
+ *   interpreting them as list separators. Use this for single values that happen
+ *   to contain semicolons.
+ * - **Array values**: Elements are joined with semicolons WITHOUT escaping,
+ *   producing a proper CMake list. Use this when you intentionally want a CMake
+ *   list (e.g., `LLVM_ENABLE_PROJECTS`).
+ *
+ * @param value The value to convert. Can be:
+ *   - `boolean`: Converts to CMake BOOL ("TRUE" or "FALSE")
+ *   - `string`: Converts to STRING with semicolons escaped
+ *   - `number`: Converts to STRING
+ *   - `string[]`: Joins elements with `;` to form a CMake list (no escaping)
+ *   - `CMakeValue`: Passes through unchanged
+ * @returns A CMakeValue object with the appropriate type and value.
+ * @throws An error if the input value is invalid or cannot be converted.
+ *
+ * @example
+ * // String with semicolon - ESCAPED (for single values containing semicolons)
+ * cmakeify("clang;lld")
+ * // Returns: { type: 'STRING', value: 'clang\\;lld' }
+ * // Produces: -DVAR:STRING=clang\;lld
+ *
+ * @example
+ * // Array - NOT escaped (for CMake lists)
+ * cmakeify(["clang", "lld"])
+ * // Returns: { type: 'STRING', value: 'clang;lld' }
+ * // Produces: -DVAR:STRING=clang;lld (a proper CMake list)
+ */
+export function cmakeify(value: (string | boolean | number | string[] | CMakeValue)): CMakeValue {
+    const ret: CMakeValue = {
+        type: 'UNKNOWN',
+        value: ''
+    };
+    if (value === true || value === false) {
+        ret.type = 'BOOL';
+        ret.value = value ? 'TRUE' : 'FALSE';
+    } else if (isString(value)) {
+        ret.type = 'STRING';
+        // String values have semicolons escaped to prevent CMake list interpretation
+        ret.value = replaceAll(value, ';', '\\;');
+    } else if (typeof value === 'number') {
+        ret.type = 'STRING';
+        ret.value = value.toString();
+    } else if (value instanceof Array) {
+        ret.type = 'STRING';
+        // Array values are joined with semicolons WITHOUT escaping to form CMake lists
+        ret.value = value.join(';');
+    } else if (Object.getOwnPropertyNames(value).filter(e => e === 'type' || e === 'value').length === 2) {
+        ret.type = value.type;
+        ret.value = value.value;
+    } else {
+        // Note: This error message is not localized because this module must remain
+        // free of vscode-nls dependencies to support import in backend unit tests.
+        // This error is rare (only occurs with malformed input) and primarily aids debugging.
+        throw new Error(`Invalid value to convert to cmake value: ${JSON.stringify(value)}`);
+    }
+    return ret;
+}

src/drivers/cmakeDriver.ts

@@ -1848,7 +1848,7 @@ export abstract class CMakeDriver implements vscode.Disposable {
         }
         if (this._kit.cmakeSettings) {
             util.objectPairs(this._kit.cmakeSettings)
-                .forEach(([key, value]) => settingMap[key] = util.cmakeify(value as string));
+                .forEach(([key, value]) => settingMap[key] = util.cmakeify(value));
         }
 
         return util.objectPairs(settingMap).map(([key, value]) => {

src/kits/kit.ts

@@ -105,9 +105,11 @@ export interface Kit extends KitDetect {
     preferredGenerator?: CMakeGenerator;
 
     /**
-     * Additional settings to pass to CMake
+     * Additional settings to pass to CMake.
+     * Values can be strings or string arrays. String arrays are joined with
+     * semicolons to form CMake lists (without escaping).
      */
-    cmakeSettings?: { [key: string]: string };
+    cmakeSettings?: { [key: string]: string | string[] };
 
     /**
      * Additional environment variables for the kit

src/util.ts

@@ -280,43 +280,9 @@ export function product<T>(arrays: T[][]): T[][] {
         [[]] as T[][]);
 }
 
-export interface CMakeValue {
-    type: ('UNKNOWN' | 'BOOL' | 'STRING' | 'FILEPATH' | 'PATH' | '');  // There are more types, but we don't care ATM
-    value: string;
-}
-
-/**
- * Converts a given value to a CMake-compatible value.
- * The function determines the type of the input value and converts it to a corresponding CMakeValue object.
- * @param value The value to convert. It can be a string, boolean, number, string array, or CMakeValue.
- * @returns A CMakeValue object with the appropriate type and value.
- * @throws An error if the input value is invalid or cannot be converted to a CMakeValue.
- */
-export function cmakeify(value: (string | boolean | number | string[] | CMakeValue)): CMakeValue {
-    const ret: CMakeValue = {
-        type: 'UNKNOWN',
-        value: ''
-    };
-    if (value === true || value === false) {
-        ret.type = 'BOOL';
-        ret.value = value ? 'TRUE' : 'FALSE';
-    } else if (isString(value)) {
-        ret.type = 'STRING';
-        ret.value = replaceAll(value, ';', '\\;');
-    } else if (typeof value === 'number') {
-        ret.type = 'STRING';
-        ret.value = value.toString();
-    } else if (value instanceof Array) {
-        ret.type = 'STRING';
-        ret.value = value.join(';');
-    } else if (Object.getOwnPropertyNames(value).filter(e => e === 'type' || e === 'value').length === 2) {
-        ret.type = value.type;
-        ret.value = value.value;
-    } else {
-        throw new Error(localize('invalid.value', 'Invalid value to convert to cmake value: {0}', JSON.stringify(value)));
-    }
-    return ret;
-}
+// Re-export CMakeValue types and function from the pure module (no vscode dependency)
+// This allows backward compatibility for existing imports from @cmt/util
+export { CMakeValue, cmakeify } from '@cmt/cmakeValue';
 
 /**
  * Terminates a child process and its descendant processes.

test/unit-tests/backend/cmakeify.test.ts

@@ -0,0 +1,96 @@
+import { expect } from 'chai';
+import { cmakeify, CMakeValue } from '@cmt/cmakeValue';
+
+/**
+ * Tests for the cmakeify function that converts values to CMake cache variable format.
+ *
+ * This tests the REAL implementation from @cmt/cmakeValue (not a mirrored copy).
+ * The cmakeValue module is pure TypeScript with no vscode dependencies, making it
+ * safe to import in backend tests.
+ *
+ * Key behavior tested:
+ * - String values have semicolons ESCAPED (`;` → `\;`) to prevent CMake list interpretation
+ * - Array values are joined with semicolons WITHOUT escaping to form CMake lists
+ */
+
+suite('[cmakeify]', () => {
+
+    test('Boolean true converts to BOOL TRUE', () => {
+        const result = cmakeify(true);
+        expect(result.type).to.equal('BOOL');
+        expect(result.value).to.equal('TRUE');
+    });
+
+    test('Boolean false converts to BOOL FALSE', () => {
+        const result = cmakeify(false);
+        expect(result.type).to.equal('BOOL');
+        expect(result.value).to.equal('FALSE');
+    });
+
+    test('Simple string converts to STRING', () => {
+        const result = cmakeify('hello');
+        expect(result.type).to.equal('STRING');
+        expect(result.value).to.equal('hello');
+    });
+
+    test('String with semicolon is escaped', () => {
+        const result = cmakeify('clang;lld');
+        expect(result.type).to.equal('STRING');
+        expect(result.value).to.equal('clang\\;lld');
+    });
+
+    test('Number converts to STRING', () => {
+        const result = cmakeify(42);
+        expect(result.type).to.equal('STRING');
+        expect(result.value).to.equal('42');
+    });
+
+    test('String array joins with semicolons without escaping', () => {
+        const result = cmakeify(['clang', 'lld']);
+        expect(result.type).to.equal('STRING');
+        expect(result.value).to.equal('clang;lld');
+    });
+
+    test('String array with multiple elements creates CMake list', () => {
+        const result = cmakeify(['clang', 'lld', 'compiler-rt', 'libcxx']);
+        expect(result.type).to.equal('STRING');
+        expect(result.value).to.equal('clang;lld;compiler-rt;libcxx');
+    });
+
+    test('Empty array produces empty string', () => {
+        const result = cmakeify([]);
+        expect(result.type).to.equal('STRING');
+        expect(result.value).to.equal('');
+    });
+
+    test('Single element array produces single value', () => {
+        const result = cmakeify(['clang']);
+        expect(result.type).to.equal('STRING');
+        expect(result.value).to.equal('clang');
+    });
+
+    test('CMakeValue passthrough preserves type and value', () => {
+        const input: CMakeValue = { type: 'FILEPATH', value: '/path/to/file' };
+        const result = cmakeify(input);
+        expect(result.type).to.equal('FILEPATH');
+        expect(result.value).to.equal('/path/to/file');
+    });
+
+    test('LLVM_ENABLE_PROJECTS use case - array notation avoids escaping', () => {
+        // This is the main use case from issue #4503
+        const result = cmakeify(['clang', 'lld']);
+        expect(result.type).to.equal('STRING');
+        // Array notation should NOT escape semicolons - they are joined directly
+        expect(result.value).to.equal('clang;lld');
+        // This would produce: -DLLVM_ENABLE_PROJECTS:STRING=clang;lld
+    });
+
+    test('LLVM_ENABLE_PROJECTS use case - string notation escapes semicolons', () => {
+        // When using string notation, semicolons are escaped
+        const result = cmakeify('clang;lld');
+        expect(result.type).to.equal('STRING');
+        // String notation DOES escape semicolons
+        expect(result.value).to.equal('clang\\;lld');
+        // This would produce: -DLLVM_ENABLE_PROJECTS:STRING=clang\;lld
+    });
+});