1CITNAMES(1) CITNAMES(1)
2
6 citnames - deduce command semantic
7
9 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 intercept command, which records
73 the process executions of a build.
74 Read more about the syntax of the file in the intercept man page.
76
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
82 The config file influences the command recognition (by the section
83 “compilation”) and the output format (by the section “output”).
84 The config file is optional. The program will use default values,
86 which can be dumped with the --verbose flags.
87 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 {
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 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 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 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 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
147 bear(1), intercept(1)
148
150 Copyright (C) 2012-2021 by László Nagy <https://github.com/rizsot‐
151 to/Bear>
152
154 László Nagy.
155Bear User Manuals Sep 04, 2021 CITNAMES(1)