combine tool, tests, and library

source/tool/GenerateAction.cpp

@@ -0,0 +1,106 @@
+//
+// This is a derivative work. originally part of the LLVM Project.
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2023 Vinnie Falco ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdox
+//
+
+#include "Options.hpp"
+#include "api/ConfigImpl.hpp"
+#include <mrdox/Generators.hpp>
+#include <mrdox/Reporter.hpp>
+#include <clang/Tooling/AllTUsExecution.h>
+#include <clang/Tooling/JSONCompilationDatabase.h>
+#include <cstdlib>
+
+namespace clang {
+namespace mrdox {
+
+int
+DoGenerateAction(Reporter& R)
+{
+    auto& generators = getGenerators();
+
+    // Calculate additional YAML settings from command line options.
+    std::string extraYaml;
+    {
+        llvm::raw_string_ostream os(extraYaml);
+        if(IgnoreMappingFailures.getValue())
+            os << "ignore-failures: true\n";
+    }
+
+    // Load configuration file
+    if(! ConfigPath.hasArgStr())
+    {
+        llvm::errs() <<
+            "Missing configuration file path argument.\n";
+        return EXIT_FAILURE;
+    }
+    std::error_code ec;
+    auto config = loadConfigFile(ConfigPath, extraYaml, ec);
+    if(ec)
+    {
+        (void)R.error(ec, "load config file '", ConfigPath, "'");
+        return EXIT_FAILURE;
+    }
+
+    // Load the compilation database
+    if(InputPaths.empty())
+    {
+        llvm::errs() <<
+            "Missing path to compilation database argument.\n";
+        return EXIT_FAILURE;
+    }
+    if(InputPaths.size() > 1)
+    {
+        llvm::errs() <<
+            "Expected one input path argument, got more than one.\n";
+        return EXIT_FAILURE;
+    }
+    std::string errorMessage;
+    auto compilations =
+        tooling::JSONCompilationDatabase::loadFromFile(
+            InputPaths.front(), errorMessage,
+                tooling::JSONCommandLineSyntax::AutoDetect);
+    if(! compilations)
+    {
+        llvm::errs() << errorMessage << '\n';
+        return EXIT_FAILURE;
+    }
+
+    // Create the ToolExecutor from the compilation database
+    int ThreadCount = 0;
+    auto ex = std::make_unique<tooling::AllTUsToolExecutor>(
+        *compilations, ThreadCount);
+
+    // Create the generator
+    auto generator = generators.find(FormatType.getValue());
+    if(! generator)
+    {
+        R.print("Generator '", FormatType.getValue(), "' not found.");
+        return EXIT_FAILURE;
+    }
+
+    // Run the tool, this can take a while
+    auto corpus = Corpus::build(*ex, config, R);
+    if(R.error(corpus, "build the documentation corpus"))
+        return EXIT_FAILURE;
+
+    // Run the generator.
+    if(config->verboseOutput)
+        llvm::outs() << "Generating docs...\n";
+    auto err = generator->build(OutputPath.getValue(), **corpus, R);
+    if(err)
+    {
+        R.print(err.message(), "generate '", OutputPath, "'");
+        return EXIT_FAILURE;
+    }
+    return EXIT_SUCCESS;
+}
+
+} // mrdox
+} // clang

source/tool/Options.cpp

@@ -0,0 +1,95 @@
+//
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2023 Vinnie Falco ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdox
+//
+
+#include "Options.hpp"
+
+namespace clang {
+namespace mrdox {
+
+char const* Overview =
+R"(Generate reference documentation, run tests against
+a set of input vectors, or update a set of reference tests.)";
+
+llvm::cl::OptionCategory Category("mrdox options");
+
+llvm::cl::extrahelp ExtraHelp(
+R"(Usage:
+
+    mrdox .. ( compile-commands )
+
+    mrdox .. --action ( "test" | "update" ) ( dir | file )...
+
+Examples
+
+    mrdox --action test friend.cpp
+
+    mrdox --format adoc compile_commands.json
+)");
+
+llvm::cl::opt<Action> ToolAction(
+    "action",
+    llvm::cl::desc(R"(Which action should be performed)"),
+    llvm::cl::init(Action::generate),
+    llvm::cl::values(
+        clEnumVal(test, "Compare output against expected"),
+        clEnumVal(update, "Update all expected xml files"),
+        clEnumVal(generate, "Generate reference documentation")),
+    llvm::cl::cat(Category));
+
+// Test options
+
+llvm::cl::opt<bool> badOption(
+    "bad",
+    llvm::cl::desc("Write a .bad.xml file for each test failure"),
+    llvm::cl::init(true),
+    llvm::cl::cat(Category));
+
+llvm::cl::opt<bool> adocOption(
+    "adoc",
+    llvm::cl::desc("Write the corresponding Asciidoc (adoc) file for each input test file"),
+    llvm::cl::init(false),
+    llvm::cl::cat(Category));
+
+// Generate options
+
+llvm::cl::opt<std::string> FormatType(
+    "format",
+    llvm::cl::desc("Format for outputted docs (\"adoc\" or \"xml\")."),
+    llvm::cl::init("adoc"),
+    llvm::cl::cat(Category));
+
+// Common options
+
+llvm::cl::opt<bool> IgnoreMappingFailures(
+    "ignore-map-errors",
+    llvm::cl::desc("Continue if files are not mapped correctly."),
+    llvm::cl::init(true),
+    llvm::cl::cat(Category));
+
+llvm::cl::opt<std::string> ConfigPath(
+    "config",
+    llvm::cl::desc(R"(The config filename relative to the repository root)"),
+    llvm::cl::init("mrdox.yaml"),
+    llvm::cl::cat(Category));
+
+llvm::cl::opt<std::string> OutputPath(
+    "output",
+    llvm::cl::desc("Directory or file for generating output."),
+    llvm::cl::init("."),
+    llvm::cl::cat(Category));
+
+llvm::cl::list<std::string> InputPaths(
+    "inputs",
+    llvm::cl::Sink,
+    llvm::cl::desc("The path to the compilation database, or one or more .cpp files to test."),
+    llvm::cl::cat(Category));
+
+} // mrdox
+} // clang

source/tool/Options.hpp

@@ -0,0 +1,48 @@
+//
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2023 Vinnie Falco ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdox
+//
+
+#ifndef MRDOX_TOOL_OPTIONS_HPP
+#define MRDOX_TOOL_OPTIONS_HPP
+
+#include <llvm/Support/CommandLine.h>
+#include <string>
+
+namespace clang {
+namespace mrdox {
+
+enum Action : int
+{
+    test,
+    update,
+    generate
+};
+
+extern char const* Overview;
+extern llvm::cl::OptionCategory     Category;
+extern llvm::cl::extrahelp          ExtraHelp;
+extern llvm::cl::opt<Action>        ToolAction;
+
+// Test options
+extern llvm::cl::opt<bool> badOption;
+extern llvm::cl::opt<bool> adocOption;
+
+// Generate options
+extern llvm::cl::opt<std::string> FormatType;
+
+// Common options
+extern llvm::cl::opt<bool>          IgnoreMappingFailures;
+extern llvm::cl::opt<std::string>   ConfigPath;
+extern llvm::cl::opt<std::string>   OutputPath;
+extern llvm::cl::list<std::string>  InputPaths;
+
+} // mrdox
+} // clang
+
+#endif

source/tool/SingleFileDB.hpp

@@ -0,0 +1,73 @@
+//
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2023 Vinnie Falco ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdox
+//
+
+#ifndef MRDOX_TOOL_SINGLEFILEDB_HPP
+#define MRDOX_TOOL_SINGLEFILEDB_HPP
+
+#include <clang/Tooling/CompilationDatabase.h>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace clang {
+namespace mrdox {
+
+/** Compilation database for a single .cpp file.
+*/
+class SingleFileDB
+    : public tooling::CompilationDatabase
+{
+    std::vector<tooling::CompileCommand> cc_;
+
+public:
+    SingleFileDB(
+        llvm::StringRef dir,
+        llvm::StringRef file)
+    {
+        std::vector<std::string> cmds;
+        cmds.emplace_back("clang");
+        cmds.emplace_back("-std=c++20");
+        cmds.emplace_back("-pedantic-errors");
+        cmds.emplace_back("-Werror");
+        cmds.emplace_back(file);
+        cc_.emplace_back(
+            dir,
+            file,
+            std::move(cmds),
+            dir);
+        cc_.back().Heuristic = "unit test";
+    }
+
+    std::vector<tooling::CompileCommand>
+    getCompileCommands(
+        llvm::StringRef FilePath) const override
+    {
+        if(! FilePath.equals(cc_.front().Filename))
+            return {};
+        return { cc_.front() };
+    }
+
+    std::vector<std::string>
+    getAllFiles() const override
+    {
+        return { cc_.front().Filename };
+    }
+
+    std::vector<tooling::CompileCommand>
+    getAllCompileCommands() const override
+    {
+        return { cc_.front() };
+    }
+};
+
+} // mrdox
+} // clang
+
+#endif