Catboy for Visual Studio Code

A Visual Studio Code extension that provides build system integration for the Catboy C build system.

Features

Project Discovery: Automatically discovers Catboy projects in your workspace by scanning for build.yaml files
YAML Pre-processor (YPP) Support: Full integration with Catboy's YPP module for split YAML configurations using $include directives
Interactive CodeLens for $include: Clickable links above include directives with full internationalization support
Tree View Interface: Displays all projects and their targets in a hierarchical tree view
Enhanced Navigation: Go-to-file functionality navigates to original YAML files where targets were defined, even in split configurations
Build Actions: Quick access buttons for build, clean, and rebuild operations
Terminal Integration: Executes Catboy commands directly in the VS Code integrated terminal
Status Bar Integration: Shows current target and build progress in the status bar
Error Handling: Comprehensive validation and error reporting for build.yaml files
Command Palette: Quick target selection and output viewing via command palette
Smart Terminal Management: Reuses terminals per target for better organization
Automatic YPP Processing: Intelligently processes YPP when YAML files change, with graceful fallback
Multilingual Support: Complete English and Simplified Chinese translations with runtime language switching

Requirements

Catboy build system installed and available in your PATH
Visual Studio Code 1.74.0 or higher

Installation

Install the extension from the Visual Studio Code Marketplace
Ensure the catboy executable is available in your system PATH, or configure the executable path in settings

Usage

Opening the Catboy View

Click on the Catboy icon in the Activity Bar (left sidebar) to open the Catboy projects view.

Project Structure

The extension recognizes projects defined in build.yaml files with the following structure:

name: my-project

targets:
  my-target:
    build:
      type: executable
      sources:
        c:
          - src/main.c
          - src/*.c
      includes:
        - include
      defines:
        - DEBUG=1
      links:
        - pthread
      flags:
        c: -Wall -Wextra -g

YPP (YAML Pre-processor) Support

The extension fully supports Catboy's YPP module for split YAML configurations. You can use $include directives to organize your build configurations across multiple files:

name: my-project

# Include platform configurations
platforms:
  $include: platforms/*.yaml

targets:
  # Pattern 1: Full target definition (no includes)
  simple-app:
    build:
      type: executable
      sources:
        c: ["src/main.c"]
  
  # Pattern 2: Target with build content included
  complex-app:
    build:
      type: executable
      $include: configs/complex-build.yaml
      sources:
        c: ["src/main.c", "src/utils.c"]
  
  # Pattern 3: Whole targets included from separate files
  $include: targets/library-targets.yaml

The extension automatically runs catboy ypp to process includes and uses the generated metadata for precise navigation to original source files.

Interactive CodeLens for $include Directives

The extension provides interactive CodeLens features for $include directives in YAML files:

Clickable Links: Links appear above each $include line (similar to Git merge editor)
Smart Resolution: Single files open directly; multiple files show selection menu
Visual Feedback: File paths have underline decorations and hover tooltips
F12 Navigation: Use "Go to Definition" (F12) on include paths for quick navigation
Error Handling: Missing files display "⚠️ File not found" with appropriate styling
Multilingual: All text adapts to your language setting (English/中文简体)

Example CodeLens display:

Single file: "📄 Open YAML File" / "📄 打开 YAML 文件"
Multiple files: "📁 3 files (click to choose)" / "📁 3 个文件（点击选择）"
Missing file: "⚠️ File not found" / "⚠️ 文件未找到"

Available Actions

Each target in the tree view provides three action buttons:

Build (⚙️): Executes catboy build -v -f <yaml-file>
Clean (🗑️): Executes catboy clean -v -f <yaml-file>
Rebuild (🔄): Executes catboy rebuild -v -f <yaml-file>

Build Error Integration

The extension provides seamless integration with VS Code's Problems panel and enhanced visual feedback:

Automatic Error Detection: GCC compiler errors and warnings are automatically parsed from build output
Problems Panel: Build errors appear in the Problems panel with file, line, and column information
Full-line Background Highlighting:
- Red background for entire lines with errors
- Yellow background for entire lines with warnings
Error Squiggles: Red squiggly lines appear under specific error locations
Clickable Build Output: Error lines in the build output log are clickable links that jump directly to the error location in your code
Hover Tooltips: Hover over highlighted lines to see error messages
Click Navigation: Click on problems to jump directly to the error location
Auto-Clear: Problems panel and highlighting clear automatically when starting a new build
Conflict Protection: Robust diagnostics management prevents other extensions from clearing Catboy build errors
Multi-file Support: Errors are highlighted across all files in your project

Additional Features

Status Bar: Shows the currently selected target and build progress
Command Palette: Access Catboy: Select Target and Catboy: Show Output commands
Output Channel: View detailed logs and error messages in the "Catboy" output channel
Auto-refresh: Automatically detects changes to build.yaml files and refreshes the view

Extension Settings

This extension contributes the following settings:

catboy.executablePath: Path to the Catboy executable. If not specified, the extension will use catboy from PATH.
catboy.showYamlFiles: Show build.yaml file entries in the project tree view (default: false). Can also be toggled via the button in the tree view header.
catboy.verboseBuild: Enable verbose build output by including the -v flag in catboy commands (default: true).
catboy.clearConsoleOnBuild: Clean console automatically on build/clean/rebuild operations (default: true).
catboy.language: Override the extension language display (default: auto). Supports English and Simplified Chinese (zh-hans).

Known Issues

None currently known. Please report any issues on the GitHub repository.

Release Notes

0.2.7

Optimized package size by excluding development files:

Reduced Package Size: Excluded internal documentation and test files from VSIX package
Cleaner Distribution: Removed PUBLISHING-CHECKLIST.md, CLAUDE.md, CLICKABLE-LINKS-DEMO.md, and ICON-REQUIREMENTS.md
Optimized Build: VSIX package now contains only essential runtime files

0.2.6

Fixed $include path resolution on Windows and enhanced CodeLens display:

Fixed Windows Path Resolution: Corrected path resolution for $include directives on Windows systems
Enhanced CodeLens Display: Single file includes now show the actual filename (e.g., "Open config.yaml") instead of generic "Open YAML File"
Improved Glob Pattern Handling: Better handling of glob patterns in include paths (e.g., ../../path/*.yaml)
Updated Localization: Added new localization strings for improved file display in both English and Chinese

0.2.5

Updated build system configuration format and enhanced internationalization:

Project Property Update: Updated to use 'project' instead of 'name' property in build.yaml files (follows Catboy build system update)
Nested Project Path Fix: Fixed clickable error links for nested project structures - now correctly resolves relative file paths using project directory instead of workspace folder
Enhanced Chinese Localization: Added comprehensive zh-hans translations for build error messages, validation errors, and user dialogs
Build Error Messages: Localized "Found X error(s) and Y warning(s)", "Build failed", and validation messages
Backward Compatibility: Projects using old 'name:' property will show validation errors with helpful guidance

0.2.4

Fixed clickable links and improved diagnostics management:

Fixed Clickable Build Output: Corrected file path links to use VS Code's native detection
Improved Diagnostics Protection: Added robust conflict prevention for Problems panel
Automatic Path Conversion: Relative paths converted to absolute for proper link detection
5-Second Monitoring: Automatic restoration of cleared diagnostics

0.2.3

Enhanced error visualization with full-line highlighting and clickable build output:

Build Error Integration: Complete integration with VS Code's Problems panel for GCC compiler errors and warnings
Full-line Background Highlighting: Red backgrounds for error lines, yellow backgrounds for warning lines
Clickable Build Output: Error lines in build logs are now clickable links that jump directly to the error location
Enhanced Visual Feedback: Hover tooltips, overview ruler markers, and multi-file error tracking
Conflict Protection: Robust diagnostics management prevents other extensions from clearing build errors
Custom Build Execution: Direct command execution with real-time output capture for precise error parsing

0.2.2

Enhanced build experience with automatic console clearing:

Clear Console Setting: New catboy.clearConsoleOnBuild setting to automatically clear terminal before build operations
Improved Workflow: Cleaner build output by removing previous build results before each new operation
Internationalization: Full support for the new setting in both English and Simplified Chinese

0.2.1

Interactive CodeLens with comprehensive internationalization:

CodeLens for $include: Clickable links above include directives with smart file resolution and error handling
Full Internationalization: Complete Simplified Chinese support for all CodeLens text and interactive elements
Interactive Features: Hover tooltips, F12 navigation, underline decorations, and multi-file selection menus
Comprehensive Testing: Two complete test projects (i18n-test-project, edge-case-test-project) with detailed validation instructions
Advanced Path Resolution: Support for glob patterns, Unicode filenames, special characters, and complex directory structures

0.2.0

YAML Pre-processor (YPP) support and enhanced navigation:

YPP Integration: Complete support for Catboy's YAML pre-processor with $include directives for split configurations
Enhanced Go-to-File: Navigate directly to original YAML files where targets were defined, even across split files
Automatic YPP Processing: Intelligent processing and file watching with graceful fallback for projects not using YPP
YPP Test Project: Comprehensive sample demonstrating all three YPP include patterns
Icon Consistency: Fixed target selection popup icons to match project tree view
Packaging Improvements: Reduced extension size by excluding sample directory from distribution

0.1.10

Internationalization and verbose build configuration:

Simplified Chinese Support: Added comprehensive zh-hans translations for the entire extension interface
Language Override: Custom language selection via "Catboy: Change Language" command, independent of VS Code's system language
Verbose Build Toggle: New configurable setting to control the -v flag in catboy commands (defaults to enabled)
Multilingual UI: All buttons, tooltips, status messages, and error dialogs now support Chinese localization

0.1.9

Bug fixes and UX improvements:

Fixed Extension Test: Corrected publisher ID in extension test suite
Enhanced Target Selection: Target selection dialog now shows user-friendly target type names
Current Target Indication: Selected target is now highlighted with checkmark and pre-selected in quick pick

0.1.8

Enhanced activity bar icon and attribution:

New Cat Icon: Replaced generic gear icon with custom cat SVG for better brand identity
Theme-Adaptive Design: Monotone cat icon optimized for VS Code's light and dark themes
Resource Cleanup: Removed unused SVG files to reduce extension size
Proper Attribution: Added CC Attribution License for cat icon sourced from SVG Repo

0.1.7

Comprehensive workflow enhancements and navigation improvements:

Go-to-File Navigation: Jump directly to YAML files and target definitions from tree view
Current Target System: Set and visually track the active build target with green highlighting
Status Bar Controls: Quick Build/Clean/Rebuild buttons for the current target
Enhanced Context Menu: Organized right-click menu with logical command grouping

0.1.6

Enhanced UI controls and visual improvements:

Toggle YAML files: New button to show/hide build.yaml entries in tree view
Configurable display: Persistent setting for YAML file visibility (default: hidden)
Better visual hierarchy: Projects use blue folder icons with target counts
Improved icons: Updated build button (tools) and static library (file-zip) icons

0.1.5

Target type visualization and improved UX:

Target type-based icons: Different icons for executables, libraries, object files, and Luna BSP targets
Target type labels: Dimmed type descriptions (e.g., "Executable", "Dynamic Link Library") shown after target names
Enhanced target selection: Dropdown shows type-specific icons and information
Consistent icon colors: All target icons use neutral/white coloring for visual consistency

0.1.4

Enhanced tree view and build management:

New build file tree level: Shows build.yaml files between projects and targets for better organization
Build all targets: Build file entries can build/clean/rebuild all targets at once
Improved path display: Consistent forward slash separators across all platforms
Better visual hierarchy: File icons and dimmed filenames for clearer navigation

0.1.3

Bug fixes and UI improvements:

Fixed duplicate targets bug: Resolved issue where targets would appear duplicated when refreshing
Added alphabetical sorting: Projects and targets now display in consistent alphabetical order
Improved state management: Better handling of project discovery during refresh operations

0.1.2

Bug fixes and stability improvements:

Fixed extension activation issues: Extension now activates properly in all environments
Resolved dependency problems: Replaced external YAML dependency with lightweight custom parser
Improved reliability: Commands are now always registered and available
Better error handling: Enhanced logging for troubleshooting activation issues

0.1.1

Enhanced user experience improvements:

Status bar integration with build progress indicators
Smart terminal management with per-target reuse
Comprehensive error handling and validation
Command palette integration for quick target selection

0.1.0

Initial release of Catboy for Visual Studio Code:

Project discovery from build.yaml files
Tree view with projects and targets
Build, clean, and rebuild actions
Terminal integration for command execution

Development

Prerequisites

Node.js 16.x or higher
npm 7.x or higher
Visual Studio Code

Setup

Clone the repository:

git clone https://github.com/catboy-build/catboy-for-vscode.git
cd catboy-for-vscode

Install dependencies:

npm install

Compile the extension:

npm run compile

Running the Extension

Open the project in Visual Studio Code
Press F5 to launch a new VS Code window with the extension loaded
Open a folder containing a build.yaml file
Click on the Catboy icon in the Activity Bar to see your projects

Testing

Development Testing

Run the extension in development mode:

# Open the project in VSCode
code .

# Press F5 to launch Extension Development Host
# This opens a new VSCode window with the extension loaded

Test with sample project:
- In the Extension Development Host, open the sample/ folder
- Look for the Catboy icon in the Activity Bar
- Verify projects and targets appear in the tree view
Test mock Catboy (optional):
- Configure executable path in settings to point to sample/mock-catboy.bat (Windows) or sample/mock-catboy.sh (Unix/Mac)
- Test build commands without installing actual Catboy

Automated Tests

Run the test suite:

npm test

Manual Testing Checklist

[ ] Extension icon appears in Activity Bar
[ ] Tree view shows projects and targets from build.yaml files
[ ] Build/Clean/Rebuild buttons execute commands in terminal
[ ] Status bar shows selected target
[ ] Command palette commands work (Ctrl+Shift+P → "Catboy")
[ ] Output channel shows project discovery logs
[ ] File changes trigger automatic refresh
[ ] Error handling displays warnings for invalid YAML files

Building for Production

Create a VSIX package:

npm install -g vsce
vsce package

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests on the GitHub repository.

License

This extension is licensed under the MIT License. See the LICENSE file for details.

Icon Attribution

The cat icon used in this extension is sourced from SVG Repo and is licensed under CC Attribution License.

Catboy Build System

Catboy