Add Setting

Adding a New Configuration Setting

Recipe for adding a new cmake.* setting to CMake Tools.

Files you must touch

| File | What to add |

|------|-------------|

| package.json | Setting declaration in contributes.configuration.properties |

| package.nls.json | English description string |

| src/config.ts | Interface property + EventEmitter + getter |

| docs/cmake-settings.md | Row in the settings table |

| CHANGELOG.md | Entry under the current version |

Step 1 — Declare the setting in package.json

Add an entry inside contributes.configuration.properties. Key format is cmake.<settingName>.

// package.json  →  contributes.configuration.properties
"cmake.myNewSetting": {
  "type": "boolean",
  "default": false,
  "description": "%cmake-tools.configuration.cmake.myNewSetting.description%",
  "scope": "resource"
}

Rules

• type — "boolean", "string", "number", "array", "object", or use "oneOf" for union types.
• default — always required.
• scope — use "resource" for project-specific settings (most common), "window" for global UI settings, "machine-overridable" for tool paths.
• description or markdownDescription — must use an NLS key, never a bare string.
• NLS key format: %cmake-tools.configuration.cmake.<settingName>.description% (wrapped in %).

Real example — cmake.saveBeforeBuild

"cmake.saveBeforeBuild": {
  "type": "boolean",
  "default": true,
  "description": "%cmake-tools.configuration.cmake.saveBeforeBuild.description%",
  "scope": "resource"
}

Step 2 — Add the English string to package.nls.json

Add the NLS key (without the % wrappers) and its English text:

"cmake-tools.configuration.cmake.myNewSetting.description": "Description of what this setting does."

> Do not modify any file under i18n/. Translations are handled separately.

Step 3 — Wire up src/config.ts (three changes)

3a — Add property to ExtensionConfigurationSettings

// src/config.ts  →  ExtensionConfigurationSettings interface
export interface ExtensionConfigurationSettings {
    // ... existing properties ...
    myNewSetting: boolean;
}

The type must match what you declared in package.json.

3b — Add EventEmitter to the emitters map

// src/config.ts  →  ConfigurationReader.emitters
private readonly emitters: EmittersOf<ExtensionConfigurationSettings> = {
    // ... existing emitters ...
    myNewSetting: new vscode.EventEmitter<boolean>(),
};

The emitter type parameter must match the interface property type.

3c — Add a getter

Simple pass-through getter (most settings):

get myNewSetting(): boolean {
    return this.configData.myNewSetting;
}

Getter with transformation logic (e.g., sourceDirectory normalizes to array):

get sourceDirectory(): string[] {
    if (!Array.isArray(this.configData.sourceDirectory)) {
        return [this.configData.sourceDirectory];
    }
    return this.configData.sourceDirectory;
}

Step 4 — Document in docs/cmake-settings.md

Add a row to the settings table. Keep alphabetical order.

| `cmake.myNewSetting` | Description of what this setting does. | `false` | no |

Table columns:

| Column | Content |

|--------|---------|

| Setting | Backtick-quoted cmake.<name> |

| Description | Plain-English description |

| Default value | Backtick-quoted default |

| Supports substitution | yes if ${variable} expansion applies, otherwise no |

Step 5 — Add a CHANGELOG entry

Add an entry under the current version in CHANGELOG.md, in the Features: or Improvements: section.

Verification checklist

• [ ] package.json — setting declared with correct type, default, scope, and NLS key
• [ ] package.nls.json — English string added
• [ ] src/config.ts — interface property, emitter, and getter all added
• [ ] docs/cmake-settings.md — table row added in alphabetical order
• [ ] CHANGELOG.md — entry added
• [ ] yarn compile succeeds (or npm run compile)
• [ ] No files under i18n/ were modified

*See also: .github/copilot-instructions.md for project-wide conventions.*