CMake Companion

A VS Code extension for resolving CMake variable paths (like ${MY_WORKSPACE_PATH}/path/file.h) with underline decoration, hover tips, and click-to-navigate functionality.

Features

• Syntax Highlighting: Rich syntax highlighting for CMake files including commands, variables, strings, comments, and generator expressions
• Semantic Tokens: Enhanced semantic highlighting that distinguishes between different variable types (built-in, user-defined, environment, cache)
• Smart Completions: Intelligent code completions for CMake commands, variables, and paths
• Go to Definition: Navigate to variable and macro/function definitions with one click
• Diagnostics: Real-time error and warning diagnostics for CMake files
• Code Folding: Fold CMake blocks (if/endif, function/endfunction, etc.) for better code readability
• Document Links: Clickable links for include() paths and file references
• Document Formatting: Format CMake files with configurable indentation, command casing, and parentheses spacing
• Underline Decoration: CMake paths with variables are underlined and clickable
• Hover Tips: Hover over CMake paths to see the resolved path and file existence status
• Click to Navigate: Ctrl+Click (Cmd+Click on Mac) to jump directly to the resolved file
• Variable Resolution: Automatic parsing of set() commands in CMakeLists.txt and .cmake files, including files reached via include()
• Built-in Variables: Support for common CMake variables like PROJECT_SOURCE_DIR, CMAKE_SOURCE_DIR, CMAKE_CURRENT_SOURCE_DIR, etc. Directory variables are resolved per file
• Environment and cache paths: $ENV{VAR}/... and $CACHE{VAR}/... can be hovered and Ctrl+Clicked
• Nested Variables: Recursive resolution of nested variable references
• Custom Variables: Define custom variable mappings in VS Code settings
• vcxproj to CMake Conversion: Convert Visual Studio project files (.vcxproj) to CMakeLists.txt with one click
• Xcode to CMake Conversion: Convert Xcode project files (.xcodeproj) to CMakeLists.txt with one click

Supported File Types

• CMakeLists.txt — Full language support (highlighting, completions, diagnostics, navigation)
• *.cmake — Full language support
• *.vcxproj — Conversion to CMakeLists.txt
• *.xcodeproj — Conversion to CMakeLists.txt

Usage

1. Open a workspace containing CMakeLists.txt files
2. Open a CMake file (CMakeLists.txt or *.cmake) to parse its variable definitions
3. CMake variable paths will be underlined
4. Hover over a path to see the resolved value
5. Ctrl+Click to navigate to the resolved file

Commands

• Resolve CMake Path: Manually resolve a CMake path expression
• Refresh CMake Variables: Re-scan the workspace for CMake variable definitions (follows include())
• Convert vcxproj to CMake: Convert a Visual Studio project file (.vcxproj) to CMakeLists.txt
• Convert Xcode project to CMake: Convert an Xcode project (.xcodeproj) to CMakeLists.txt

Formatting

To format a CMake document:

• Right-click and select "Format Document"
• Use the keyboard shortcut (Shift+Alt+F on Windows/Linux, Shift+Option+F on Mac)
• Enable "Format on Save" in VS Code settings

Converting Visual Studio Projects to CMake

To convert a .vcxproj file to CMakeLists.txt:

1. Right-click on a .vcxproj file in the Explorer panel and select "Convert vcxproj to CMake"
2. Or open a .vcxproj file and use the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) to run "Convert vcxproj to CMake"
3. The extension will parse the project file and generate a CMakeLists.txt in the same directory

The conversion automatically extracts:

• Project name and type (executable, static library, or shared library)
• Source files (.cpp, .c, etc.)
• Header files (.h, .hpp, etc.)
• Include directories
• Preprocessor definitions
• Library dependencies
• C++ language standard (CMAKE_CXX_STANDARD from LanguageStandard)
• Windows SDK version (CMAKE_SYSTEM_VERSION from WindowsTargetPlatformVersion)
• Platform toolset (informational comment)
• Character set (UNICODE/_UNICODE or _MBCS definitions)
• Subsystem (WIN32_EXECUTABLE property for Windows GUI applications)
• Precompiled headers (PCH) - converted to CMake's target_precompile_headers (requires CMake 3.16+)
  • PCH header file configuration
  • PCH source file that creates the precompiled header
  • Per-file exclusions from PCH (files marked as "Not Using Precompiled Headers")
• Build events - converted to CMake's add_custom_command
  • Pre-build events (PRE_BUILD)
  • Pre-link events (PRE_LINK)
  • Post-build events (POST_BUILD)
  • Custom build steps

Note: The generated CMakeLists.txt is a starting point and may require manual adjustments for complex projects with custom build configurations.

Converting Xcode Projects to CMake

To convert an Xcode project to CMakeLists.txt:

1. Right-click on a .xcodeproj directory in the Explorer panel and select "Convert Xcode project to CMake"
2. Or use the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) to run "Convert Xcode project to CMake"
3. The extension will parse the project.pbxproj file and generate a CMakeLists.txt in the parent directory

The conversion automatically extracts:

• Project name and type (executable, static library, or shared library)
• Source files (.cpp, .c, .m, .mm, etc.)
• Header files (.h, .hpp, etc.)
• Include directories (HEADER_SEARCH_PATHS)
• Preprocessor definitions (GCC_PREPROCESSOR_DEFINITIONS)
• Linked frameworks and libraries
• C++ language standard (CLANG_CXX_LANGUAGE_STANDARD)
• macOS deployment target (MACOSX_DEPLOYMENT_TARGET)
• Architecture settings (ARCHS)
• Compiler flags (OTHER_CPLUSPLUSFLAGS, OTHER_CFLAGS)
• Linker flags (OTHER_LDFLAGS)
• Library search paths (LIBRARY_SEARCH_PATHS)
• Configuration-specific settings (Debug/Release)
• Shell script build phases - converted to CMake's add_custom_command
  • Run Script phases with inputs and outputs
  • Pre-build and post-build scripts

Note: The generated CMakeLists.txt is a starting point and may require manual adjustments for complex projects with custom build configurations or schemes.

Configuration

Custom Variables

You can define custom variable mappings in your VS Code settings:

{
  "cmake-companion.customVariables": {
    "MY_WORKSPACE_PATH": "/path/to/workspace",
    "THIRD_PARTY_DIR": "/path/to/third_party"
  }
}

Enabled File Types

Configure which file types should have CMake path resolution enabled:

{
  "cmake-companion.enabledFileTypes": ["cmake"]
}

Formatting Options

Configure document formatting behavior:

{
  "cmake-companion.formatting.style": "google",
  "cmake-companion.formatting.maxLineLength": 0,
  "cmake-companion.formatting.spaceAfterOpenParen": false,
  "cmake-companion.formatting.spaceBeforeCloseParen": false,
  "cmake-companion.formatting.uppercaseCommands": false
}

• style: Formatting style preset. Available styles: "default", "google", "llvm", "mozilla", "microsoft", "gnu", "webkit", "kde"
• maxLineLength: Maximum line length (0 = no limit). Overrides the style preset value when set.
• spaceAfterOpenParen: Add space after opening parenthesis in commands. Overrides the style preset value when set.
• spaceBeforeCloseParen: Add space before closing parenthesis in commands. Overrides the style preset value when set.
• uppercaseCommands: Convert CMake command names to uppercase. Overrides the style preset value when set.

Formatting Style Presets

The following style presets are available. Individual options (e.g., maxLineLength, uppercaseCommands) override the preset values when explicitly set.

To use a style preset:

{
  "cmake-companion.formatting.style": "google"
}

Built-in Variables

The following CMake built-in variables are automatically set based on your workspace:

• CMAKE_SOURCE_DIR - Root of the workspace
• CMAKE_CURRENT_SOURCE_DIR - Current directory being processed
• PROJECT_SOURCE_DIR - Root of the project
• CMAKE_BINARY_DIR - Build directory (workspace/build)
• CMAKE_CURRENT_BINARY_DIR - Current build directory
• PROJECT_BINARY_DIR - Project build directory
• PROJECT_NAME - Name from project() command
• CMAKE_PROJECT_NAME - Project name

Syntax Highlighting

The extension provides syntax highlighting for:

• Commands: CMake commands like set(), if(), add_executable(), etc.
• Variables: ${VARIABLE}, $ENV{VARIABLE}, $CACHE{VARIABLE}
• Strings: Quoted strings with escape sequence support
• Comments: Line comments (#) and block comments (#[[ ]])
• Generator Expressions: $<...> syntax
• Keywords: CMake keywords like PUBLIC, PRIVATE, INTERFACE, ON, OFF, etc.
• Numbers: Numeric literals

Installation

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "CMake Companion"
4. Click Install

Development

# Install dependencies
npm install

# Compile
npm run compile

# Run tests (includes VS Code API mock tests)
npm run test:unit

# Lint
npm run lint

# Watch mode
npm run watch

# Package a .vsix locally
npm run package

Publishing

Marketplace publish is driven by GitHub Actions (same split as DumpStorm):

1. Put a Personal Access Token from VS Code Marketplace into the repo secret VSCE_PAT (Settings → Secrets and variables → Actions → New repository secret).
2. Commit the version bump, then push a tag matching package.json:

git tag v1.2.0
git push origin v1.2.0

3. Create Release builds the VSIX and creates a GitHub Release.
4. Publish to Marketplace runs when that release is published (skipped for alpha / beta / rc and GitHub pre-releases).
5. You can also run Publish to Marketplace manually from the Actions tab (workflow_dispatch).

License

MIT