Crafter.Build/interfaces/Crafter.Build-External.cppm

/*
Crafter® Build
Copyright (C) 2026 Catcrafts®
Catcrafts.net

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License version 3.0 as published by the Free Software Foundation;

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
*/

module;
#include "Crafter.Build-Api.h"
export module Crafter.Build:External;
import std;
namespace fs = std::filesystem;

export namespace Crafter {
    struct Configuration;

    struct GitSource {
        std::string url;
        std::string branch;
        std::string commit;
    };

    enum class ExternalBuilder {
        None,
        CMake,
    };

    struct ExternalDependency {
        std::string name;
        GitSource source;
        ExternalBuilder builder = ExternalBuilder::None;
        std::vector<std::string> options;
        std::vector<fs::path> includeDirs;
        // Extra library search paths (each becomes a -L flag), interpreted
        // relative to the CMake build dir. Currently only honoured for
        // ExternalBuilder::CMake. The CMake builder always adds its
        // top-level build dir as a -L; libDirs is for projects (msquic,
        // others) whose CMakeLists set LIBRARY_OUTPUT_DIRECTORY to a subdir
        // of the build tree.
        std::vector<fs::path> libDirs;
        std::vector<std::string> libs;
    };

    struct ExternalBuildResult {
        std::string error;
        std::vector<std::string> compileFlags;
        std::vector<std::string> linkFlags;
        fs::file_time_type latestArtifact = fs::file_time_type::min();
    };

    CRAFTER_API ExternalBuildResult BuildExternal(
        const ExternalDependency& dep,
        std::string_view target,
        std::atomic<bool>& cancelled);

    // Specification for a sibling crafter-build project to fetch and depend on.
    // GitSource picks the revision: leave branch + commit empty for the
    // remote's default branch HEAD (sloppy but convenient), set branch to
    // track a branch tip, or set commit to pin to an immutable SHA. args are
    // forwarded verbatim to the dep's CrafterBuildProject — typically you
    // pass through the parent's args so target/march/debug propagate.
    struct GitProjectSpec {
        GitSource source;
        fs::path projectFile = "project.cpp";
        std::vector<std::string> args;
    };

    // Clones the spec's git URL into the per-project external cache (keyed by
    // url+branch+commit+args+projectFile), recursively LoadProject's the
    // remote's project.cpp, and returns a stable Configuration* you can drop
    // into cfg.dependencies. The Configuration is owned by an internal cache
    // for the lifetime of the build; identical specs share one Configuration.
    CRAFTER_API Configuration* GitProject(const GitProjectSpec& spec);

    // Specification for a local sibling crafter-build project (e.g. an
    // example folder depending on its parent project, or a workspace where
    // multiple projects live side-by-side without going through git).
    struct LocalProjectSpec {
        fs::path projectFile;             // relative to cwd or absolute
        std::vector<std::string> args;    // forwarded to dep's CrafterBuildProject
    };

    // Same as GitProject but for a local on-disk project — no fetch, no
    // cache copy. Resolves projectFile to its canonical absolute path and
    // recursively LoadProject's it. Returns a stable Configuration* owned
    // by the same internal cache as GitProject.
    CRAFTER_API Configuration* LocalProject(const LocalProjectSpec& spec);

    // Clone (or update) the given git source into the shared external
    // cache and return the path to the cloned working tree. Intended for
    // example projects that need large asset bundles which shouldn't
    // live in the parent repo — push the returned path (or specific
    // files inside it) into `cfg.assets`. Reuses the same cache root as
    // ExternalDependency / GitProject. Caching key = url + branch + commit;
    // identical calls reuse the existing clone. Pin `source.commit` to a
    // SHA for reproducible, offline-after-first-fetch builds.
    CRAFTER_API fs::path GitFetch(const GitSource& source);
}