BEAR-CITNAMES(1)

🎀 bear-citnames(1) — the manual, but make it a vibe ✨

okay bestie, sit down, we're reading bear-citnames from the Bear user manuals and honestly? it's giving brainy queen 💅

---

✨ NAME ✨

bear-citnames — deduce command semantic 🧠✨

---

🌸 SYNOPSIS 🌸

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

---

💖 DESCRIPTION 💖

okay so first of all, the name citnames? it's literally just the word "semantic" spelled backwards 🙈 iconic behavior.

here's the tea: when you type a command, you already know your intent, right? like, the command execution is just the thing you do to get to your goal. so this program takes the command that got executed and tries to figure out what the intent was to run it. it deduces the semantic of the command. queen of reading minds, no cap 👑

and why do we care? because it's useful to generate a compilation database! citnames gets a list of commands and it creates a JSON compilation database. (and just so we're clear — this is currently the only output of the tool. the one and only. main character energy, no supporting cast 💀)

---

💅 OPTIONS 💅

• --version — prints the version number, duh.
• --help — prints the help message, go read it bestie.
• --verbose — turns on verbose logging. more words, more insight 🔥
• --input file — specifies the input file. (a default file name is provided, don't stress.) the input is a command execution list with some extra info sprinkled in. the syntax is detailed in a whole separate section below, keep scrolling 🌈
• --output file — specifies the output file. (default file name provided too, she's prepared.) the output is currently a JSON compilation database.
• --append — uses the previously generated output file and appends the new entries onto 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. but heads up: a build process change (like, compiler flags changing) might cause duplicate entries 😭
• --run-checks — lets the program verify file location checks on the current machine it runs on. (a default value is provided — run help to query it.) this is important if the execution list is not from the current host, okay? don't skip this one 🫶
• --config file — specifies a configuration file. the config file captures how the output should be formatted and which entries it shall contain. very custom, very demure.

---

👑 EXIT STATUS 👑

citnames exit status is non-zero in case of IO problems, otherwise it's zero. and listen — the exit status is independent of how many commands it recognized, or whether it recognized them at all. zero means zero, it doesn't mean "yay I found stuff" 💀

---

🦋 OBSERVABILITY 🦋

any insight about the command recognition logic can be observed with the --verbose flag on the standard error. otherwise? the command is silent. mute. not a peep 🙈

---

🍓 INPUT FILE 🍓

it's a JSON file, with the command execution history. (plus some metadata, which is useful for debugging the application that produced it — thoughtful!) this file can be produced by the bear intercept command, which records the process executions of a build.

read more about the syntax of the file in the bear-intercept(1) man page 📖

---

🧚 OUTPUT FILE 🧚

currently, the only output format is the JSON compilation database. read more about the syntax of that in the bear(1) 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. the program will use default values, which can be dumped with the --verbose flags.

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. periodt ✋

{
  "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": [],
      "duplicate_filter_fields": "file_output"
    },
    "format": {
      "command_as_array": true,
      "drop_output_field": false
    }
  }
}

🌟 compilation.compilers_to_recognize 🌟

this is 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 that will get appended to the final output. (it's a good candidate to use this for adding OpenMPI compiler wrapper flags from the mpicc --showme:compile output, iykyk ✨) the flags_to_remove is an optional attribute, where the given flags will be removed from the final argument list. (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. sorry bestie, it's just how she is 💅)

🌟 compilation.compilers_to_exclude 🌟

this is an optional list of executables (with absolute path) which need to be removed from the output. bye bye 👋

🌟 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 checking for the output. the --run-checks flag overrides this config value. the duplicate_filter_fields selects the method of how duplicate entries are detected in the output. the possible values for this field are: all, file and file_output.

🌟 output.format 🌟

the command_as_array controls which command field is emitted in the output. true produces the arguments, false produces the command field. the drop_output_field will disable the output field from the output. gone, reduced to atoms 💀

---

🌈 SEE ALSO 🌈

bear(1), bear-intercept(1)

---

💖 COPYRIGHT 💖

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

---

🫶 AUTHORS 🫶

László Nagy.

---

okay that's the whole page bestie, you ate it up fr fr 👑✨ this was brought to you by the Bear User Manuals, dated Jan 02, 2023 — slay, and remember: every option here is exactly the option that was there before, no cap 💅💜