Simplifying C Development: A Lightweight Solution for LSP Support

Modern C development shouldn't require learning complex build systems just to get basic editor features working. If you've ever struggled with setting up CMake or wrestling with heavy tooling like bear just to generate a compile_commands.json file, there's now a simpler way.

The Problem with Current Solutions

Today's editors and Language Server Protocol (LSP) implementations need a compile_commands.json file to provide essential features like syntax highlighting, error checking, code completion, and go-to-definition. Unfortunately, generating this file typically means:

- Setting up CMake for simple projects (overkill)
- Installing heavy tools like bear or compiledb
- Learning complex build system syntax
- Dealing with build system quirks and edge cases

For small to medium C projects, personal experiments, or learning projects, this overhead is frustrating and unnecessary.

A Lightweight Alternative

The compile-commands utility takes a refreshingly simple approach. Instead of forcing you into a full build system, it lets you describe your project structure in a straightforward YAML file and generates the exact JSON that LSP servers require.

Here's how simple it is:

yaml
project:
  name: my-project
  language: c
  standard: c99

compiler:
  flags: ["-Wall", "-Wextra", "-g"]
  defines: ["_GNU_SOURCE"]

source_groups:
  - name: main
    source_dirs: ["src/"]
    include_dirs: ["include/"]

Run python generate_compile_commands.py and you're done. Your editor now has everything it needs for intelligent C language support.

Key Features

The tool's strength lies in its source groups concept. Different parts of your project often need different include paths - main code might only need project headers, while tests require both project headers and test utilities. Source groups handle this elegantly:

yaml
source_groups:
  - name: tests
    source_dirs: ["tests/"]
    include_dirs: ["include/", "tests/"]
    flags: ["-DTESTING"]

The utility scans your source directories, maps each .c file to its appropriate compilation context, and generates a complete compile_commands.json file. No actual compilation happens - just the metadata generation that LSP servers need.

Perfect for the Right Projects

This tool shines for small to medium C projects, prototypes, hobby projects, and learning exercises. It embraces the Unix philosophy: do one thing well. While it won't replace CMake for complex codebases with intricate build requirements, it eliminates unnecessary complexity for straightforward projects.

Sometimes the simplest solution really is the best solution.

Try it out: github.com/qa3-tech/compile-commands