ec is a tool that lets you couple files (source code in particular) and actions on those files. These actions, or commands, are defined in a plaintext header at the beginning of the file and resemble comments in many programming languages.

An ec header is a collection of consecutive lines at the beginning of a file beginning with // or ##. Once ec encounters a line that does not begin with either of these patterns, it stops parsing the header.

Actions/commands are defined in the header by the following format:

//commandname:shell to execute

Everything that comes before the colon (:) is part of the command name and everything after is part of the shell command that will executed if the command is invoked by the user. There must be no white space between the starting pattern (// or ##) and the command name. If there is white space, then the line will be interpreted as a continuation from the last command definition.

To act on the current file, the environment variable SRC is set to the current filename before executing the command's shell code. To use user specified arguments, use the environment variables A0, A1, A2, up to a maximum of A99.

For example:

//compile:gcc -Wall -Wextra -Werror -pedantic -O3 $SRC -o $A0
//debug:gcc -Wall -Wextra -Werror -pedantic -g -O0 -fsanitize=address
// -fsanitize=undefined $SRC -o $A0

// This is a comment and not part of the ec header.

#include <stdio.h>

int main(void) {
  printf("Hello, world!\n");
  return 0;
}

is a source file for a small C program along with an ec header to allow for quick compilation. The header specifies two actions/commands, compile and debug. Both actions compile the current file and write an executable to a file specified by the user.

Some linters might not like that the comments in the ec header don't have a leading space. To stop them from trying to mess up the header, you might need to add some configuration. For example, you can stop clang-format (and clangd) from complaining by adding this line to your .clang-format file:

CommentPragmas: '^[^ ].*:.*'

To run an ec on a file, pass the filename, the action you want to run, and any arguments you wish to pass.

If the example from above was in a file named hello.c, then the debug action/command could be run with the following invocation of ec:

ec hello.c debug output_program