// mcpp.plugins.tool -- where a tool a plugin runs comes from (L2 of the

// build-plugin architecture; mcpp#755, protocol 15).

//

// A member that runs a program -- cmake, glslangValidator, slangc, nvcc,

// appimagetool -- answers one question before it can plan anything: which

// program. Each member used to answer it its own way: an option here, an

// environment variable there, a silent PATH fallback in two members and a

// refusal of PATH in two others. This module answers it once, in one order:

//

// 1. the build program's choice `o.cmake = "/usr/bin/cmake"`, or

// `tool::on_path()`, `tool::root(dir)`

// 2. a member's legacy variable `MCPP_SLANGC`, kept for compatibility

// 3. the engine's override `[xlings.overrides]`,

// `MCPP_XLINGS_OVERRIDE_<NS>_<NAME>`,

// config.toml -- the payload is then not

// installed at all

// 4. the declared payload installed before the program runs, or,

// declared `provision = "on-request"`,

// asked for here and installed then

//

// A CHOICE NEVER ASKS FOR THE PAYLOAD. That is what makes "the build program

// names its own tool" mean "the payload is not downloaded": a member whose

// payload is declared on request calls `resolve`, and only the fourth step

// requests it.

//

// EVERY ANSWER IS RECORDED. `resolve` states a `mcpp:decision=` with the

// source and, for a choice, the `build.mcpp` line that made it, so the build

// reports `Using cmake (mcpp.deps.cmake) ← /usr/bin/cmake [program ·

// build.mcpp:9]` and `mcpp why tool cmake` answers from the same record.

module;

#include <cstdlib>

export module mcpp.plugins.tool;

import std;

import mcpp;

namespace mcpp::plugins::tool::detail {

inline bool is_file(const std::filesystem::path& p) {

std::error_code ec;

return !p.empty() && std::filesystem::is_regular_file(p, ec);

}

inline std::string generic(const std::filesystem::path& p) {

return p.lexically_normal().generic_string();

}

#if defined(_WIN32)

inline constexpr char kPathSep = ';';

inline constexpr std::string_view kExe = ".exe";

#else

inline constexpr char kPathSep = ':';

inline constexpr std::string_view kExe = "";

#endif

// `<dir>/<name>`, with and without `.exe`.

//

// BOTH SPELLINGS ON EVERY HOST, and the suffix of the machine doing the

// building is only the preferred one. A payload repacked with the other

// convention is then found instead of silently missed, and the cost is one

// `stat`; it is also what lets a plugin's test state a Windows row and run on

// Linux, which `mcpp.plugins.testing` does.

inline std::string program_in(const std::filesystem::path& dir, std::string_view name) {

const std::string bare(name);

const std::string exe = bare + ".exe";

for (auto const& cand : kExe.empty() ? std::array<std::string, 2>{bare, exe}

: std::array<std::string, 2>{exe, bare}) {

auto p = dir / cand;

if (is_file(p)) return generic(p);

}

return {};

}

// A STATED PATH, WITH THE SAME SUFFIX RULE AS A DISCOVERED ONE. A build program

// writes the path a shell gave it, and on Windows `command -v cmake` answers

// `C:/Program Files/CMake/bin/cmake` for a `cmake.exe`; process creation there

// appends the suffix itself, so a resolver that insisted on the exact spelling

// refused a program the host would have run (measured in CI: the cmake consumer

// reported `options::cmake = "C:/Program Files/CMake/bin/cmake" (not found)` on a

// runner carrying cmake). Empty when neither spelling is a file.

inline std::string program_at(const std::filesystem::path& p) {

if (is_file(p)) return generic(p);

auto with = p;

with += ".exe";

if (is_file(with)) return generic(with);

if (p.extension() == ".exe") {

auto without = p;

without.replace_extension();

if (is_file(without)) return generic(without);

}

return {};

}

inline std::string find_on_path(std::string_view name) {

const char* path = std::getenv("PATH");

if (!path) return {};

std::string_view rest(path);

while (!rest.empty()) {

auto sep = rest.find(kPathSep);

auto dir = rest.substr(0, sep);

if (!dir.empty())

if (auto p = program_in(std::filesystem::path(dir), name); !p.empty()) return p;

if (sep == std::string_view::npos) break;

rest.remove_prefix(sep + 1);

}

return {};

}

// The root a program implies: `<root>/bin/<program>`, or its directory.

inline std::string root_of(const std::filesystem::path& program) {

auto dir = program.parent_path();

if (dir.filename() == "bin") return generic(dir.parent_path());

return generic(dir);

}

} // namespace mcpp::plugins::tool::detail

export namespace mcpp::plugins::tool {

// WHAT A BUILD PROGRAM STATES ABOUT ONE TOOL, as a member's option.

//

// A STRING IS A PROGRAM, so every option that was a `std::string` keeps its

// spelling: `o.cmake = "/usr/bin/cmake"` constructs a choice, and an empty

// string is the default. The constructor's default argument records the line

// of the assignment -- `std::source_location::current()` in a default

// argument is evaluated where the call is written, which is the build

// program -- and the line reaches the decision record.

struct choice {

enum class kind { payload, program, root, on_path };

kind how = kind::payload;

std::string value;

std::source_location where{};

choice() = default;

choice(std::string program,

std::source_location w = std::source_location::current())

: how(program.empty() ? kind::payload : kind::program),

value(std::move(program)), where(w) {}

choice(const char* program,

std::source_location w = std::source_location::current())

: choice(std::string(program ? program : ""), w) {}

// The default: the engine's answer (override or payload).

bool is_default() const { return how == kind::payload; }

// The text a member stored before this type, for code that read it.

const std::string& str() const { return value; }

};

inline choice payload() { return {}; }

// This program. A relative path is relative to the package root.

inline choice program(std::string path,

std::source_location w = std::source_location::current()) {

choice c; c.how = choice::kind::program; c.value = std::move(path); c.where = w; return c;

}

// A directory laid out like the payload (`<root>/bin/<program>`).

inline choice root(std::string dir,

std::source_location w = std::source_location::current()) {

choice c; c.how = choice::kind::root; c.value = std::move(dir); c.where = w; return c;

}

// The first program of the member's list found on PATH, or `name`.

inline choice on_path(std::string name = {},

std::source_location w = std::source_location::current()) {

choice c; c.how = choice::kind::on_path; c.value = std::move(name); c.where = w; return c;

}

// WHAT A MEMBER KNOWS ABOUT ONE OF ITS TOOLS, written once per tool.

struct spec {

std::string who; // the member's module: "mcpp.deps.cmake"

std::string ns = "xim"; // the payload's namespace

std::string package; // the payload: "cmake"

std::vector<std::string> programs; // program names, in preference order

std::vector<std::string> bin_dirs = {"bin", ""}; // where, under a root

std::string option; // "options::cmake", for messages

std::string legacy_env; // a variable the member read before, or empty

// Ask for a payload declared `provision = "on-request"` when nothing else

// answers. A member that only looks (to report what is there) passes false.

bool request = true;

};

enum class from { choice, legacy_env, override_, payload, path, none, pending };

inline std::string_view name(from f) {

switch (f) {

case from::choice: return "choice";

case from::legacy_env: return "env";

case from::override_: return "override";

case from::payload: return "payload";

case from::path: return "path";

case from::pending: return "pending";

case from::none: break;

}

return "none";

}

struct found {

std::string program; // the program, absolute, forward slashes

std::string root; // the root it implies, when one does

from source = from::none;

// What was consulted and what each answered, for `describe_missing`.

std::vector<std::string> tried;

explicit operator bool() const { return !program.empty(); }

// The payload was asked for: the engine installs it and runs the program

// again. The member returns without planning what needs the tool.

bool pending() const { return source == from::pending; }

};

// The subject of the decision record: `tool:<module>:<name>`.

inline std::string subject_of(const spec& s) {

return "tool:" + s.who + ":" + (s.programs.empty() ? s.package : s.programs.front());

}

// The program in a root, by the member's names and directories.

inline std::string program_in_root(const spec& s, const std::filesystem::path& root) {

for (auto const& sub : s.bin_dirs)

for (auto const& p : s.programs)

if (auto hit = detail::program_in(sub.empty() ? root : root / sub, p); !hit.empty())

return hit;

return {};

}

inline found resolve(const spec& s, const choice& c = {}) {

found out;

const auto payloadKey = s.ns + ":" + s.package;

auto record = [&](from f, std::string_view file = {}, unsigned line = 0) {

out.source = f;

mcpp::decision(subject_of(s).c_str(), std::string(name(f)).c_str(),

out.program.c_str(), std::string(file).c_str(), line,

payloadKey.c_str());

};

// 1. The build program's choice.

if (!c.is_default()) {

const std::string file = c.where.file_name() ? c.where.file_name() : "";

const auto line = static_cast<unsigned>(c.where.line());

std::filesystem::path base = mcpp::manifest_dir();

switch (c.how) {

case choice::kind::program: {

std::filesystem::path p(c.value);

if (p.is_relative() && p.has_parent_path()) p = base / p;

if (!p.has_parent_path()) { // a bare name: on PATH

out.program = detail::find_on_path(c.value);

if (!out.program.empty()) {

out.root = detail::root_of(out.program);

record(from::choice, file, line);

return out;

}

} else if (auto hit = detail::program_at(p); !hit.empty()) {

out.program = std::move(hit);

out.root = detail::root_of(out.program);

record(from::choice, file, line);

return out;

}

out.tried.push_back(std::format("{} = \"{}\" (not found)", s.option, c.value));

return out; // a stated choice that fails is not replaced by another source

}

case choice::kind::root: {

std::filesystem::path r(c.value);

if (r.is_relative()) r = base / r;

out.program = program_in_root(s, r);

if (!out.program.empty()) {

out.root = detail::generic(r);

record(from::choice, file, line);

return out;

}

out.tried.push_back(std::format("{} = root(\"{}\") (no {} there)", s.option,

c.value, s.programs.empty() ? s.package : s.programs.front()));

return out;

}

case choice::kind::on_path: {

std::vector<std::string> names = c.value.empty() ? s.programs

: std::vector<std::string>{c.value};

for (auto const& n : names)

if (auto p = detail::find_on_path(n); !p.empty()) {

out.program = p;

out.root = detail::root_of(p);

record(from::path, file, line);

return out;

}

out.tried.push_back(std::format("{} = on_path() (not on PATH)", s.option));

return out;

}

case choice::kind::payload: break;

}

}

out.tried.push_back(std::format("{} (not set)", s.option));

// 2. The member's legacy variable.

if (!s.legacy_env.empty()) {

mcpp::rerun_if_env_changed(s.legacy_env.c_str());

if (const char* v = std::getenv(s.legacy_env.c_str()); v && *v) {

out.program = detail::generic(v);

out.root = detail::root_of(out.program);

out.source = from::legacy_env;

mcpp::decision(subject_of(s).c_str(), "env", out.program.c_str(),

s.legacy_env.c_str(), 0, payloadKey.c_str());

return out;

}

out.tried.push_back(std::format("{} (not set)", s.legacy_env));

}

// 3 and 4. The engine's answer: an override, or the payload.

const std::string source = mcpp::xpkg_source(s.ns.c_str(), s.package.c_str());

if (source == "override") {

out.program = mcpp::xpkg_program(s.ns.c_str(), s.package.c_str());

const std::string dir = mcpp::xpkg_dir(s.ns.c_str(), s.package.c_str());

if (out.program.empty() && !dir.empty()) out.program = program_in_root(s, dir);

out.root = dir;

if (!out.program.empty()) { record(from::override_); return out; }

out.tried.push_back(std::format("the override of {} (names no {} under '{}')",

payloadKey, s.programs.empty() ? s.package

: s.programs.front(), dir));

return out;

}

if (source == "pending" && s.request) {

(void)mcpp::xpkg_request(s.ns.c_str(), s.package.c_str());

out.source = from::pending;

out.tried.push_back(std::format("payload {} (requested)", payloadKey));

return out;

}

if (const std::string dir = mcpp::xpkg_dir(s.ns.c_str(), s.package.c_str()); !dir.empty()) {

out.program = program_in_root(s, dir);

out.root = dir;

if (!out.program.empty()) { record(from::payload); return out; }

out.tried.push_back(std::format("payload {} at '{}' (no {} in it)", payloadKey, dir,

s.programs.empty() ? s.package : s.programs.front()));

return out;

}

out.tried.push_back(source == "pending"

? std::format("payload {} (declared on request, not requested)", payloadKey)

: std::format("payload {} (not declared for this build, or not installed)", payloadKey));

return out;

}

// THE ONE REFUSAL TEXT: what was consulted, and the four ways to name the

// tool. A member prints it with `mcpp::warning` (R1.2) or its own stream.

inline std::string describe_missing(const spec& s, const found& f) {

const auto tool = s.programs.empty() ? s.package : s.programs.front();

const auto key = s.ns + ":" + s.package;

std::string env = "MCPP_XLINGS_OVERRIDE_";

for (char ch : key)

env += (ch >= 'a' && ch <= 'z') ? char(ch - 'a' + 'A')

: ((ch >= 'A' && ch <= 'Z') || (ch >= '0' && ch <= '9')) ? ch : '_';

std::string out = std::format("{}: no {}.\n", s.who, tool);

for (auto const& t : f.tried) out += " consulted: " + t + "\n";

out += std::format(

" Any one of these names it:\n"

" o.{} = \"/path/to/{}\"; // build.mcpp\n"

" [xlings.overrides] \"{}\" = \"/path\" // mcpp.toml\n"

" {}=/path // environment\n"

" or install the payload: `mcpp build` provisions {} when it is declared.",

s.option.starts_with("options::") ? s.option.substr(9) : s.option, tool, key, env, key);

return out;

}

} // namespace mcpp::plugins::tool