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 from how many command it recog‐
62 nized 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 silent.
67
69 It’s a JSON file, with the command execution history. (Plus some meta‐
70 data, that is useful for debugging the application which was produced
71 it.) This file can be produced by the intercept command, which records
72 the process executions of a build.
73 Read more about the syntax of the file in the intercept man page.
75
77 Currently the only output format is the JSON compilation database.
78 Read more about the syntax of that in the bear man page.
79
81 The config file influences the command recognition (by the section
82 “compilation”) and the output format (by the section “output”).
83 The config file is optional. The program will use default values,
85 which can be dumped with the --verbose flags.
86 Some parts of the file has overlap with the command line arguments. If
88 both present the command line argument overrides the config file val‐
89 ues.
90 {
92 "compilation": {
93 "compilers_to_recognize": [
94 {
95 "executable": "/usr/bin/mpicc",
96 "additional_flags": ["-I/opt/MPI/include"]
97 }
98 ],
99 "compilers_to_exclude": []
100 },
101 "output": {
102 "content": {
103 "include_only_existing_source": true,
104 "paths_to_include": [],
105 "paths_to_exclude": []
106 },
107 "format": {
108 "command_as_array": true,
109 "drop_output_field": false
110 }
111 }
112 }
113 compilation.compilers_to_recognize
115 where compiler can be specified, which are not yet recognized by
116 default. The executable is an absolute path to the compiler.
117 The additional_flags is an optional attribute, which contains
118 flags which will append to the final output. (It’s a good can‐
119 didate to use this for adding OpenMPI compiler wrapper flags
120 from the mpicc --showme:compile output.)
121 compilation.compilers_to_exclude
123 this is an optional list of executables (with absolute path)
124 which needs to be removed from the output.
125 output.content
127 The paths_to_include and paths_to_exclude are for filter out en‐
128 tries from these directories. (Directory names has to be abso‐
129 lute paths.) The include_only_existing_source allows or disables
130 file check for the output.
131 output.format
133 The command_as_array controls which command field is emitted in
134 the output. True produces arguments, false produces command
135 field. The drop_output_field will disable the output field from
136 the output.
137
139 bear(1), intercept(1)
140
142 Copyright (C) 2012-2021 by László Nagy <https://github.com/rizsot‐
143 to/Bear>
144
146 László Nagy.
147Bear User Manuals Sep 14, 2020 CITNAMES(1)