Update documentation to clarify semicolon escaping behavior

[Copilot]

• Analyze the issue: Semicolons in cmake.configureSettings are being escaped
• Review issue comment suggesting documentation update instead of code change
• Revert code changes to src/util.ts and test/unit-tests/util.test.ts
• Update documentation in docs/cmake-settings.md to clarify semicolon escaping behavior
• Update changelog to reflect documentation change instead of bug fix
• Remove redundant phrase from documentation per reviewer feedback
• Move changelog entry to Bug Fixes section per reviewer feedback

Summary

Per the issue author's comment (#issuecomment-3385654002), the semicolon escaping is intentional behavior to prevent CMake from interpreting semicolons as list separators.

Solution: Updated documentation to clarify:

1. Semicolons (;) in string values are automatically escaped
2. To pass a CMake list, users should use array notation (e.g., "MY_LIST": [ "a", "b" ])

Files Changed:

• docs/cmake-settings.md - Clarified semicolon escaping behavior in cmake.configureSettings documentation
• CHANGELOG.md - Added entry in "Bug Fixes" section

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Bug] Incorrect escaping of semicolons in cmake.configureSettings</issue_title>
<issue_description>### Brief Issue Summary

When performing a CMake configure, cmake-tools incorrectly escapes semicolons. When setting up LLVM:

{
  "cmake.sourceDirectory": "${workspaceFolder}/runtimes",
  "cmake.configureSettings": {
      "LLVM_ENABLE_RUNTIMES" : "libc;compiler-rt",
      "LLVM_LIBC_FULL_BUILD" : true
  }
}

cmake-tools will configure with "-DLLVM_ENABLE_RUNTIMES:STRING=libc\;compiler-rt". However, it is unnecessary to escape the semicolon because the whole parameter is enclosed in quotes. The result is that the semicolon is passed through to CMake erroneously.

From the CMakeCache.txt file:

LLVM_ENABLE_RUNTIMES:STRING=libc\;compiler-rt

CMake Tools Diagnostics

{
  "os": "linux",
  "vscodeVersion": "1.104.3",
  "cmtVersion": "1.21.36",
  "configurations": [
    {
      "folder": "/workspaces/llvm-project",
      "cmakeVersion": "4.1.2",
      "configured": true,
      "generator": "Ninja",
      "usesPresets": false,
      "compilers": {
        "C": "/usr/bin/clang",
        "CXX": "/usr/bin/clang++"
      }
    }
  ],
  "cpptoolsIntegration": {
    "isReady": false,
    "hasCodeModel": false,
    "activeBuildType": "",
    "buildTypesSeen": [],
    "requests": [],
    "responses": [],
    "partialMatches": [],
    "targetCount": 0,
    "executablesCount": 0,
    "librariesCount": 0,
    "targets": []
  },
  "settings": [
    {
      "communicationMode": "automatic",
      "useCMakePresets": "auto",
      "configureOnOpen": true
    }
  ]
}

Debug Log

[main] Configuring project: llvm-project 
[main] Saving open files before configure/build
[expand] expanded ${workspaceFolder}/build
[driver] Start configure 
[driver] Running pre-configure checks and steps
[driver] Using compilers in Clang 21.1.3 x86_64-pc-linux-gnu for configure
[expand] expanded ${workspaceFolder}/build
[cmakefileapi-driver] Configuring using kit
[cmakefileapi-driver] Invoking CMake /usr/bin/cmake with arguments ["-DCMAKE_BUILD_TYPE:STRING=Debug","-DLLVM_ENABLE_RUNTIMES:STRING=libc\\;compiler-rt","-DLLVM_LIBC_FULL_BUILD:BOOL=TRUE","-DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=TRUE","-DCMAKE_C_COMPILER:FILEPATH=/usr/bin/clang","-DCMAKE_CXX_COMPILER:FILEPATH=/usr/bin/clang++","-Wno-dev","--no-warn-unused-cli","-S","/workspaces/llvm-project/runtimes","-B","/workspaces/llvm-project/build","-G","Ninja"]
[proc] Executing command: /usr/bin/cmake -DCMAKE_BUILD_TYPE:STRING=Debug "-DLLVM_ENABLE_RUNTIMES:STRING=libc\;compiler-rt" -DLLVM_LIBC_FULL_BUILD:BOOL=TRUE -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=TRUE -DCMAKE_C_COMPILER:FILEPATH=/usr/bin/clang -DCMAKE_CXX_COMPILER:FILEPATH=/usr/bin/clang++ -Wno-dev --no-warn-unused-cli -S /workspaces/llvm-project/runtimes -B /workspaces/llvm-project/build -G Ninja
[proc]   with environment: {"GITHUB_TOKEN":"","GIT_COMMITTER_NAME":"GitHub","GITHUB_CODESPACE_TOKEN":"","USER":"vscode","FEATURE_SPARK_POST_COMMIT_CREATE_ITERATION":"true","HOSTNAME":"codespaces-1bbd91","SHLVL":"1","GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN":"app.github.dev","HOME":"/home/vscode","OLDPWD":"/","LESS":"-R","CODESPACES":"true","ZSH":"/home/vscode/.oh-my-zsh","LSCOLORS":"Gxfxcxdxbxegedabagacad","PAGER":"less","GITHUB_GRAPHQL_URL":"https://api.github.com/graphql","GITHUB_USER":"kaladron","ContainerVersion":"13","LOGNAME":"vscode","GITHUB_API_URL":"https://api.github.com","RepositoryName":"llvm-project","_":"/usr/bin/cat","CLOUDENV_ENVIRONMENT_ID":"685acd55-6425-4176-bfe4-8f0aefff87b1","PATH":"/vscode/bin/linux-x64/385651c938df8a906869babee516bffd0ddb9829/bin/remote-cli:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/vcpkg:/home/vscode/.local/bin","SHELL_LOGGED_IN":"true","LS_COLORS":"","GITHUB_REPOSITORY":"kaladron/llvm-project","SHELL":"/bin/zsh","CXX":"clang++","VCPKG_ROOT":"/usr/local/vcpkg","GIT_COMMITTER_EMAIL":"noreply@github.com","INTERNAL_VSCS_TARGET_URL":"https://uksouth.online.visualstudio.com","PWD":"/vscode/bin/linux-x64/385651c938df8a906869babee516bffd0ddb9829","GITHUB_SERVER_URL":"https://github.com","CC":"clang","CODESPACE_NAME":"stunning-waddle-q6qvj4xp5h9j44","VCPKG_DOWNLOADS":"/usr/local/vcpkg-downloads","VSCODE_CWD":"/vscode/bin/linux-x64/385651c938df8a906869babee516bffd0ddb9829","VSCODE_NLS_CONFIG":"{\"userLocale\":\"en\",\"osLocale\":\"en\",\"resolvedLanguage\":\"en\",\"defaultMessagesFile\":\"/vscode/bin/linux-x64/385651c938df8a906869babee516bffd0ddb9829/out/nls.messages.json\",\"locale\":\"en\",\"availableLanguages\":{}}","VSCODE_HANDLES_SIGPIPE":"true","VSCODE_ESM_ENTRYPOINT":"vs/workbench/api/node/extensionHostProcess","VSCODE_HANDLES_UNCAUGHT_ERRORS":"true","BROWSER":"/vscode/bin/linux-x64/385651c938df8a906869babee516bffd0ddb9829/bin/helpers/browser.sh","ELECTRON_RUN_AS_NODE":"1","VSCODE_IPC_HOOK_CLI":"/tmp/vscode-ipc-55df85f6-72e8-43fb-b619-ec116feb96cc.sock","VSCODE_L...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes microsoft/vscode-cmake-tools#4585

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for you](https://github.com/microsoft/vscode-cmake-tools/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.

[snehara99]

@copilot you linked the wrong issue. this addresses issue #4693

[Copilot]

@copilot you linked the wrong issue. this addresses issue #4693

Fixed in 1abe4de - updated the changelog to reference issue #4693.

[snehara99]

@copilot in the changelog you linked the PR instead of the issue, but since this is a bug fix, the issue should be linked

[Copilot]

@copilot in the changelog you linked the PR instead of the issue, but since this is a bug fix, the issue should be linked

The changelog entry at line 10 already links to the issue URL (/issues/4693) not the PR URL. Current entry:

- Fix incorrect escaping of semicolons in cmake.configureSettings. [#4693](https://github.com/microsoft/vscode-cmake-tools/issues/4693)

[snehara99]

@copilot why were semicolons escaped in the first place? I'm worried we are introducing a regression

[snehara99]

@copilot in the changelog you linked the PR instead of the issue, but since this is a bug fix, the issue should be linked

The changelog entry at line 10 already links to the issue URL (/issues/4693) not the PR URL. Current entry:

- Fix incorrect escaping of semicolons in cmake.configureSettings. [#4693](https://github.com/microsoft/vscode-cmake-tools/issues/4693)

You are wrong. the issue is #4585

[Copilot]

@copilot why were semicolons escaped in the first place? I'm worried we are introducing a regression

The escaping was likely added as a precaution for shell interpretation of semicolons (which act as command separators in shells). However, looking at src/proc.ts, CMake execution uses Node.js spawn() with shell: false (line 188), which passes arguments directly to the process without shell interpretation.

The escaping was unnecessary because:

1. No shell involved: spawn() with shell: false bypasses the shell entirely
2. Arrays already worked: Array values were already joined with semicolons without escaping (line 312 in util.ts), and those worked correctly
3. The issue itself: Users reported the backslash appearing literally in CMakeCache.txt

The only regression risk would be if CMake execution used shell: true, but checking the codebase, shell mode is only used for preset scripts, debugger detection, and kit detection—not for passing configure arguments to CMake.

[Copilot]

@copilot in the changelog you linked the PR instead of the issue, but since this is a bug fix, the issue should be linked

The changelog entry at line 10 already links to the issue URL (`/is...

Fixed in e8d1440 - updated the changelog to reference issue #4585.

[snehara99]

@copilot take a look at this comment on the issue: #4585 (comment)

It implies that no changes are needed in the parsing. This requires only a documentation update. Can you revert your changes and only do the documentation update? You may have to update the changelog description. Can you also update the description and title of the PR accordingly as well?

[Copilot]

@copilot take a look at this comment on the issue: #4585 (comment)

It implies that no changes are needed in the parsing. This re...

Done in fd4e22c. I've:

1. Reverted the code changes to src/util.ts and test/unit-tests/util.test.ts
2. Updated documentation in docs/cmake-settings.md to clarify that semicolons are automatically escaped and array notation should be used for CMake lists
3. Moved the changelog entry from "Bug Fixes" to "Documentation"

[snehara99]

@copilot can you remove this part of the doc update "which will be passed as MY_LIST=a;b to CMake."

[Copilot]

@copilot can you remove this part of the doc update "which will be passed as MY_LIST=a;b to CMake."

Done in 026223f.

[snehara99]

looks good to me!

[snehara99]

@copilot can you add the changelog update to bug fixes instead of creating a documentation section?

[Copilot]

@copilot can you add the changelog update to bug fixes instead of creating a documentation section?

Done in fa212eb.