NAME

       citnames - deduce command semantic

SYNOPSIS

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

DESCRIPTION

       The name citnames comes from to reverse the word “semantic”.

       Because  when you type a command, you know your intent.  The command execution is just a thing to achieve
       your goal.  This program takes the command which was executed, and try to find out what the intent was to
       run that command.  It deduces the semantic of the command.

       This is useful to generate a compilation database.  Citnames get a list of commands,  and  it  creates  a
       JSON compilation database.  (This is currently the only output of the tool.)

OPTIONS

       --version
              Print version number.

       --help Print help message.

       --verbose
              Enable verbose logging.

       --input file
              Specify  input  file.   (Default  file name provided.) The input is a command execution list, with
              some extra information.  The syntax is detailed in a separate section.

       --output file
              Specify output file.  (Default file name provided.) The output is  currently  a  JSON  compilation
              database.

       --append
              Use  previously generated output file and append the new entries to it.  This way you can run con‐
              tinuously during work, and it keeps the compilation database up to date.  File deletion and  addi‐
              tion  are both considered.  But build process change (compiler flags change) might cause duplicate
              entries.

       --run-checks
              Allow the program to verify file location checks on the current machine it runs.   (Default  value
              provided.   Run help to query it.) This is important if the execution list is not from the current
              host.

       --config file
              Specify a configuration file.  The configuration file captures how the output should be  formatted
              and which entries it shall contain.

EXIT STATUS

       Citnames  exit  status is non-zero in case of IO problems, otherwise it’s zero.  The exit status is inde‐
       pendent of how many command it recognized or was it recognized at all.

OBSERVABILITY

       Any insight about the command recognition logic can be observed with --verbose flag on the  standard  er‐
       ror.  Otherwise, the command is silent.

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.) This file can be produced by the intercept command, which records
       the process executions of a build.

       Read more about the syntax of the file in the intercept man page.

OUTPUT FILE

       Currently, the only output format is the JSON compilation database.  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.  The program will use default values, which can be dumped with the --verbose
       flags.

       Some parts of the file has overlap with the command line arguments.  If both present the command line ar‐
       gument overrides the config file values.

              {
                "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 compiler can be specified, which are 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 com‐
              piler wrapper flags from the mpicc --showme:compile output.) The flags_to_remove  is  an  optional
              attribute,  where the given flags will be removed for the final argument list.  (The flags checked
              for equality only, no regex match.  Flags with arguments are not good candidates to put here,  be‐
              cause the removal logic is too simple for that.)

       compilation.compilers_to_exclude
              this  is  an  optional list of executables (with absolute path) which needs to be removed from the
              output.

       output.content
              The paths_to_include and paths_to_exclude are for filter out entries from these directories.  (Di‐
              rectory names can be absolute paths or relative to the current working  directory  if  the  --run-
              checks  flag  passed.) The include_only_existing_source allows or disables file check for the out‐
              put.  The --run-checks flag overrides this config value.

       output.format
              The command_as_array controls which command field is emitted in the output.  True  produces  argu‐
              ments, false produces command field.  The drop_output_field will disable the output field from the
              output.

SEE ALSO

       bear(1), intercept(1)

COPYRIGHT

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

AUTHORS

       László Nagy.

Bear User Manuals                                 Sep 04, 2021                                       CITNAMES(1)