MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
MayaFluxSignatures.cpp
Go to the documentation of this file.
1#include "CreatorBuild.hpp"
2#include "Discovery.hpp"
3#include "FunctionBuild.hpp"
5#include "FunctionSidecar.hpp"
6#include "Scan.hpp"
7#include "Sidecar.hpp"
8#include "SignatureOutput.hpp"
9
10#ifndef MAYAFLUX_REFLECT_RESOURCE_DIR
11#define MAYAFLUX_REFLECT_RESOURCE_DIR ""
12#endif
13
14namespace {
15
16using namespace MayaFlux::Reflect::Tool;
17
18struct Config {
19 std::filesystem::path root;
20 std::filesystem::path registry;
21 std::filesystem::path output;
22 std::filesystem::path build_path;
23 std::filesystem::path translation_unit;
24 std::string resource_dir;
25 std::vector<std::string> extra_args;
26 bool check { false };
27 bool functions { false };
28 bool insert_includes { true };
29 std::vector<std::filesystem::path> paths;
30};
31
32int fail(const std::string& message)
33{
34 std::cerr << message << '\n';
35 return 1;
36}
37
38int generate_functions(const Config& config)
39{
40 std::vector<std::filesystem::path> roots = config.paths;
41 if (roots.empty()) {
42 roots.push_back(config.root / "src/MayaFlux");
43 }
44 std::error_code code;
45 for (auto& root : roots) {
46 const auto canonical = std::filesystem::canonical(root, code);
47 if (code) {
48 return fail("cannot read " + root.string());
49 }
50 root = canonical;
51 }
52
53 const std::vector<std::filesystem::path> headers = discover_headers(roots, "MF_DESCRIBE_FUNCTION");
54 if (headers.empty()) {
55 return fail("no MF_DESCRIBE_FUNCTION requests found under the given paths");
56 }
57
58 std::string error;
59 ScanInput input;
60 for (const auto& header : headers) {
61 const std::filesystem::path sidecar = sidecar_path(header, function_sidecar_suffix);
62 if (config.check) {
63 if (!std::filesystem::exists(sidecar)) {
64 input.stubs.push_back(sidecar.filename().string());
65 }
66 } else if (!ensure_stub(sidecar, error)) {
67 return fail(error);
68 }
69 }
70 input.build_path = config.build_path;
71 input.translation_unit = config.translation_unit;
72 input.roots = roots;
73 input.headers = headers;
74 input.resource_dir = config.resource_dir;
75 input.extra_args = config.extra_args;
76
77 FunctionCollector collector;
78 if (!scan(input, [&collector](clang::ast_matchers::MatchFinder& finder) { collector.attach(finder); }, error)) {
79 return fail(error);
80 }
81 if (!collector.errors().empty()) {
82 for (const auto& message : collector.errors()) {
83 std::cerr << message << '\n';
84 }
85 return 1;
86 }
87 if (collector.requests().empty()) {
88 return fail("no MF_DESCRIBE_FUNCTION requests were recognised in the selected headers (marker variables matched: "
89 + std::to_string(collector.matched()) + ")");
90 }
91
92 if (config.check) {
93 std::vector<std::filesystem::path> directories;
94 for (const auto& root : roots) {
95 if (std::filesystem::is_directory(root, code)) {
96 directories.push_back(root);
97 }
98 }
99 const auto existing = directories.empty()
100 ? std::vector<std::filesystem::path> {}
102 const auto problems = check_function_sidecars(collector.requests(), headers, existing);
103 for (const auto& problem : problems) {
104 std::cerr << problem << '\n';
105 }
106 if (problems.empty()) {
107 std::cout << "All " << collector.requests().size() << " function sidecars are current\n";
108 return 0;
109 }
110 std::cout << problems.size() << " problem(s) found\n";
111 return 1;
112 }
113
114 bool clean = true;
115 std::size_t functions = 0;
116 for (const auto& header : headers) {
117 const auto found = collector.requests().find(header);
118 if (found == collector.requests().end()) {
119 std::cerr << header.string() << ": contains MF_DESCRIBE_FUNCTION text but produced no request\n";
120 clean = false;
121 continue;
122 }
124 return fail(error);
125 }
126 functions += found->second.functions.size();
127 const unsigned last = last_function_line(found->second);
128 if (config.insert_includes) {
129 bool inserted = false;
130 if (!insert_include(header, last, function_sidecar_suffix, inserted, error)) {
131 return fail(error);
132 }
133 if (inserted) {
134 std::cout << "Inserted #include \"" << sidecar_path(header, function_sidecar_suffix).filename().string()
135 << "\" into " << header.string() << '\n';
136 }
137 }
138 if (const auto problem = check_include(header, last, function_sidecar_suffix)) {
139 std::cerr << *problem << '\n';
140 clean = false;
141 }
142 }
143 std::cout << "Generated " << functions << " function descriptions in " << collector.requests().size() << " sidecars\n";
144 return clean ? 0 : 1;
145}
146
147int generate(const Config& config)
148{
149 std::error_code code;
150 const std::filesystem::path source_root = std::filesystem::canonical(config.root / "src", code);
151 if (code) {
152 return fail("cannot read " + (config.root / "src").string());
153 }
154
155 std::string error;
156 auto entries = read_signature_entries(config.registry, source_root, error);
157 if (!entries) {
158 return fail(error);
159 }
160
161 ScanInput input;
162 input.build_path = config.build_path;
163 input.translation_unit = config.translation_unit;
164 input.roots = { source_root };
165 input.resource_dir = config.resource_dir;
166 input.extra_args = config.extra_args;
167 for (const SignatureEntry& entry : *entries) {
168 const auto canonical = std::filesystem::canonical(entry.header, code);
169 if (code) {
170 return fail("cannot read header " + entry.header.string());
171 }
172 input.headers.push_back(canonical);
173 }
174 std::ranges::sort(input.headers);
175 input.headers.erase(std::ranges::unique(input.headers).begin(), input.headers.end());
176
177 SignatureCollector collector(*entries, source_root);
178 if (!scan(input, [&collector](clang::ast_matchers::MatchFinder& finder) { collector.attach(finder); }, error)) {
179 return fail(error);
180 }
181 if (!collector.errors().empty()) {
182 for (const auto& message : collector.errors()) {
183 std::cerr << message << '\n';
184 }
185 return 1;
186 }
187 if (const auto missing = collector.missing(); !missing.empty()) {
188 for (const auto& name : missing) {
189 std::cerr << name << ": expected one complete class definition, found none\n";
190 }
191 return 1;
192 }
193
194 const SignatureFiles files = render_signature_files(collector.classes(), source_root);
195 const std::vector<std::pair<std::string, const std::string*>> outputs {
196 { "CreatorIncludes.hpp", &files.includes },
197 { "CreatorClasses.hpp", &files.classes },
198 { "CreatorDeclarations.inc", &files.declarations },
199 { "CreatorDefinitions.inc", &files.definitions },
200 };
201
202 if (config.check) {
203 std::size_t stale = 0;
204 for (const auto& [name, text] : outputs) {
205 if (read_text(config.output / name) != std::optional<std::string>(*text)) {
206 std::cerr << (config.output / name).string() << ": differs from what the registry generates\n";
207 ++stale;
208 }
209 }
210 if (stale == 0) {
211 std::cout << "All " << outputs.size() << " generated files are current\n";
212 return 0;
213 }
214 std::cout << stale << " file(s) out of date\n";
215 return 1;
216 }
217
218 std::filesystem::create_directories(config.output, code);
219 if (code) {
220 return fail("cannot create " + config.output.string());
221 }
222 for (const auto& [name, text] : outputs) {
223 if (!write_if_changed(config.output / name, *text, error)) {
224 return fail(error);
225 }
226 }
227 std::cout << "Generated methods for " << collector.classes().size() << " classes\n";
228 return 0;
229}
230
231}
232
233int main(int argc, const char** argv)
234{
235 llvm::cl::OptionCategory category("mayaflux-signatures options");
236 llvm::cl::opt<std::string> root("root",
237 llvm::cl::desc("Repository root holding src/"),
238 llvm::cl::value_desc("dir"), llvm::cl::init("."), llvm::cl::cat(category));
239 llvm::cl::opt<std::string> registry("registry",
240 llvm::cl::desc("Registry header (default: <root>/src/MayaFlux/API/Proxy/Registry.hpp)"),
241 llvm::cl::value_desc("file"), llvm::cl::cat(category));
242 llvm::cl::opt<std::string> output("output",
243 llvm::cl::desc("Directory the generated files are written to (default: <root>/src/MayaFlux/API/Proxy/Generated)"),
244 llvm::cl::value_desc("dir"), llvm::cl::cat(category));
245 llvm::cl::opt<std::string> build_path("p",
246 llvm::cl::desc("Directory holding compile_commands.json"),
247 llvm::cl::value_desc("dir"), llvm::cl::init("build"), llvm::cl::cat(category));
248 llvm::cl::opt<std::string> translation_unit("translation-unit",
249 llvm::cl::desc("Source file whose compile command is borrowed (default: <root>/src/MayaFlux/API/Proxy/Creator.cpp)"),
250 llvm::cl::value_desc("file"), llvm::cl::cat(category));
251 llvm::cl::opt<std::string> resource_dir("resource-dir",
252 llvm::cl::desc("Clang resource directory holding the builtin headers"),
253 llvm::cl::value_desc("dir"), llvm::cl::init(MAYAFLUX_REFLECT_RESOURCE_DIR),
254 llvm::cl::cat(category));
255 llvm::cl::list<std::string> extra_args("extra-arg",
256 llvm::cl::desc("Extra Clang argument added to the scan"),
257 llvm::cl::value_desc("argument"), llvm::cl::cat(category));
258 llvm::cl::opt<bool> check("check",
259 llvm::cl::desc("Write nothing; exit 1 when a generated file is out of date"),
260 llvm::cl::cat(category));
261 llvm::cl::opt<bool> functions("functions",
262 llvm::cl::desc("Write a Name.signatures.hpp sidecar beside each header that holds MF_DESCRIBE_FUNCTION "
263 "requests, instead of the Creator methods. A header with requests must not use its own sidecar"),
264 llvm::cl::cat(category));
265 llvm::cl::opt<bool> no_insert_include("no-insert-include",
266 llvm::cl::desc("With --functions, report a missing sidecar include instead of inserting it"),
267 llvm::cl::cat(category));
268 llvm::cl::opt<bool> build("build",
269 llvm::cl::desc("Build step: write the Creator files and mark them modified, or with --functions the "
270 "sidecar of the one header given, inserting its include when missing. Needs "
271 "--translation-unit (defaulted) with a compile database, or --compile-arg"),
272 llvm::cl::cat(category));
273 llvm::cl::list<std::string> compile_args("compile-arg",
274 llvm::cl::desc("With --build: one argument of the whole compile command, used instead of the database"),
275 llvm::cl::value_desc("argument"), llvm::cl::cat(category));
276 llvm::cl::opt<std::string> depfile("depfile",
277 llvm::cl::desc("With --build: write a depfile of the registry and the headers the scan read"),
278 llvm::cl::value_desc("file"), llvm::cl::cat(category));
279 llvm::cl::opt<std::string> depfile_target("depfile-target",
280 llvm::cl::desc("With --build: the target named in the depfile (default: CreatorIncludes.hpp in the output)"),
281 llvm::cl::value_desc("path"), llvm::cl::cat(category));
282 llvm::cl::list<std::string> paths(llvm::cl::Positional,
283 llvm::cl::desc("<path>... (with --functions: headers or directories searched, default src/MayaFlux)"),
284 llvm::cl::cat(category));
285
286 llvm::cl::HideUnrelatedOptions(category);
287 llvm::cl::ParseCommandLineOptions(argc, argv,
288 "Writes the Creator proxy's methods from the public constructors of the registered classes, or with "
289 "--functions the parameter names of the functions named by MF_DESCRIBE_FUNCTION.\n");
290
291 Config config;
292 config.root = root.getValue();
293 const std::filesystem::path proxy = config.root / "src/MayaFlux/API/Proxy";
294 config.registry = registry.empty() ? proxy / "Registry.hpp" : std::filesystem::path(registry.getValue());
295 config.output = output.empty() ? proxy / "Generated" : std::filesystem::path(output.getValue());
296 config.build_path = build_path.getValue();
297 config.translation_unit = translation_unit.empty() ? proxy / "Creator.cpp" : std::filesystem::path(translation_unit.getValue());
298 config.resource_dir = resource_dir.getValue();
299 config.extra_args.assign(extra_args.begin(), extra_args.end());
300 config.check = check;
301 config.functions = functions;
302 config.insert_includes = !no_insert_include;
303 config.paths.assign(paths.begin(), paths.end());
304
305 if (build && config.functions) {
306 if (config.check || config.paths.size() != 1) {
307 return fail("--functions --build takes exactly one header, and no --check");
308 }
309 FunctionBuildOptions options;
310 options.header = config.paths.front();
311 options.build_path = config.build_path;
312 options.translation_unit = config.translation_unit;
313 options.resource_dir = config.resource_dir;
314 options.extra_args = config.extra_args;
315 options.compile_args.assign(compile_args.begin(), compile_args.end());
316 options.depfile = depfile.getValue();
317 options.depfile_target = depfile_target.getValue();
318 options.insert_includes = config.insert_includes;
319 return run_function_build(options);
320 }
321
322 if (build) {
323 if (config.check || !config.paths.empty()) {
324 return fail("--build writes the Creator files; it takes no --check or paths");
325 }
326 CreatorBuildOptions options;
327 options.root = config.root;
328 options.registry = config.registry;
329 options.output = config.output;
330 options.build_path = config.build_path;
331 options.translation_unit = config.translation_unit;
332 options.resource_dir = config.resource_dir;
333 options.extra_args = config.extra_args;
334 options.compile_args.assign(compile_args.begin(), compile_args.end());
335 options.depfile = depfile.getValue();
336 options.depfile_target = depfile_target.getValue();
337 return run_creator_build(options);
338 }
339
340 return config.functions ? generate_functions(config) : generate(config);
341}
#define MAYAFLUX_REFLECT_RESOURCE_DIR
int main(int argc, const char **argv)
Cycle Behavior: The for_cycles(N) configuration controls how many times the capture operation execute...
const FunctionMap & requests() const noexcept
void attach(clang::ast_matchers::MatchFinder &finder)
Registers the matcher for the marker variables on finder.
std::size_t matched() const noexcept
Marker variables the matcher reached, before any filtering.
const std::vector< std::string > & errors() const noexcept
Turns each MF_DESCRIBE_FUNCTION variable in the scanned translation unit into a FunctionRequest.
std::vector< SignatureClass > classes() const
The registered classes that were found, in registry order.
std::vector< std::string > missing() const
Registered classes the scan never reached a definition of.
const std::vector< std::string > & errors() const noexcept
void attach(clang::ast_matchers::MatchFinder &finder)
Registers the matcher for class definitions on finder.
Reads the public constructors of each registered class from the scanned translation unit.
bool ensure_stub(const std::filesystem::path &path, std::string &error)
Writes an empty sidecar when none exists, so the include never fails a first scan.
Definition Sidecar.cpp:129
int run_creator_build(const CreatorBuildOptions &options)
Writes the four Creator files, for a build step.
bool insert_include(const HeaderRequests &requests, bool &inserted, std::string &error)
Inserts the sidecar include on the line after the last marker when the header has none.
Definition Sidecar.cpp:41
std::vector< std::string > check_function_sidecars(const FunctionMap &requests, const std::vector< std::filesystem::path > &headers, const std::vector< std::filesystem::path > &existing)
Compares the function sidecars on disk with what the generator would write, touching nothing.
std::optional< std::vector< SignatureEntry > > read_signature_entries(const std::filesystem::path &registry, const std::filesystem::path &source_root, std::string &error)
Reads the N, W and B registrations of the registry header and finds each class's header.
SignatureFiles render_signature_files(const std::vector< SignatureClass > &classes, const std::filesystem::path &source_root)
Renders the generated files for the non abstract classes of classes.
std::optional< std::string > read_text(const std::filesystem::path &path)
The whole content of path, or nullopt when it cannot be read.
Definition Sidecar.cpp:30
std::vector< std::filesystem::path > discover_headers(const std::vector< std::filesystem::path > &roots)
Finds headers under roots that contain an MF_DESCRIBE request.
Definition Discovery.cpp:45
std::filesystem::path sidecar_path(const std::filesystem::path &header)
Path of the sidecar for header: Name.hpp becomes Name.describe.hpp beside it.
Definition Sidecar.cpp:85
std::vector< std::filesystem::path > discover_sidecars(const std::vector< std::filesystem::path > &roots)
Every Name.describe.hpp under the directories among roots, canonical and sorted.
Definition Discovery.cpp:76
bool scan(const ScanInput &input, RequestCollector &collector, std::string &error)
Parses every header of input in one translation unit and fills collector.
Definition Scan.cpp:176
constexpr std::string_view function_sidecar_suffix
The suffix of a function sidecar: Name.hpp becomes Name.signatures.hpp beside it.
int run_function_build(const FunctionBuildOptions &options)
Writes the function sidecar of one header, for a build step.
std::string render_function_sidecar(const HeaderFunctions &functions)
Text of the sidecar for one header, one Signature specialization per function, sorted by name.
unsigned last_function_line(const HeaderFunctions &functions)
The line after which the sidecar include may appear: the last marker of the header.
std::optional< std::string > check_include(const HeaderRequests &requests)
Checks that the header includes its sidecar exactly once, after its last marker.
Definition Sidecar.cpp:161
bool write_if_changed(const std::filesystem::path &path, const std::string &content, std::string &error)
Replaces path with content only when the content differs.
Definition Sidecar.cpp:137
What mayaflux_signatures --build needs to write the Creator files.
What mayaflux_signatures --functions --build needs to describe the functions of one header.
std::filesystem::path build_path
Definition Scan.hpp:12
std::vector< std::string > extra_args
Definition Scan.hpp:17
std::vector< std::string > stubs
Definition Scan.hpp:18
std::vector< std::filesystem::path > roots
Definition Scan.hpp:14
std::vector< std::filesystem::path > headers
Definition Scan.hpp:15
std::filesystem::path translation_unit
Definition Scan.hpp:13
What one scan needs: the compile database, the headers, and flag overrides.
Definition Scan.hpp:11
One class of the Creator registry: the method name, its qualified type and its header.
The four generated files of the Creator proxy, as text.