Repository navigation
π Features
New features and additions
- β¨ plugins: Native plugins that load only into the build they target.1 a19da39
- π« Support plugins.2 (Closes #58.) 237be77
- π Let plugins also install corpus transforms.3 4a40a1f
- β¨ docs: Add Plausible analytics.4 (Refs #1353) 9faf2d7 (thanks @julioest)
π Fixes
Bug fixes and error corrections
- The include-dir probe uses the compiler and sysroot of the compile command.5 d46730d
- Export the public API when MrDocs is built.6 (mode: a plugin built without
NDEBUGcalls it from the inline code of) bcbe2f9 - bootstrap: Clang_ROOT pinned to the LLVM recipe install.7 (Fixes #1337) 2ceca8f (thanks @SuchaharCan)
- config: Non-standard attributes off by default. 744b43e
- extensions: An empty Lua table is accepted for an object field. af3a320
β‘οΈ Performance
Performance optimizations and enhancements
β»οΈ Refactor
Code refactoring and restructuring
- extensions: One pipeline and described contexts for scripts and plugins.9 cead178
- report: One reporter, owned by the session and passed to whoever reports.10 591b814
π Documentation
Documentation updates and improvements
- contribute: Contributor guide reorganized around the codebase.11 2d29928
- ui: Body copy off-center on pages without a contents rail. 917352d
π¦οΈ Build
Build system and configuration changes
π§ͺ Tests
Test cases and testing-related changes
π¦ Continuous Integration
Changes related to continuous integration
ποΈ Chores
Routine tasks, maintenance, and housekeeping
-
This finishes the plugin support Gennaro started. A plugin is a shared library that registers transforms and generators with
registerTransformandregisterGenerator, each taking an id and a callable.A plugin sees MrDocs's C++ types by their layout, so it must match the exact build:- the loader (our owndlopenandLoadLibraryEx, never unloaded) refuses a plugin whose build id differs. The build id is the commit hash, with.modifiedfor an edited tree, and comes fromgit-archival.txtin a source archive.- a plugin built against another standard library fails at its first compile, and the loader checks the tag again.- the tool exports only the MrDocs API. Each public class carries the marker its members need:MRDOCS_DECLwhen a member is compiled into MrDocs,MRDOCS_VISIBLEfor type information only, and the self-doc run checks every case.- dom and handlebars symbols stay visible in a hidden core, and shared builds load plugins with the same recipe.Plugins linkmrdocs::plugin-api, andmrdocs_add_pluginships with the CMake package. The integration tests cover the refusals, symbol isolation, dependencies, reloading and a consumer built with another compiler. The user docs explain what must match and how to build a plugin. β© -
MrDocs loads the shared libraries in the plugins subdirectory of eachaddon root as it starts up, and lets each one install a generator. Aplugin resolves the MrDocs symbols it calls against the tool, so writingan output format takes the MrDocs headers and nothing else: no LLVM, noClang, no separate library to ship.The tool links mrdocs-core privately now, so that a plugin linking thetool does not link the core as well.Note that a statically linked MrDocs, such as the Linux release, cannotload plugins.
MRDOCS_BUILD_PLUGIN_MODULESis off by default there, andin a shared build, and a MrDocs built without it reports a plugin itfinds instead of loading it. β© -
A plugin could install a generator, so it could add an output format butnot change what any format sees. We now let a plugin install corpustransforms too, closing the gap with extension scripts.
loadPluginsreturns them in aPluginRegistry, which the tool appliesbefore the script transforms, as it applies anExtensionRegistry. β© -
Injected only on mrdocs.com hosts. Docs read the idfrom site.keys.plausible; the landing page inlines it. β©
-
MrDocs finds the default include directories by running the compiler of each compile command with
-v -E. It ran that compiler without the command's-isysrootor--sysroot, so Xcode's toolchainclang++listed no SDK headers and<cstdint>was missing. It also treated a bare name such asclang++as a file path, found nothing, and fell back to guessing a compiler.The probe now passes the command's sysroot and looks a bare compiler name up on PATH, the way the driver runs it. It falls back to$CXX,$CCand common names only when the command's compiler cannot be found. β© -
MRDOCS_DECLexpanded to nothing in a static build, so it markednothing and its misuse went unnoticed: it was applied to some classesand to some of their members, which MSVC rejects.MRDOCS_TOOLnowcomes first, so a plugin can call the symbols the headers declare, whilea static consumer still sees plain declarations.Marking the API also exposed declarations that had no marker at all,such as the symbol kinds'operator<=>and severalCorpusmembers,which a plugin reaches from inline and template code. We mark them now.The dom and handlebars libraries check build defines of their own in thesame place,MRDOCS_DOM_BUILDINGandMRDOCS_HANDLEBARS_BUILDING,which only their own targets set, so that their headers do not depend onthe tool's.We also declareassert_failed, withMRDOCS_DECL, in every buildthe public headers, whatever mode MrDocs was built in. β© -
A recipe can list several _ROOT names ("package_root_var"accepts a string or a list). The LLVM recipe lists LLVM_ROOT andClang_ROOT, so the generated user preset sets both to the same installdir. Before, the base presets took Clang_ROOT from $env{LLVM_ROOT} andthe generated preset overrode only LLVM_ROOT, so a stale LLVM_ROOT inthe shell sent find_package(Clang) to another install (Homebrew), whichfails with "imported targets are referenced, but are missing: LLVM".setup-llvm.cmake now validates Clang_ROOT (the old branch set LLVM_ROOTto itself), rejects a Clang_ROOT that differs from LLVM_ROOT, checks forlib/cmake/clang, and fails with a clear message when the found Clangand LLVM come from different prefixes.Root aliases are not part of the recipe stamp, so no dependency isrebuilt. β©
-
The handler wrote six custom properties to :root on everyscroll event, forcing a full style recalc. Nothing reads them. β©
-
Scripts and native plugins now go through the same per-run pipeline:- one
extensions/layout for scripts and plugins, and an extension is named by its file stem- the registries of transforms and generators belong to the context of the run- a script'sctxis the described C++ context, built next to its caller, with one builder per context type- a generator receives its options block the way a transform does- the extension contexts and callable wrappers live in headers of their own. β© -
The global report functions become a
report::Reporterthat the session owns. The corpus, the extensions and the generators receive it by reference instead of reaching for global state, so two sessions in one process no longer share a log level or an error count.Breaking for library users:session.log()returnsreport::Reporter&,Corpus::buildtakes the reporter by reference, and scripts report throughctx.reportinstead of the globalmrdocs.report. β© -
- a codebase layout page with the allowed top-level entries and a check, and one page per top-level directory instead of READMEs- the invariants in subpages, each naming the guard that checks it, with a page-length guard- a development setup page, a coding standards page and a contributor overview- copyable snippets come from built examples and tests, and links target explicit section anchors- extension names in the pipeline, template and integration pages, and the breaking-changes example shows sessions.
-
- plugin support and the plugin tests are separate CMake options-
justhas a recipe for every test suite- the IDE run configs take program paths from CMake's file API, and refreshing them keeps the saved bootstrap arguments- each CMake helper is a file of its own, and a runtime DLL already next to its consumer is not linked again- thefind_tooltests ignore the tool variables of the environment.
- plugin support and the plugin tests are separate CMake options-
-
- one directory per example with every variant and its tests, and the compiled plugin examples under
examples/extensions- a load-and-run example for the library page- the plugin and CMake package suites undertests/integration, the plugin cases grouped into exports, refused, dependencies and reload, and the consumer test split into executable, plugin and library parts- golden migration fixtures named after the migration they show- library unit tests mirror their headers, and the tests share their setup instead of copying it.
- one directory per example with every variant and its tests, and the compiled plugin examples under
-
- the Linux release builds in ubuntu:20.04 for a glibc 2.31 floor and bundles the C++ runtime- the macOS release and its LLVM target macOS 14, and the release check fails when the deployment target is not set- shared rows for every compiler family- checkouts at depth 1, and push builds fetch the nearest calendar tag through a composite action- the pull request template is gone, with the danger check that read it.
-
The guards that keep the rules of this branch from breaking later, and the sweeps that make the tree pass them:- lint, format and the release checks each live in their own directory under
utils/, and every guard judges only what a branch changes- guards write SARIF, so CI and the review tools read the same findings- a layout check, a README length cap, section titles that name their concept, and unit tests that mirror the header they test-.clang-formatdescribes the code as written- public type and function names in PascalCase, function names at column 0 after the qualifier line, andPlatform.hppfirst in the headers that need it, checked by the self-doc run- copyright lines where this branch changed existing files. β©