1CITNAMES(1)                                                        CITNAMES(1)
2
3
4

NAME

6       citnames - deduce command semantic
7

SYNOPSIS

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

DESCRIPTION

12       The name citnames comes from to reverse the word “semantic”.
13
14       Because when you type a command, you know your intent.  The command ex‐
15       ecution is just a thing to achieve your goal.  This program  takes  the
16       command  which was executed, and try to find out what the intent was to
17       run that command.  It deduces the semantic of the command.
18
19       This is useful to generate a compilation database.  Citnames get a list
20       of commands, and it creates a JSON compilation database.  (This is cur‐
21       rently the only output of the tool.)
22

OPTIONS

24       --version
25              Print version number.
26
27       --help Print help message.
28
29       --verbose
30              Enable verbose logging.
31
32       --input file
33              Specify input file.  (Default file name provided.) The input  is
34              a command execution list, with some extra information.  The syn‐
35              tax is detailed in a separate section.
36
37       --output file
38              Specify output file.  (Default file name provided.)  The  output
39              is currently a JSON compilation database.
40
41       --append
42              Use  previously generated output file and append the new entries
43              to it.  This way you can run continuously during  work,  and  it
44              keeps  the  compilation  database up to date.  File deletion and
45              addition are both considered.  But build process change (compil‐
46              er flags change) might cause duplicate entries.
47
48       --run-checks
49              Allow  the program to verify file location checks on the current
50              machine it runs.  (Default value provided.  Run  help  to  query
51              it.)  This  is  important  if the execution list is not from the
52              current host.
53
54       --config file
55              Specify a configuration file.  The configuration  file  captures
56              how  the  output  should be formatted and which entries it shall
57              contain.
58

EXIT STATUS

60       Citnames exit status is non-zero in case of IO problems, otherwise it’s
61       zero.  The exit status is independent of how many command it recognized
62       or was it recognized at all.
63

OBSERVABILITY

65       Any insight about the command recognition logic can  be  observed  with
66       --verbose  flag  on  the  standard  error.   Otherwise,  the command is
67       silent.
68

INPUT FILE

70       It’s a JSON file, with the command execution history.  (Plus some meta‐
71       data,  that  is useful for debugging the application which was produced
72       it.) This file can be produced by the intercept command, which  records
73       the process executions of a build.
74
75       Read more about the syntax of the file in the intercept man page.
76

OUTPUT FILE

78       Currently,  the  only  output  format is the JSON compilation database.
79       Read more about the syntax of that in the bear man page.
80

CONFIG FILE

82       The config file influences the  command  recognition  (by  the  section
83       “compilation”) and the output format (by the section “output”).
84
85       The  config  file  is  optional.   The program will use default values,
86       which can be dumped with the --verbose flags.
87
88       Some parts of the file has overlap with the command line arguments.  If
89       both  present  the command line argument overrides the config file val‐
90       ues.
91
92              {
93                "compilation": {
94                  "compilers_to_recognize": [
95                    {
96                      "executable": "/usr/bin/mpicc",
97                      "flags_to_add": ["-I/opt/MPI/include"],
98                      "flags_to_remove": ["-Wall"]
99                    }
100                  ],
101                  "compilers_to_exclude": []
102                },
103                "output": {
104                  "content": {
105                    "include_only_existing_source": true,
106                    "paths_to_include": [],
107                    "paths_to_exclude": []
108                  },
109                  "format": {
110                    "command_as_array": true,
111                    "drop_output_field": false
112                  }
113                }
114              }
115
116       compilation.compilers_to_recognize
117              where compiler can be specified, which are not yet recognized by
118              default.   The  executable  is an absolute path to the compiler.
119              The flags_to_add is an optional attribute, which contains  flags
120              which  will  append to the final output.  (It’s a good candidate
121              to use this for adding OpenMPI compiler wrapper flags  from  the
122              mpicc  --showme:compile  output.)  The flags_to_remove is an op‐
123              tional attribute, where the given flags will be removed for  the
124              final  argument  list.  (The flags checked for equality only, no
125              regex match.  Flags with arguments are not  good  candidates  to
126              put here, because the removal logic is too simple for that.)
127
128       compilation.compilers_to_exclude
129              this  is  an  optional  list of executables (with absolute path)
130              which needs to be removed from the output.
131
132       output.content
133              The paths_to_include and paths_to_exclude are for filter out en‐
134              tries  from these directories.  (Directory names can be absolute
135              paths or relative to the current working directory if the --run-
136              checks  flag passed.) The include_only_existing_source allows or
137              disables file check for the output.  The --run-checks flag over‐
138              rides this config value.
139
140       output.format
141              The  command_as_array controls which command field is emitted in
142              the output.  True produces  arguments,  false  produces  command
143              field.  The drop_output_field will disable the output field from
144              the output.
145

SEE ALSO

147       bear(1), intercept(1)
148
150       Copyright (C)  2012-2022  by  László  Nagy  <https://github.com/rizsot
151       to/Bear>
152

AUTHORS

154       László Nagy.
155
156
157
158Bear User Manuals                Sep 04, 2021                      CITNAMES(1)
Impressum