CITNAMES(1)

📦 version 3.0.20, in epel 9, ubuntu jammy

✨ CITNAMES ✨

okay bestie, sit down, hydrate, because we're about to talk about the little man page called citnames from the Bear User Manuals. it's giving "quiet genius" energy and honestly? obsessed. 💖

🌸 NAME 🌸

citnames — deduce command semantic

no wait, that's the boring version. citnames literally figures out what you meant when you ran a command. it's the semantic detective. periodt. 🔍

🎀 SYNOPSIS 🎀

citnames [options] --input <file> --output <file>

that's the whole vibe. give it options, give it an input file, give it an output file. slay. ✨

🦋 DESCRIPTION 🦋

so the name citnames? it comes from reversing the word "semantic". cute little anagram moment, iykyk. 💅

here's the thing: when you type a command, you already know your intent. the command execution is just... a thing you do to achieve your goal, right? it's the means, not the end. so this program takes the command that was actually executed and tries to find out what the intent was to run that command. it deduces the semantic of the command. main character behavior, honestly. 👑

and why do we care? because this is useful to generate a compilation database, bestie. citnames gets a list of commands, and it creates a JSON compilation database. (this is currently the only output of the tool — and that's fine, we love a specialist.) 🌈

💅 OPTIONS 💅

  • --version — prints the version number. that's it. that's the whole job. 🎀
  • --help — prints a help message, so you're never lost, bestie. 🫶
  • --verbose — turns on verbose logging. more words, more clarity, more ✨vibes✨.
  • --input file — specify the input file. (a default file name is provided, so you're not stranded.) the input is a command execution list, with some extra information sprinkled on top. the syntax gets its own section below, don't worry.
  • --output file — specify the output file. (default file name provided here too, we love a fallback.) the output is currently a JSON compilation database.
  • --append — uses the previously generated output file and appends the new entries to it. this way you can run continuously during work, and it keeps the compilation database up to date. file deletion and addition are both considered, so it actually tracks your chaos. but — build process change (compiler flags change) might cause duplicate entries. so like... be aware. 🙈
  • --run-checks — allows the program to verify file location checks on the current machine it runs on. (default value provided — run help to query it.) this is important if the execution list is not from the current host. like, do not skip this one if you're crossing machines, fr fr. 🔥
  • --config file — specify a configuration file. the configuration file captures how the output should be formatted and which entries it shall contain. very "let me customize my little universe" of you. 💜

⭐ EXIT STATUS ⭐

citnames exit status is non-zero in case of IO problems, otherwise it's zero.

and here's the iconic part: the exit status is independent of how many commands it recognized, or whether it recognized them at all. it does not care. it does not judge. it just does the IO thing. 💀

🔥 OBSERVABILITY 🔥

any insight about the command recognition logic can be observed with the --verbose flag on the standard error. otherwise, the command is silent. 🤫

silent. mysterious. lowkey iconic.

🌸 INPUT FILE 🌸

it's a JSON file, with the command execution history. (plus some metadata, that is useful for debugging the application which was produced it — thoughtful, honestly.)

this file can be produced by the intercept command, which records the process executions of a build. the dream team. 🤝

read more about the syntax of the file in the intercept man page. (it's in SEE ALSO, bestie, don't worry.)

🎀 OUTPUT FILE 🎀

currently, the only output format is the JSON compilation database. one format, one love.

read more about the syntax of that in the bear man page. 🐻

✨ CONFIG FILE ✨

the config file influences the command recognition (by the section compilation) and the output format (by the section output).

the config file is optional. if you don't bring one, the program will use default values, which can be dumped with the --verbose flags. (yes, the manpage says "flags" plural, we're keeping it, character for character, no cap.)

some parts of the file have overlap with the command line arguments. if both are present, the command line argument overrides the config file values. the CLI always wins. main character energy. 👑

{
  "compilation": {
    "compilers_to_recognize": [
      {
        "executable": "/usr/bin/mpicc",
        "flags_to_add": ["-I/opt/MPI/include"],
        "flags_to_remove": ["-Wall"]
      }
    ],
    "compilers_to_exclude": []
  },
  "output": {
    "content": {
      "include_only_existing_source": true,
      "paths_to_include": [],
      "paths_to_exclude": []
    },
    "format": {
      "command_as_array": true,
      "drop_output_field": false
    }
  }
}

🌈 compilation.compilers_to_recognize

where a compiler can be specified which is not yet recognized by default. the executable is an absolute path to the compiler. the flags_to_add is an optional attribute, which contains flags which will append to the final output. (it's a good candidate to use this for adding OpenMPI compiler wrapper flags from the mpicc --showme:compile output — chef's kiss tip right there. 💋) the flags_to_remove is an optional attribute, where the given flags will be removed from the final argument list. (careful though: the flags are checked for equality only, no regex match. flags with arguments are not good candidates to put here, because the removal logic is too simple for that. it's giving "simple by design", respect it. 🙏)

🧚 compilation.compilers_to_exclude

this is an optional list of executables (with absolute path) which needs to be removed from the output. bye bestie, not you. 👋

🌸 output.content

the paths_to_include and paths_to_exclude are for filtering out entries from these directories. (directory names can be absolute paths, or relative to the current working directory if the --run-checks flag is passed.) the include_only_existing_source allows or disables file check for the output. the --run-checks flag overrides this config value. so yeah, CLI stays winning.

💜 output.format

the command_as_array controls which command field is emitted in the output. true produces arguments, false produces the command field. the drop_output_field will disable the output field from the output. your output, your rules. ✨

💖 SEE ALSO 💖

bear(1), intercept(1)

Copyright (C) 2012-2022 by László Nagy <https://github.com/rizsotto/Bear>

👑 AUTHORS 👑

László Nagy.

okay that's the whole page, bestie. you understood all of it, obviously, because you're smart and iconic. 💅✨

written under the Bear User Manuals banner, citnames(1), dated Sep 04, 2021 — go forth and generate that compilation database, queen. 🎀🌈
📦 where this page comes from