~sircmpwn/annotatec

eb1eb338d1f1db5a676ee146a757e45f4a039a43 — Drew DeVault 7 months ago 4dde209
Add README.md
1 files changed, 56 insertions(+), 0 deletions(-)

A README.md
A README.md => README.md +56 -0
@@ 0,0 1,56 @@
# annotatec

This program scans C source code and emits an annotation graph for
[git.sr.ht](https://git.sr.ht)'s [code
annotations](https://man.sr.ht/git.sr.ht/annotations.md) feature.

## Limitations

This supports C11 syntax and a handful of GNU C extensions. If your software
uses `-std=gnu*`, it will likely not be parsed successfully. You will
undoubtably run into some GNU extensions anyway, please [report them
here](https://todo.sr.ht/~sircmpwn/annotate)

## Usage

```
annotatec [-gdD] [-C <cpp...>] files... >annotations.json
```

This will print annotations to stdout and progress to stderr. For information
about uploading these annotations to git.sr.ht, see the [git.sr.ht
docs](https://man.sr.ht/git.sr.ht/annotations.md).

The `-C` flag allows you to specify a custom C preprocessor command to
use, where you will need to supply it with a list of include directories,
macros, and so on, which matches those used in your source tree, as well as the
C standard to target. For example:

```sh
annotatec -C "cpp -std=c11 -Iinclude $(pkg-config --cflags libgit2)"
```

You also will almost certainly want to specify the `-g` flag, which will
translate file paths into git blob IDs.

## Example

To generate annotations for all C files in your git repo suitable for sending to
git.sr.ht:

```sh
find . -name "*.c" | xargs \
  annotatec -gC "cpp -std=c11 -Iinclude $(pkg-config --cflags libgit2)" \
  > annotations.json
```

## Bugs, help, patches

Submit bugs to [~sircmpwn/annotate](https://todo.sr.ht/~sircmpwn/annotate).

Send support requests to
[sr.ht-discuss](https://lists.sr.ht/~sircmpwn/sr.ht-discuss).

Send patches [via email](https://git-send-email.io) to
[sr.ht-dev](https://lists.sr.ht/~sircmpwn/sr.ht-dev) with `git config
format.subjectPrefix 'PATCH annotatec'`.