README.md

Malterlib VS Code Extension Documentation

Welcome to the comprehensive documentation for the Malterlib VS Code extension. This extension enhances VS Code with specialized support for Malterlib C++ development, implementing the official Malterlib Code Standard.

Official Malterlib Documentation

For complete details on Malterlib standards and conventions:

• Malterlib Code Standard - Complete coding standards
• Naming Conventions - Official naming prefix guide
• Coloring Standard - Color coding rationale and design

VS Code Extension Documentation

Getting Started

• Syntax Highlighting - TextMate grammar and language support
• Semantic Coloring - Intelligent identifier coloring based on Malterlib naming conventions

Build System Integration

• Build Integration - VS Code tasks, problem matchers, and automation

User Interface

• Status Bar Controls - Interactive status bar for build configuration
• Debug Configuration - Automatic LLDB setup and multi-target debugging
• Color Themes - Display P3 and sRGB optimized themes

Advanced Topics

• clangd Integration - Enhanced language features with clangd language server

Quick Reference

Essential Features

Feature	Description	Documentation
Semantic Coloring	Intelligent code coloring based on Malterlib naming conventions	Semantic Coloring
Status Bar Controls	Interactive build system configuration	Status Bar
Build Integration	Tasks, problem matchers, and automation	Build Integration
Debug Support	Automatic LLDB configuration and multi-target debugging	Debug Configuration
Color Themes	Optimized themes for different display technologies	Color Themes
clangd Integration	Enhanced language features and performance	clangd Integration

File Types Supported

Extension	Language ID	Description	Documentation
.cpp, .cc, .cxx	cpp	C++ implementation files	Syntax Highlighting
.h, .hpp, .hxx	cpp	C++ header files	Syntax Highlighting
.MBuildSystem, .MWorkspace, etc	malterlib-build	Malterlib build system files	Syntax Highlighting

Key Commands

Command	Description	Default Key
malterlib.selectGenerator	Choose build generator	None
malterlib.selectWorkspace	Choose workspace	None
malterlib.selectConfiguration	Choose configuration	None
malterlib.selectTarget	Choose target	None
malterlib.selectDebugTargets	Select multiple debug targets	None
malterlib.selectSingleDebugTarget	Select single debug target	None

Configuration Overview

Basic Settings

Essential extension settings for getting started:

{
    // Theme selection (automatically sets appropriate color space)
    "workbench.colorTheme": "Malterlib"  // or "Malterlib (sRGB)"
}

To enable richer LLDB formatting and automatic expansion of Malterlib types during debugging, create a file named .lldbinit in the root of your workspace containing the following line:

command script import "./Malterlib/Debug/Source/Malterlib_LLDB"

This imports the Malterlib LLDB Python helper so LLDB can present Malterlib-specific type summaries and pretty-printing during debug sessions.

### clangd Integration Settings

For mixed codebases that need coloring for non-Malterlib code (uses clangd's slower semantic highlighting):

```json
{
    // Disable extension semantic coloring (this is the default)
    "malterlib.enableSemanticColoring": false,
    
    // Use Malterlib-shipped clangd
    "clangd.path": "${workspaceFolder}/Binaries/MalterlibLLVM/HostPlatformArchitecture/bin/clangd",
    
    // Use Malterlib-shipped LLDB for debugging
    "lldb.library": "${workspaceFolder}/Binaries/MalterlibLLVM/HostPlatformArchitecture/lib/liblldb.dylib",
    
    // clangd arguments (optional)
    "clangd.arguments": [
        "--background-index",
        "--completion-style=detailed",
        "--header-insertion=iwyu"
    ]
}

Compatibility

VS Code: 1.80.0 or later Languages: C, C++ (C++11 through C++23) Build Systems: Malterlib build system Debuggers: LLDB