More error docs

docs/err/archive-failure.rst

+Error: Creating a static library archive failed
+###############################################
+
+``dds`` primarily works with *static libraries*, and the file format of a
+static library is known as an *archive*. This error indicates that ``dds``
+failed in its attempt to collect one or more compiled *object files* together
+into an archive.
+
+It is unlikely that regular user action can cause this error, and is more
+likely an error related to the environment and/or filesystem.
+
+If you are using a custom toolchain and have specified the archiving command
+explicitly, it may also be possible that the argument list you have given to
+the archiving tool is invalid.
+
+When archiving fails, ``dds`` will print the output and command that tried to
+generate the archive. It should provide more details into the nature of the
+failure.

docs/err/git-url-ref-mutual-req.rst

 
 When ``dds`` obtains a package from the catalog using the ``Git`` method, it
 needs a URL to clone from, and a Git ref to clone. ``dds`` uses a technique
-known as "shallow cloning," which requires a known Git reference to clone from
-the reference may be a tag, branch, or an individual commit (Using a Git commit
+known as "shallow cloning," which requires a known Git reference to clone from.
+The reference may be a tag, branch, or an individual commit (Using a Git commit
 as the ``ref`` requires support from the remote Git server, and it is often
 unavailable in most setups). Using a Git tag is strongly recommended.
 

docs/err/link-failure.rst

+Error: Linking a runtime binary failed
+######################################
+
+.. contents::
+
+.. highlight:: c++
+
+This error indicates that the final phases of the build pipeline, the link
+phases, failed.
+
+The end result of the software development process is to produce applications
+and programs that can be executed by users. In the traditional compilation and
+linking model, which we still use to this day, multiple *translation units*
+(which can be thought of as "source files") are combined together in a process
+known as *linking*. The result of linking is an actual executable.
+
+.. note::
+    Linking is also used to generate executables that are used as tests.
+    Refer: :ref:`pkgs.apps-tests`.
+
+
+What is "Linking"?
+******************
+
+The *phases of translation* define the steps taken by a compiler (and linker)
+to map from the input human-readable source code to the code that can be
+executed by a machine. The first few phases are collected bundled together in
+a phase known as "compilation," while the later phases are known as "linking."
+
+The output of the compilation phases is often generated by a *compiler* and
+then written to the filesystem. The resulting files, known as *object files*
+are then fed into another tool known as a *linker*.
+
+.. note::
+    "Object files" are just one possible intermediate product. Compilers and
+    linkers may deal with different intermediate products depending on compiler
+    and linker options.
+
+
+Symbol Reference Resolution
+***************************
+
+When code within a translation unit uses a function, variable, or member of a
+class that is declared **but not defined** in that translation unit, that
+usage is stored as an "unresolved" reference to an external symbol within the
+resulting object file.
+
+Each translation unit may also contain the *definitions* of any number of
+symbols. It is possible that other translation units may contain unresolved
+references to the symbol that the translation unit defines.
+
+It is the job of the linker to fill in these unresolved references when it
+combines translation units together.
+
+
+Failure Modes
+*************
+
+There are two very common types of linker errors that may be seen:
+
+
+Multiple Definitions Found
+==========================
+
+When translation units are combined together, the symbols within them are
+combined together into a final binary. If two or more translation units contain
+the *definition* of a single symbol, then the linker must make a decision:
+
+#. If the symbol is marked properly, then the linker can discard all except one
+   of the definitions and choose one to keep in the final binary. For example:
+   This is allowed if the associated symbol has been declared with the
+   ``inline`` keyword, or is a symbol in any context that is "implicitly
+   ``inline``," which includes member functions and static variables which are
+   defined within their class's body, and any function template.
+#. **Fail**
+
+If the linker is not allowed to discard all-but-one of the multiple
+definitions, this is a hard-error. This can happen if multiple translation
+units defined the same variable or function at the same namespace.
+
+
+Issue: A non-``inline`` function is defined in a header file
+------------------------------------------------------------
+
+A likely case is that of defining a function in a header file without
+marking it as ``inline``:
+
+.. code-block::
+    :caption: ``hello.hpp``
+
+    #ifndef MY_HEADER_INC
+    #define MY_HEADER_INC
+
+    #include <cstdio>
+
+    void say_hello() {
+        std::puts("Hello!\n");
+    }
+
+    #endif
+
+and then that header is ``#include``-ed in multiple source files:
+
+.. code-block::
+    :caption: ``a.cpp``
+
+    #include "hello.hpp"
+
+    // ... stuff ...
+
+.. code-block::
+    :caption: ``b.cpp``
+
+    #include "hello.hpp"
+
+    // .. different stuff ...
+
+.. note::
+    ``template`` functions and member functions *defined within the class body*
+    are implicitly ``inline``, and using the ``inline`` keyword is then
+    redundant.
+
+In the above configuration, the linker will generate an error about multiple
+definitions of the ``say_hello`` function. Possibly confusingly, it will point
+to ``a.cpp`` and ``b.cpp`` as the "definers" of ``say_hello``, even though it
+is actually defined in the header. The issue is that no tools are currently
+able to understand this structure in a way that they can clearly issue
+appropriate instruction on how to fix this. There are two ways to fix this:
+
+#. Add the ``inline`` keyword to the definition of ``say_hello``::
+
+        #ifndef MY_HEADER_INC
+        #define MY_HEADER_INC
+
+        #include <cstdio>
+
+        inline void say_hello() {
+            std::puts("Hello!\n");
+        }
+
+        #endif
+
+   This activates the rule that permits the linker to disregard the multiple
+   definitions and choose one to keep arbitrarily.
+
+   .. note::
+        Only use ``inline`` in headers!
+
+#. Change the definition of ``say_hello`` to be a *declaration*, and move the
+   *definition* to a separate source file:
+
+   .. code-block::
+        :caption: ``hello.hpp``
+
+        #ifndef MY_HEADER_INC
+        #define MY_HEADER_INC
+
+        #include <cstdio>
+
+        void say_hello() {
+            std::puts("Hello!\n");
+        }
+
+        #endif
+
+   .. code-block::
+        :caption: ``hello.cpp``
+
+        #include "hello.hpp"
+
+        void say_hello() {
+            std::puts("Hello!\n");
+        }
+
+   This will place the sole location of the ``say_hello`` definition within
+   ``hello.cpp``.
+
+
+Issue: There are two colliding and distinct definitions
+-------------------------------------------------------
+
+Suppose you have two different source files:
+
+.. code-block::
+    :caption: ``a.cpp``
+
+    #include "a.hpp"
+
+    void error(string message) {
+        cerr << "An error occured: " << msg << '\n';
+    }
+
+    void a_func() {
+        bool had_error = first_a();
+        if (err) {
+            error(*err);
+        }
+        err = second_a();
+        if (err) {
+            error(*err);
+        }
+    }
+
+.. code-block::
+    :caption: ``b.cpp``
+
+    void error(string message) {
+        throw runtime_error(msg);
+    }
+
+    void b_func() {
+        bool had_error = first_b();
+        if (had_error) {
+            error("The first step failed!");
+        }
+        had_error = second_b();
+        if (had_error) {
+            error("The second step failed!");
+        }
+    }
+
+The two functions, ``a_func`` and ``b_func``, despite having a similar
+structure, are *completely different* because of the behavior of ``error``:
+
+- In ``a.cpp``:
+
+    - ``error()`` will simply log a message but let execution continue.
+    - If ``first_a()`` fails, execution will continue into ``second_a()``.
+
+- In ``b.cpp``:
+
+    - ``error()`` will throw an exception.
+    - If ``first_b()`` fails, execution will never reach ``second_b()``
+
+Nevertheless, the linker will produce an error that there are multiple visible
+definitions of ``error()``, even though the translation units individually have
+no ambiguity.
+
+The issue is that both of the definitions have *external linkage* and must be
+visible to all other translation units.
+
+It may be tempting to fix this issue in the same way that we did in the prior
+example: to declare them ``inline``, and it will *seem* to have worked, but
+**this will not work correctly!!**
+
+Remember what the linker does in the presence of ``inline`` on multiple
+definitions between different translation units: It will *pick one* and
+*discard the others*. This means that either ``error`` function may replace the
+other across translation units, and the resulting code will have wildly
+different behavior.
+
+The *correct* solution is to give the ``error`` function *internal linkage*,
+which means that its definition is not visible across translation units. This
+will allow both definitions of ``error`` to live together in the linked binary
+without ambiguity. The classic way of doing this is through the usage of the
+global-scope ``static`` keyword which is present in C::
+
+    static void error(string s) {
+        // ...
+    }
+
+C++ presents another way it can be done: via an *unnamed namespace*::
+
+    namespace {
+
+    void error(string s) {
+        // ...
+    }
+
+    }  // close namespace
+
+The benefit of the unnamed namespace is it can be used to mark an entire
+section of declarations to be *internal*, and it can also be used to mark a
+class definition to have *internal linkage* (There is no way to declare a
+"``static class``").
+
+
+Unresolved External Symbol / Undefined Reference
+================================================
+
+Another common error seen while linking is that of the *unresolved external
+symbol* (Visual C++) or *undefined reference* (GCC and Clang). Both have the
+same underlying cause, and both have the same solutions.
+
+When a translation unit makes use of a symbol which has been declared *but not
+defined within that translation unit*, it is up to the linker to resolve that
+reference to another translation unit that contains the definition.
+
+If the linker is unable to find the definition of the referenced entity, it
+will emit this error.
+
+
+Issue: An external library is not being included in the link
+------------------------------------------------------------
+
+If the unresolved reference is to an entity belonging to an external library,
+you may be missing the linker inputs to actually use that library.
+
+If your project makes use of a declared entity from a third party (even if that
+usage is transitive through a dependency), it is required that the definitions
+from that third party library are included in the link step. This usually comes
+in the form of a static library, shared library/DLL, or even plain object
+files.
+
+If the external library containing the definition in question is managed by
+``dds``, this issue should never occur. If the library exists outside of
+``dds`` (e.g. a system library), then that library will need to be manually
+added as a linker input using a toolchain file using the ``Link-Flags`` option.
+See: :ref:`toolchains.opt-ref`.
+
+If the name of the unresolved symbol appears unfamiliar or you do not believe
+that you are making use of it, it is possible that one of your dependencies is
+making use of a system library symbol that needs to be part of the link. The
+link error will refer to the object/source file that is actually making the
+unresolvable reference. Seeing this filepath will be a reliable way to discover
+who would be making the reference, and therefore a good way to track down the
+dependency that needs an additional linker input. Refer to the documentation
+of the dependency in question to see if it requires additional linker inputs
+in order to be used.
+
+If the library that should contain the unresolved reference is a dependency
+managed by ``dds``, it is possible that the library author has mistakenly
+declared a symbol without providing a definition. If the definition *is*
+present in the ``dds``-provided dependency library, then the failure to resolve
+the reference would be a ``dds`` bug.
+
+
+Issue: The definition is simply missing
+---------------------------------------
+
+C and C++ allow for an entity to be *declared* and *defined* separately. If you
+*declare* and entity but do not *define* that entity, your code will work as
+long as no one attempts to refer to that entity.
+
+Ensure that the entity that is "missing" exists.
+
+
+Issue: Missing ``virtual`` method implementations
+-------------------------------------------------
+
+If the error refers to a missing ``vtable for class``, or if the error refers
+to a missing definition of a ``virtual`` function, it means that one or more
+``virtual`` functions are not defined.
+
+Note that ``virtual`` functions are slightly different in this regard: It is
+not required that someone actually make a call to the ``virtual`` function for
+the definition to be required. The metadata that the compiler generates for
+the class containing the ``virtual`` functions will implicitly form a reference
+to every ``virtual`` function, so they must all be defined if someone attempts
+to instantiate the class, as instantiating the class will form a reference to
+that metadata.
+
+
+Issue: Mismatched declarations and definitions
+----------------------------------------------
+
+Suppose you have a header file and a corresponding source file:
+
+.. code-block::
+    :caption: ``a.hpp``
+
+    namespace foo {
+
+    size_t string_length(const string& str);
+
+    }
+
+.. code-block::
+    :caption: ``a.cpp``
+
+    #include "a.hpp"
+
+    using namespace foo;
+
+    size_t string_length(const string& str) {
+        // ... implementation goes here ...
+    }
+
+The above code will link correctly, as the definition of ``foo::string_length``,
+is available from ``a.cpp``, while the declaration exists in ``a.hpp``.
+
+However, if we modify *only the declaration* to use ``string_view`` instead of
+``const string&``, something different occurs::
+
+    namespace foo {
+
+    size_t string_length(string_view str);
+
+    }
+
+It may be tempting to say that "our declaration and definition do not match,"
+but that is semantically incorrect: We have declared a function
+``size_t foo::string_length(string_view)``, but we have defined *and declared*
+a **completely different function** ``size_t string_length(const string&)``!
+The compiler will not warn about this: There is nothing semantically incorrect
+about this code.
+
+The linker, however, will not find any definition of ``foo::string_length``.
+The function ``::string_length(const string&)`` isn't even in the ``foo``
+``namespace``: It was declared and defined at the global scope within
+``a.cpp``.
+
+If you are seeing an error about an unresolved reference to a function that is
+declared and defined separately, and you are *sure* is being compiled, check
+that the signature (and name) of the definition and declaration match
+*exactly*.
+
+.. tip::
+    In essence, the error originates from relying on the
+    ``using namespace foo`` directive to cause the definition of
+    ``string_length`` to incidentally hit the name lookup of the prior
+    declaration.
+
+    In C++, using a *qualified name* at the definition site can prevent this
+    error from slipping through::
+
+        #include "a.hpp"
+
+        using namespace foo;
+
+        size_t foo::string_length(const string& str) {
+            // ... implementation goes here ...
+        }
+
+    By using the qualified name ``foo::string_length`` at the definition site,
+    the compiler will validate that the function being defined has a prior
+    declaration that matches *exactly* to the signature of the definition.
+
+    Note that this *is not* the same as defining the function within a
+    ``namespace`` block::
+
+        #include "a.hpp"
+
+        // NOT HELPFUL!
+
+        namespace foo {
+
+        size_t string_length(const string& str) {
+            // ... implementation goes here ...
+        }
+
+        }
+
+    This will suffer the same potential mistake as defining it with an
+    unqualified name.
+
+    Note that within the scope of a function that has been declared within the
+    namespace, that namespace is currently within scope even if the definition
+    itself is not wrapped in a ``namespace`` block. It may be a good option to
+    simply remove the ``using namespace`` directive altogether.
+
+    .. note::
+        This trick cannot be applied to names that are declared at the global
+        scope, since you cannot use the global-namespace qualifier at a
+        function definition (it is not valid syntax)::
+
+            // Declaration at global scope
+            void some_function();
+
+            // Definition? No: Invalid syntax!
+            void ::some_function() {
+                // ... stuff ...
+            }
+
+
+Issue: The source file containing definition is not being included in the link
+------------------------------------------------------------------------------
+
+If the translation unit that contains the definition of an entity is not being
+passed to the linker, the linker will not be able to find it!
+
+If you are using ``dds`` correctly, and the compiled source file containing the
+definition is placed as a (direct or indirect) descendent of the ``src/``
+directory, then ``dds`` will always include that source file as part of the
+link for the enclosing library.
+
+Build systems that require you to enumerate your source files explicitly will
+not automatically see a source file unless it has been added to the source
+list. Even build systems that allow directory-globbing (like CMake) will need
+to have the globbing pattern match the path to the source file.

docs/err/test-failure.rst

+Error: One or more tests failed
+###############################
+
+This error message is printed when a project's tests encounter a failure
+condition. The exact behavior of tests is determined by a project's
+``Test-Driver``.
+
+If you see this error, it is most likely that you have an issue in the tests of
+your project.
+
+When a project is built with the ``build`` command, it is the default behavior
+for ``dds`` to compile, link, and execute all tests defined for the project.
+Test execution can be suppressed using the ``--no-tests`` command line option
+with the ``build`` subcommand.
+
+.. seealso::
+    Refer to the page on :ref:`pkgs.apps-tests`.

docs/guide/catalog.rst

 
     dds catalog add <package-id>
         [--depends <requirement> [--depends <requirement> [...]]]
-        [--git-url <url>]
-        [--git-ref <ref>]
+        [--git-url <url> --git-ref <ref>]
         [--auto-lib <Namespace>/<Name>]
 
 The ``<package-id>`` positional arguments is the ``name@version`` package ID

docs/guide/packages.rst

     together as part of *source distribution*.
 
 
+.. _pkgs.apps-tests:
+
 Applications and Tests
 **********************
 

docs/guide/toolchains.rst

     Link-Flags: -fsanitize=address -fPIE
 
 
+.. _toolchains.opt-ref:
+
 Toolchain Option Reference
 **************************
 

docs/tut/hello-test.rst

 *********************************
 
 ``dds`` ships with built-in support for the `Catch2`_ C and C++ testing
-framework, a popular
+framework.
 
 .. _catch2: https://github.com/catchorg/Catch2
 

docs/tut/hello-world.rst

 
 To start, create a new directory for your project. This will be known as the
 *package root*, and the entirety of our project will be placed in this
-directory the name and location of this directory is not important, but the
+directory. The name and location of this directory is not important, but the
 contents therein will be significant.
 
 .. note::
 named ``_build``. Within this directory, you will find the generated executable
 named ``hello-world`` (with a ``.exe`` suffix if on Windows).
 
-We should not be able to run this executable and see our ``Hello, world!``::
+We should now be able to run this executable and see our ``Hello, world!``::
 
     > ./_build/hello-world
     Hello, world!
 
-Obviously this isn't *all* there is to do with ``dds``. Read on to the next
-pages to learn more.
-
-.. note::
-    You're reading a very early version of these docs. There will be a lot more
-    here in the future. Watch this space for changes!
-
-
 More Sources
 ************
 

src/dds.main.cpp

     } catch (const dds::user_cancelled&) {
         spdlog::critical("Operation cancelled by user");
         return 2;
-    } catch (const dds::user_error_base& e) {
+    } catch (const dds::error_base& e) {
         spdlog::error("{}", e.what());
         spdlog::error("{}", e.explanation());
         spdlog::error("Refer: {}", e.error_reference());

src/dds/build/builder.cpp

 #include <dds/build/plan/full.hpp>
 #include <dds/catch2_embedded.hpp>
 #include <dds/compdb.hpp>
+#include <dds/error/errors.hpp>
 #include <dds/usage_reqs.hpp>
 #include <dds/util/time.hpp>
 
                       failures.output);
     }
     if (!test_failures.empty()) {
-        throw compile_failure("Test failures during the build!");
+        throw_user_error<errc::test_failure>();
     }
 
     if (params.emit_lmi) {

src/dds/build/plan/archive.cpp

 #include "./archive.hpp"
 
+#include <dds/error/errors.hpp>
 #include <dds/proc.hpp>
 #include <dds/util/time.hpp>
 
     if (!ar_res.okay()) {
         spdlog::error("Creating static library archive failed: {}", out_relpath);
         spdlog::error("Subcommand FAILED: {}\n{}", quote_command(ar_cmd), ar_res.output);
-        throw std::runtime_error(
-            fmt::format("Creating archive [{}] failed for '{}'", out_relpath, _name));
+        throw_external_error<
+            errc::archive_failure>("Creating static library archive [{}] failed for '{}'",
+                                   out_relpath,
+                                   _name);
     }
 }

src/dds/build/plan/exe.cpp

 #include "./exe.hpp"
 
 #include <dds/build/plan/library.hpp>
+#include <dds/error/errors.hpp>
 #include <dds/proc.hpp>
 #include <dds/util/algo.hpp>
 #include <dds/util/time.hpp>
 
     // Check and throw if errant
     if (!proc_res.okay()) {
-        throw compile_failure(
-            fmt::format("Failed to link test executable '{}'. Link command [{}] returned {}:\n{}",
-                        spec.output.string(),
-                        quote_command(link_command),
-                        proc_res.retc,
-                        proc_res.output));
+        throw_external_error<
+            errc::link_failure>("Failed to link executable [{}]. Link command was [{}]",
+                                spec.output.string(),
+                                quote_command(link_command),
+                                proc_res.retc,
+                                proc_res.output);
     }
 }
 

src/dds/error/errors.cpp

         return "no-such-catalog-package.html";
     case errc::git_url_ref_mutual_req:
         return "git-url-ref-mutual-req.html";
+    case errc::test_failure:
+        return "test-failure.html";
+    case errc::archive_failure:
+        return "archive-failure.html";
+    case errc::link_failure:
+        return "link-failure.html";
     case errc::none:
         break;
     }
         return R"(
 Creating a Git-based catalog entry requires both a URL to clone from and a Git
 reference (tag, branch, commit) to clone.
+)";
+    case errc::test_failure:
+        return R"(
+One or more of the project's tests failed. The failing tests are listed above,
+along with their exit code and output.
+)";
+    case errc::archive_failure:
+        return R"(
+Creating a static library archive failed, which prevents the associated library
+from being used as this archive is the input to the linker for downstream
+build targets.
+
+It is unlikely that regular user action can cause static library archiving to
+fail. Refer to the output of the archiving tool.
+)";
+    case errc::link_failure:
+        return R"(
+Linking a runtime binary file failed. There are a variety of possible causes
+for this error. Refer to the documentation for more information.
 )";
     case errc::none:
         break;
         return "The catalog has no entry for the given package ID";
     case errc::git_url_ref_mutual_req:
         return "Git requires both a URL and a ref to clone";
+    case errc::test_failure:
+        return "One or more tests failed";
+    case errc::archive_failure:
+        return "Creating a static library archive failed";
+    case errc::link_failure:
+        return "Linking a runtime binary (executable/shared library/DLL) failed";
     case errc::none:
         break;
     }
     assert(false && "Unexpected execution path during error message creation. This is a DDS bug");
     std::terminate();
-}
+}

src/dds/error/errors.hpp

 
 namespace dds {
 
-struct exception_base : std::runtime_error {
-    using runtime_error::runtime_error;
-};
-
-struct user_error_base : exception_base {
-    using exception_base::exception_base;
-
-    virtual std::string      error_reference() const noexcept = 0;
-    virtual std::string_view explanation() const noexcept     = 0;
-};
-
 enum class errc {
     none = 0,
     invalid_builtin_toolchain,
     no_such_catalog_package,
     git_url_ref_mutual_req,
+    test_failure,
+    archive_failure,
+    link_failure,
 };
 
 std::string      error_reference_of(errc) noexcept;
 std::string_view explanation_of(errc) noexcept;
 std::string_view default_error_string(errc) noexcept;
+struct exception_base : std::runtime_error {
+    using runtime_error::runtime_error;
+};
+
+struct error_base : exception_base {
+    using exception_base::exception_base;
+
+    virtual errc     get_errc() const noexcept = 0;
+    std::string      error_reference() const noexcept { return error_reference_of(get_errc()); }
+    std::string_view explanation() const noexcept { return explanation_of(get_errc()); }
+};
+
+struct external_error_base : error_base {
+    using error_base::error_base;
+};
+
+struct user_error_base : error_base {
+    using error_base::error_base;
+};
 
 template <errc ErrorCode>
 struct user_error : user_error_base {
     using user_error_base::user_error_base;
+    errc get_errc() const noexcept override { return ErrorCode; }
+};
 
-    std::string error_reference() const noexcept override { return error_reference_of(ErrorCode); }
-    std::string_view explanation() const noexcept override { return explanation_of(ErrorCode); }
+template <errc ErrorCode>
+struct external_error : external_error_base {
+    using external_error_base::external_error_base;
+    errc get_errc() const noexcept override { return ErrorCode; }
 };
 
 using error_invalid_default_toolchain = user_error<errc::invalid_builtin_toolchain>;
     throw user_error<ErrorCode>(std::string(default_error_string(ErrorCode)));
 }
 
+template <errc ErrorCode, typename... Args>
+[[noreturn]] void throw_external_error(std::string_view fmt_str, Args&&... args) {
+    throw external_error<ErrorCode>(fmt::format(fmt_str, std::forward<Args>(args)...));
+}
+
+template <errc ErrorCode>
+[[noreturn]] void throw_external_error() {
+    throw external_error<ErrorCode>(std::string(default_error_string(ErrorCode)));
+}
+
 }  // namespace dds