Add user-local default toolchain lookup semantics [Close #18] [Close

docs/err/no-default-toolchain.rst

+Error: Unable to find a default toolchain to use for the build
+##############################################################
+
+Unlike other build systems, ``dds`` will not attempt to make a "best guess"
+about the local platform and the available build toolchains. Instead, a
+toolchain must be provided for every build. This can be named on the command
+line with ``--toolchain`` or by placing a toolchain file in one of a few
+prescribed locations.
+
+
+Solution: Request a built-in toolchain
+**************************************
+
+A built-in toolchain can be specified with the ``--toolchain`` (or ``-t``)
+argument. Refer to the :ref:`toolchains.builtin` section for more information.
+
+
+Solution: Set up a default toolchain file for the project or for your local user
+********************************************************************************
+
+If no toolchain argument is given when a build is invoked, ``dds`` will search
+a predefined set of filepaths for the existence of a toolchain file to use as
+the "default." Writing a simple toolchain to one of these paths will cause
+``dds`` to use this toolchain when none was provided.
+
+
+.. seealso::
+    For more information, refer to the full documentation page:
+    :doc:`/guide/toolchains`

docs/guide/toolchains.rst

     Sets the C++ version to ``C++UV`` and uses the ``:XYZ`` toolchain.
 
 
+.. _toolchains.default:
+
+Providing a Default Toolchain File
+**********************************
+
+If you do not which to provide a new toolchain for every individual project,
+and the built-in toolchains do not suit your needs, you can write a toolchain
+file to one of a few predefined paths, and ``dds`` will find and use it for the
+build. The following paths are searched, in order:
+
+#. ``$pwd/toolchain.dds`` - If the working directory contains ``toolchain.dds``,
+   it will be used as the default.
+#. ``$dds_config_dir/toolchain.dds`` - Searches for a toolchain file in
+   ``dds``'s user-local configuration directory (see below).
+#. ``$user_home/toolchain.dds`` - Searches for a toolchain file at the root of
+   the current user's home directory. (``$HOME`` on Unix-like systems, and
+   ``$PROFILE`` on Windows.)
+
+The ``$dds_user_config`` directory is the ``dds`` subdirectory of the
+user-local configuration directory.
+
+The user-local config directory is ``$XDG_CONFIG_DIR`` or ``~/.config`` on
+Linux, ``~/Library/Preferences`` on macOS, and ``~/AppData/Roaming`` on
+Windows.
+
+
 Toolchain Definitions
 *********************
 

src/dds.main.cpp

     toolchain_flag(args::Group& grp)
         : string_flag{grp,
                       "toolchain_file",
-                      "Path/ident of the toolchain to use",
-                      {"toolchain", 't'},
-                      (dds::fs::current_path() / "toolchain.dds").string()} {}
+                      "Path/identifier of the toolchain to use",
+                      {"toolchain", 't'}} {}
 
     dds::toolchain get_toolchain() {
+        if (*this) {
+            return get_arg();
+        } else {
+            auto found = dds::toolchain::get_default();
+            if (!found) {
+                dds::throw_user_error<dds::errc::no_default_toolchain>();
+            }
+            return *found;
+        }
+    }
+
+    dds::toolchain get_arg() {
         const auto tc_path = this->Get();
         if (tc_path.find(":") == 0) {
             auto default_tc = tc_path.substr(1);

src/dds/error/errors.cpp

     switch (ec) {
     case errc::invalid_builtin_toolchain:
         return "invalid-builtin-toolchain.html";
+    case errc::no_default_toolchain:
+        return "no-default-toolchain.html";
     case errc::no_such_catalog_package:
         return "no-such-catalog-package.html";
     case errc::git_url_ref_mutual_req:
 
 These toolchain names are encoded into the dds executable and cannot be
 modified.
+)";
+    case errc::no_default_toolchain:
+        return R"(
+`dds` requires a toolchain to be specified in order to execute the build. `dds`
+will not perform a "best-guess" at a default toolchain. You may either pass the
+name of a built-in toolchain, or write a "default toolchain" file to one of the
+supported filepaths. Refer to the documentation for more information.
 )";
     case errc::no_such_catalog_package:
         return R"(
     switch (ec) {
     case errc::invalid_builtin_toolchain:
         return "The built-in toolchain name is invalid";
+    case errc::no_default_toolchain:
+        return "Unable to find a default toolchain to use for the build";
     case errc::no_such_catalog_package:
         return "The catalog has no entry for the given package ID";
     case errc::git_url_ref_mutual_req:

src/dds/error/errors.hpp

 enum class errc {
     none = 0,
     invalid_builtin_toolchain,
+    no_default_toolchain,
     no_such_catalog_package,
     git_url_ref_mutual_req,
     test_failure,

src/dds/toolchain/toolchain.cpp

 #include <dds/toolchain/from_dds.hpp>
 #include <dds/toolchain/prep.hpp>
 #include <dds/util/algo.hpp>
+#include <dds/util/paths.hpp>
 #include <dds/util/string.hpp>
 
 #include <cassert>
     tc_content += "Compiler-ID: " + opt_triple->id + "\n";
     return parse_toolchain_dds(tc_content);
 }
+
+std::optional<dds::toolchain> dds::toolchain::get_default() {
+    auto candidates = {
+        fs::current_path() / "toolchain.dds",
+        dds_config_dir() / "toolchain.dds",
+        user_home_dir() / "toolchain.dds",
+    };
+    for (auto&& cand : candidates) {
+        if (fs::exists(cand)) {
+            return parse_toolchain_dds(slurp_file(cand));
+        }
+    }
+    return std::nullopt;
+}

src/dds/toolchain/toolchain.hpp

     std::vector<std::string> create_link_executable_command(const link_exe_spec&) const noexcept;
 
     static std::optional<toolchain> get_builtin(std::string_view key) noexcept;
+    static std::optional<toolchain> get_default();
 };
 
 }  // namespace dds