1BEAR-CITNAMES(1) BEAR-CITNAMES(1)
2
6 bear-citnames - deduce command semantic
7
9 bear citnames [options] --input <file> --output <file>
10
12 The name citnames comes from to reverse the word “semantic”.
13 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 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
24 --version
25 Print version number.
26 --help Print help message.
28 --verbose
30 Enable verbose logging.
31 --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 --output file
38 Specify output file. (Default file name provided.) The output
39 is currently a JSON compilation database.
40 --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 --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 --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
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
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
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 bear intercept command, which
73 records the process executions of a build.
74 Read more about the syntax of the file in the bear-intercept(1) man
76 page.
77
79 Currently, the only output format is the JSON compilation database.
80 Read more about the syntax of that in the bear(1) man page.
81
83 The config file influences the command recognition (by the section
84 “compilation”) and the output format (by the section “output”).
85 The config file is optional. The program will use default values,
87 which can be dumped with the --verbose flags.
88 Some parts of the file has overlap with the command line arguments. If
90 both present the command line argument overrides the config file val‐
91 ues.
92 {
94 "compilation": {
95 "compilers_to_recognize": [
96 {
97 "executable": "/usr/bin/mpicc",
98 "flags_to_add": ["-I/opt/MPI/include"],
99 "flags_to_remove": ["-Wall"]
100 }
101 ],
102 "compilers_to_exclude": []
103 },
104 "output": {
105 "content": {
106 "include_only_existing_source": true,
107 "paths_to_include": [],
108 "paths_to_exclude": [],
109 "duplicate_filter_fields": "file_output"
110 },
111 "format": {
112 "command_as_array": true,
113 "drop_output_field": false
114 }
115 }
116 }
117 compilation.compilers_to_recognize
119 where compiler can be specified, which are not yet recognized by
120 default. The executable is an absolute path to the compiler.
121 The flags_to_add is an optional attribute, which contains flags
122 which will append to the final output. (It’s a good candidate
123 to use this for adding OpenMPI compiler wrapper flags from the
124 mpicc --showme:compile output.) The flags_to_remove is an op‐
125 tional attribute, where the given flags will be removed for the
126 final argument list. (The flags checked for equality only, no
127 regex match. Flags with arguments are not good candidates to
128 put here, because the removal logic is too simple for that.)
129 compilation.compilers_to_exclude
131 this is an optional list of executables (with absolute path)
132 which needs to be removed from the output.
133 output.content
135 The paths_to_include and paths_to_exclude are for filter out en‐
136 tries from these directories. (Directory names can be absolute
137 paths or relative to the current working directory if the --run-
138 checks flag passed.) The include_only_existing_source allows or
139 disables file check for the output. The --run-checks flag over‐
140 rides this config value. The duplicate_filter_fields select the
141 method how duplicate entries are detected in the output. The
142 possible values for this field are: all, file and file_output.
143 output.format
145 The command_as_array controls which command field is emitted in
146 the output. True produces arguments, false produces command
147 field. The drop_output_field will disable the output field from
148 the output.
149
151 bear(1), bear-intercept(1)
152
154 Copyright (C) 2012-2023 by László Nagy <https://github.com/rizsot‐
155 to/Bear>
156
158 László Nagy.
159Bear User Manuals Jan 02, 2023 BEAR-CITNAMES(1)