clip: CLI Project

This is really just a command wrapper around various commands to run at a project root level.

Originally it was to build/debug/run c++ stuff from an editor (emacs!), but there's no reason it should be tied to c++ or emacs.

Maybe it's more necessary for c++ since there's a lack of standard tooling. In some sense, this project is inspired by rust's cargo tool.

Intended Audience

Vim and Emacs support :make / M-x compile but those are rarely used to build a project. The intent is to provide a cli tool that runs some high level commands on a project basis that can be easily used from various editors. The configuration file to capture these commands can be persisted with the source.

Config File

Here's a sample configuration file using meson/ninja. This would be placed at the root of a project as .clip.yaml.

---
# parameters that will build this project
build:
  # Various "profiles"
  release:
    command: ninja -j@NUM_CORES_TO_USE@
    working_dir: build
  debug:
    command: ninja -j@NUM_CORES_TO_USE@
    working_dir: build-debug
  cross:
    command: ninja -j@NUM_CORES_TO_USE@
    working_dir: build-cross
  test:
    # Can set environment variables when running profiles
    env:
      BOOST_TESTS_TO_RUN: subset
    command: ninja test
    working_dir: build-debug

# run the "tests" binary with gdb in the "build-debug" directory
debug:
  program: tests
  working_dir: build-debug
  program_args:
  # "env" also supported here

# Process compile_commands.json file[s] in various ways to
# generate a new one to stdout
compile_commands:
  working_dir: build-debug
  # ignore_args:
  #   - args to ignore

  # additional_args:
  #   - args to add if missing

  # Option to override compilers
  compiler_overrides:
    gcc: /usr/local/bin/my-special-gcc
    g++: /usr/local/bin/my-special-g++

  # Filter compile_commands.json
  # {directory_,command_,file_,arguments_,output_}filter_regexes
  # filter_regexes:
  #   regex: replacement

  # You can specify more than one file that will get merged into one
  files:
    - compile_commands.json
    - compile_commands2.json

  # Some options to pass to clangd
  clangd:
    log_level: verbose
    query_driver: /usr/bin/**/clang-*
    #extra_args: --pretty
    #executable: /usr/local/bin/clangd

NUM_CORES_TO_USE is referenced from the environment in order to cap parallel jobs to be less than cores+1. Otherwise a machine can be brought to it's knees...

Compile Commands

Support was added to this tool in order to cater to the cquery c++ language server. It was easier to provide a script that combined compile_commands.json than it was to teach cquery to read multiple files. The regex stuff was added to take compile databases from cross compiled builds and still run them through cquery.

Similar support was added to start clangd after first generating compile_commands.json and then passing that directory to clangd.

Usage

./clip <sub command> <sub command arguments>

 Sub commands:

  build [profile]
  debug
  generate-compile-db
  start-clangd

TODO