Repository navigation
docs: why logforge exists next to spdlog, and where the boundary is - #1
Merged
Merged
Conversation
The README described what the library does but never answered the question a reader arrives with: why not call spdlog directly. The answer was spread over a bullet list, the target table and comments in a header. - README: "Why not spdlog directly" puts what you get against what you give up, and says when spdlog is the better choice. "Where spdlog is allowed to appear" splits the boundary into headers, CMake targets, process state and package config -- including the one that was not documented at all: a package built with the backend runs find_dependency(spdlog) even for a core-only consumer. "What the spdlog backend uses" lists the API surface, and what it does not use, so a replacement backend is a known amount of work. "Replacing the backend" is the checklist, plus the part a swap does not fix: libraries that log through spdlog's global logger. - The first bullet named log(level, text, size), which is not the interface, and "includes nothing", which read as "no standard headers". Both now say what the code says. The Status line moves to 1.4.1. - LOGGING.md: the backend contract gains the two rules a backend author can otherwise violate silently -- log() is called concurrently, and enabled() must agree with what log() writes. The install_as_default() paragraph says why the destructor clears logforge's default but not spdlog's, and Config::level says the two level filters are set to the same value. Co-Authored-By: BaoCode <noreply@baocode.dev>
…milestone Four places still described a version of this library that no longer exists. - spdlog_backend.hpp promised a public surface free of a specific spdlog version, and the two native* functions name spdlog::logger in their signatures. The comment now says what the forward declaration actually buys: no spdlog or fmt header in a consumer's translation unit, and no version in the ABI. - backend_configuration.cpp installed its backend with set_default() and cleared it by hand, which is what install_as_default() and the destructor have done since 1.4.0. The example now shows the recommended path. - CMakeLists.txt still announced the backend as "added in a later milestone", and told readers the backend joins the export in one. Co-Authored-By: BaoCode <noreply@baocode.dev>
Documentation only: no API, behaviour or build change. The README now answers why the library exists next to spdlog and where the boundary is, the backend contract states the two rules a backend author could break in silence, and the comments and example that still described earlier milestones are corrected. Co-Authored-By: BaoCode <noreply@baocode.dev>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The README explained what the library does but not why it exists next to spdlog. This PR answers the four questions a reader arrives with, and corrects the comments and one example that had outlived their milestone. Documentation only: no API, behaviour or build change. Version 1.4.1.
What the README now says
find_dependency(spdlog)even for a core-only consumer.Other changes
log(level, text, size), which is not the interface, and said the core "includes nothing".docs/LOGGING.md: the backend contract gains two rules a backend author could break in silence --log()runs concurrently,enabled()must agree withlog().spdlog_backend.hppno longer promises a public surface without an spdlog type; it says what the forward declaration buys.examples/backend_configuration.cppusesinstall_as_default().CMakeLists.txtcomments from milestones 0.4 and 1.0 removed.release-notes/v1.4.1.md.Verification
-DLOGFORGE_WERROR=ON, 11/11 tests each.Deferred to a separate change, noted in the project's stash: making a package built with the backend usable from a consumer that has no spdlog installed.
🤖 Generated with BaoCode