From 0c5d263de5a7830848b293dbb5e9aac7fe0f098e Mon Sep 17 00:00:00 2001 From: Alan de Freitas Date: Thu, 17 Jul 2025 18:46:29 -0500 Subject: [PATCH 01/10] ci: remove extra git install step --- .github/workflows/ci.yml | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7bfabb4a9..2fc473ad1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -124,6 +124,10 @@ jobs: contents: write steps: + # We install git if we are using a container because + # containers don't always include git. + # We need git to ensure actions/checkout@v4 will use git and + # for the next steps that need to clone repositories - name: Install Git uses: alandefreitas/cpp-actions/package-install@v1.8.10 if: matrix.container != '' @@ -133,6 +137,7 @@ jobs: with: apt-get: git + # Set up the repository ownership to avoid issues with git commands - name: Configure Git Safe Directory if: matrix.container != '' run: git config --global --add safe.directory "$(pwd)" @@ -140,15 +145,6 @@ jobs: - name: Clone MrDocs uses: actions/checkout@v4 - - name: Install Git - uses: alandefreitas/cpp-actions/package-install@v1.8.10 - if: matrix.container != '' - env: - DEBIAN_FRONTEND: 'noninteractive' - TZ: 'Etc/UTC' - with: - apt-get: git - - name: Setup CMake uses: alandefreitas/cpp-actions/setup-cmake@v1.8.7 id: setup-cmake From bd9c66d63b38c7484310def57001130c441c43fd Mon Sep 17 00:00:00 2001 From: Alan de Freitas Date: Thu, 17 Jul 2025 18:47:55 -0500 Subject: [PATCH 02/10] build: bootstrap uses another path for mrdocs source when not already called from source directory --- bootstrap.py | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/bootstrap.py b/bootstrap.py index 161598082..85b8f83cc 100644 --- a/bootstrap.py +++ b/bootstrap.py @@ -21,6 +21,34 @@ import json import re +def get_default_mrdocs_src_dir(): + """ + Returns the default source directory for MrDocs based on the current working directory. + + If the current working directory is the same as the script directory, it + means we're working on development. The script is being called from a location + that's already a MrDocs repository. So the user wants the current directory + to be used as the source directory, not to create a new source directory + every time the script is run. + + If the current working directory is different from the script directory, + it means we're running the script from a different location, likely a + pre-existing MrDocs repository. In this case, we assume the user wants to + create a new source directory for MrDocs in the current working directory + under the name "mrdocs" or anywhere else in order to avoid conflicts + and we assume the user is running this whole procedure to bootstrap, + build, and install MrDocs from scratch. + + :return: str: The default source directory for MrDocs. + """ + script_dir = os.path.dirname(os.path.abspath(__file__)) + cwd = os.getcwd() + if cwd == script_dir: + return cwd + else: + return os.path.join(cwd, "mrdocs") + + @dataclass class InstallOptions: """ @@ -39,7 +67,7 @@ class InstallOptions: cmake_path: str = '' # MrDocs - mrdocs_src_dir: str = field(default_factory=lambda: os.getcwd()) + mrdocs_src_dir: str = field(default_factory=get_default_mrdocs_src_dir) mrdocs_build_type: str = "Release" mrdocs_repo: str = "https://github.com/cppalliance/mrdocs" mrdocs_branch: str = "develop" From 90549f02a37e3ce8e4ad67ebc65e2b3115ad6573 Mon Sep 17 00:00:00 2001 From: Alan de Freitas Date: Thu, 17 Jul 2025 18:48:16 -0500 Subject: [PATCH 03/10] build: bootstrap build options list valid types --- bootstrap.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/bootstrap.py b/bootstrap.py index 85b8f83cc..d26009dd2 100644 --- a/bootstrap.py +++ b/bootstrap.py @@ -124,7 +124,7 @@ class InstallOptions: "mrdocs_src_dir": "MrDocs source directory.", "mrdocs_repo": "URL of the MrDocs repository to clone.", "mrdocs_branch": "Branch or tag of the MrDocs repository to use.", - "mrdocs_build_type": "CMake build type for MrDocs (e.g., Release, Debug).", + "mrdocs_build_type": "CMake build type for MrDocs (Release, Debug, RelWithDebInfo, MilRelSize, DebWithOpt).", "mrdocs_use_user_presets": "Whether to use CMake User Presets for building MrDocs.", "mrdocs_preset_name": "Name of the CMake User Preset to use for MrDocs.", "mrdocs_build_dir": "Directory where MrDocs will be built.", @@ -134,24 +134,24 @@ class InstallOptions: "mrdocs_run_tests": "Whether to run tests after building MrDocs.", "third_party_src_dir": "Directory for all third-party source dependencies.", "fmt_src_dir": "Directory for the fmt library source code.", - "fmt_build_type": "CMake build type for the fmt library.", + "fmt_build_type": "CMake build type for the fmt library. (Release, Debug, RelWithDebInfo, MilRelSize, DebWithOpt)", "fmt_build_dir": "Directory where the fmt library will be built.", "fmt_install_dir": "Directory where the fmt library will be installed.", "fmt_repo": "URL of the fmt library repository to clone.", "fmt_branch": "Branch or tag of the fmt library to use.", "duktape_src_dir": "Directory for the Duktape source code.", "duktape_url": "Download URL for the Duktape source archive.", - "duktape_build_type": "CMake build type for Duktape.", + "duktape_build_type": "CMake build type for Duktape. (Release, Debug, RelWithDebInfo, MilRelSize, DebWithOpt)", "duktape_build_dir": "Directory where Duktape will be built.", "duktape_install_dir": "Directory where Duktape will be installed.", "libxml2_src_dir": "Directory for the libxml2 source code.", - "libxml2_build_type": "CMake build type for libxml2.", + "libxml2_build_type": "CMake build type for libxml2. (Release, Debug, RelWithDebInfo, MilRelSize, DebWithOpt)", "libxml2_build_dir": "Directory where libxml2 will be built.", "libxml2_install_dir": "Directory where libxml2 will be installed.", "libxml2_repo": "URL of the libxml2 repository to clone.", "libxml2_branch": "Branch or tag of libxml2 to use.", "llvm_src_dir": "Directory for the LLVM project source code.", - "llvm_build_type": "CMake build type for LLVM.", + "llvm_build_type": "CMake build type for LLVM. (Release, Debug, RelWithDebInfo, MilRelSize, DebWithOpt)", "llvm_build_dir": "Directory where LLVM will be built.", "llvm_install_dir": "Directory where LLVM will be installed.", "llvm_repo": "URL of the LLVM project repository to clone.", From f7e418d3fe64ec8a8e391ca564539c0f7f982025 Mon Sep 17 00:00:00 2001 From: Alan de Freitas Date: Thu, 17 Jul 2025 18:48:53 -0500 Subject: [PATCH 04/10] build: bootstrap prompts use colors --- bootstrap.py | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/bootstrap.py b/bootstrap.py index d26009dd2..7cee7669d 100644 --- a/bootstrap.py +++ b/bootstrap.py @@ -189,6 +189,14 @@ def prompt_string(self, prompt, default): : param default: The default value to use if the user does not provide input. :return: """ + prompt = prompt.strip() + if prompt.endswith('.'): + prompt = prompt[:-1] + prompt = prompt.strip() + BLUE = "\033[94m" + RESET = "\033[0m" + if self.supports_ansi(): + prompt = f"{BLUE}{prompt}{RESET}" inp = input(f"{prompt} ({default}): ") result = inp.strip() or default return result @@ -201,6 +209,14 @@ def prompt_boolean(self, prompt, default = None): :param default: The default value to return if the user does not provide input. :return: bool: True if the user answers yes, False otherwise. """ + prompt = prompt.strip() + if prompt.endswith('.'): + prompt = prompt[:-1] + prompt = prompt.strip() + BLUE = "\033[94m" + RESET = "\033[0m" + if self.supports_ansi(): + prompt = f"{BLUE}{prompt}{RESET}" while True: answer = input(f"{prompt} ({'y/n' if default is None else 'yes' if default else 'no'}): ").strip().lower() if answer in ('y', 'yes'): @@ -338,17 +354,10 @@ def run_cmd(self, cmd, cwd=None): """ BLUE = "\033[94m" RESET = "\033[0m" - def supports_ansi(): - if os.name == "posix": - return True - if os.name == "nt": - return "WT_SESSION" in os.environ or sys.stdout.isatty() - return False - if cwd is None: cwd = os.getcwd() - color = BLUE if supports_ansi() else "" - reset = RESET if supports_ansi() else "" + color = BLUE if self.supports_ansi() else "" + reset = RESET if self.supports_ansi() else "" if isinstance(cmd, list): print(f"{color}{cwd}> {' '.join(cmd)}{reset}") else: From bc43261ae9a05964839591bdced8296ef7b9d2ea Mon Sep 17 00:00:00 2001 From: Alan de Freitas Date: Thu, 17 Jul 2025 18:49:23 -0500 Subject: [PATCH 05/10] build: bootstrap removes redundant flags --- bootstrap.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/bootstrap.py b/bootstrap.py index 7cee7669d..2e17610b8 100644 --- a/bootstrap.py +++ b/bootstrap.py @@ -441,10 +441,8 @@ def cmake_workflow(self, src_dir, build_type, build_dir, install_dir, extra_args if build_type_is_debwithopt: if self.is_windows(): config_args.extend(["-DCMAKE_CXX_FLAGS=/DWIN32 /D_WINDOWS /Ob1 /O2 /Zi", "-DCMAKE_C_FLAGS=/DWIN32 /D_WINDOWS /Ob1 /O2 /Zi"]) - config_args.extend(["-DCMAKE_CXX_FLAGS=/Ob1 /O2 /Zi", "-DCMAKE_C_FLAGS=/Ob1 /O2 /Zi"]) else: config_args.extend(["-DCMAKE_CXX_FLAGS=-Og -g", "-DCMAKE_C_FLAGS=-Og -g"]) - config_args.extend(["-DCMAKE_CXX_FLAGS_DEBUG=-Og -g", "-DCMAKE_C_FLAGS_DEBUG=-Og -g"]) if isinstance(extra_args, str): config_args.extend(extra_args.split()) elif isinstance(extra_args, list): From 80917bfa095dab59cb3c6cb1f71f644b2aaf9e4e Mon Sep 17 00:00:00 2001 From: Alan de Freitas Date: Thu, 17 Jul 2025 18:49:30 -0500 Subject: [PATCH 06/10] build: bootstrap runs tests in parallel --- bootstrap.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bootstrap.py b/bootstrap.py index 2e17610b8..37814ede5 100644 --- a/bootstrap.py +++ b/bootstrap.py @@ -798,8 +798,8 @@ def install_mrdocs(self): ctest_path = os.path.join(os.path.dirname(self.options.cmake_path), "ctest") if not os.path.exists(ctest_path): raise FileNotFoundError(f"ctest executable not found at {ctest_path}. Please ensure CMake is installed correctly.") - # --parallel 4 --no-tests=error --progress --output-on-failure - test_args = [ctest_path, "--test-dir", self.options.mrdocs_build_dir, "--output-on-failure", "--progress", "--no-tests=error", "--output-on-failure"] + test_args = [ctest_path, "--test-dir", self.options.mrdocs_build_dir, "--output-on-failure", "--progress", + "--no-tests=error", "--output-on-failure", "--parallel", str(os.cpu_count() or 1)] self.run_cmd(test_args) print(f"\nMrDocs has been successfully installed in {self.options.mrdocs_install_dir}.\n") From f1cccdbc7cea143c70cfd26bd0841936f48825c4 Mon Sep 17 00:00:00 2001 From: Alan de Freitas Date: Thu, 17 Jul 2025 18:52:04 -0500 Subject: [PATCH 07/10] ci: libxml2 build mode is static --- .github/workflows/ci.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2fc473ad1..c05cd7754 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -320,6 +320,7 @@ jobs: ccflags: ${{ matrix.ccflags }} cxxflags: ${{ matrix.cxxflags }} build-type: Release + shared: false extra-args: | -D LIBXML2_WITH_PROGRAMS=ON -D LIBXML2_WITH_FTP=OFF From 55b951a4c5279eb9b457474bc1344a81ce002481 Mon Sep 17 00:00:00 2001 From: Alan de Freitas Date: Thu, 17 Jul 2025 19:20:41 -0500 Subject: [PATCH 08/10] docs: one-liner installation instructions --- bootstrap.py | 45 +++++++----------- docs/modules/ROOT/pages/install.adoc | 70 ++++++++++++++++++++++++++-- 2 files changed, 83 insertions(+), 32 deletions(-) diff --git a/bootstrap.py b/bootstrap.py index 37814ede5..6dcb4401e 100644 --- a/bootstrap.py +++ b/bootstrap.py @@ -20,34 +20,17 @@ import tarfile import json import re +from functools import lru_cache -def get_default_mrdocs_src_dir(): +@lru_cache(maxsize=1) +def running_from_mrdocs_source_dir(): """ - Returns the default source directory for MrDocs based on the current working directory. - - If the current working directory is the same as the script directory, it - means we're working on development. The script is being called from a location - that's already a MrDocs repository. So the user wants the current directory - to be used as the source directory, not to create a new source directory - every time the script is run. - - If the current working directory is different from the script directory, - it means we're running the script from a different location, likely a - pre-existing MrDocs repository. In this case, we assume the user wants to - create a new source directory for MrDocs in the current working directory - under the name "mrdocs" or anywhere else in order to avoid conflicts - and we assume the user is running this whole procedure to bootstrap, - build, and install MrDocs from scratch. - - :return: str: The default source directory for MrDocs. + Checks if the current working directory is the same as the script directory. + :return: """ script_dir = os.path.dirname(os.path.abspath(__file__)) cwd = os.getcwd() - if cwd == script_dir: - return cwd - else: - return os.path.join(cwd, "mrdocs") - + return cwd == script_dir @dataclass class InstallOptions: @@ -67,7 +50,7 @@ class InstallOptions: cmake_path: str = '' # MrDocs - mrdocs_src_dir: str = field(default_factory=get_default_mrdocs_src_dir) + mrdocs_src_dir: str = field(default_factory=lambda: os.getcwd() if running_from_mrdocs_source_dir() else os.path.join(os.getcwd(), "mrdocs")) mrdocs_build_type: str = "Release" mrdocs_repo: str = "https://github.com/cppalliance/mrdocs" mrdocs_branch: str = "develop" @@ -75,8 +58,8 @@ class InstallOptions: mrdocs_preset_name: str = "-" mrdocs_build_dir: str = "/build/-" mrdocs_build_tests: bool = True - mrdocs_install_dir: str = "/install/-" - mrdocs_system_install: bool = False + mrdocs_system_install: bool = field(default_factory=lambda: not running_from_mrdocs_source_dir()) + mrdocs_install_dir: str = field(default_factory=lambda: "/install/-" if running_from_mrdocs_source_dir() else "") mrdocs_run_tests: bool = True # Third-party dependencies @@ -771,8 +754,9 @@ def install_mrdocs(self): self.prompt_option("mrdocs_install_dir") extra_args = [] - if self.options.mrdocs_system_install and self.options.mrdocs_install_dir: + if not self.options.mrdocs_system_install and self.options.mrdocs_install_dir: extra_args.extend(["-D", f"CMAKE_INSTALL_PREFIX={self.options.mrdocs_install_dir}"]) + if self.options.mrdocs_use_user_presets: extra_args.append(f"--preset={self.options.mrdocs_preset_name}") else: @@ -802,7 +786,12 @@ def install_mrdocs(self): "--no-tests=error", "--output-on-failure", "--parallel", str(os.cpu_count() or 1)] self.run_cmd(test_args) - print(f"\nMrDocs has been successfully installed in {self.options.mrdocs_install_dir}.\n") + YELLOW = "\033[93m" + RESET = "\033[0m" + if self.supports_ansi(): + print(f"{YELLOW}MrDocs has been successfully installed in {self.options.mrdocs_install_dir}.{RESET}") + else: + print(f"\nMrDocs has been successfully installed in {self.options.mrdocs_install_dir}.\n") def install_all(self): self.check_tools() diff --git a/docs/modules/ROOT/pages/install.adoc b/docs/modules/ROOT/pages/install.adoc index 10533e794..eec93e787 100644 --- a/docs/modules/ROOT/pages/install.adoc +++ b/docs/modules/ROOT/pages/install.adoc @@ -11,16 +11,48 @@ mrdocs-releases::[] [#mrdocs-source-script] == Python Bootstrap Script -The Python bootstrap script available in the repository provides an alternative way to install MrDocs and its dependencies -from source. Just run the script from the root of the MrDocs repository: +The Python bootstrap script available in the repository provides an alternative way to install MrDocs and its +dependencies from source. Just run the script from the root of the MrDocs repository: [source,bash] ---- git clone https://www.github.com/cppalliance/mrdocs.git cd mrdocs -python3 bootstrap.py +python bootstrap.py ---- +Or if you just want to install MrDocs without cloning the repository, you can run the script directly from the web: + +[tabs] +==== +Windows:: ++ +-- +[source,powershell] +---- +python -c "$(Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/cppalliance/mrdocs/refs/heads/develop/bootstrap.py' -UseBasicParsing | Select-Object -ExpandProperty Content)" +---- +-- + +Linux:: ++ +-- +[source,bash] +---- +python3 -c "$(curl -fsSL https://raw.githubusercontent.com/cppalliance/mrdocs/refs/heads/develop/bootstrap.py)" +---- +-- + +macOS:: ++ +-- +[source,bash] +---- +python -c "$(curl -fsSL https://raw.githubusercontent.com/cppalliance/mrdocs/refs/heads/develop/bootstrap.py)" +---- +-- +==== + This method automates the download, configuration, and build steps for MrDocs and all required third-party libraries. It is especially useful for developers and for users who prefer a streamlined, interactive setup or need to install MrDocs in custom environments. @@ -30,7 +62,37 @@ Every option can be defined in the command line directly instead of being prompt All options can be listed with the `--help` option. The `--non-interactive` option allows you to run the script without any prompts, using -values specified in the command line and default values for other options. +values specified in the command line and default values for other options. In the default case, the script will download the source code to the current directory and install MrDocs system-wide. + +[tabs] +==== +Windows PowerShell:: ++ +-- +[source,powershell] +---- +python -c "$(Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/cppalliance/mrdocs/refs/heads/develop/bootstrap.py' -UseBasicParsing)" --non-interactive +---- +-- + +Linux:: ++ +-- +[source,bash] +---- +python3 -c "$(curl -fsSL https://raw.githubusercontent.com/cppalliance/mrdocs/refs/heads/develop/bootstrap.py)" --non-interactive +---- +-- + +macOS:: ++ +-- +[source,bash] +---- +python -c "$(curl -fsSL https://raw.githubusercontent.com/cppalliance/mrdocs/refs/heads/develop/bootstrap.py)" --non-interactive +---- +-- +==== The script handles tool checks, repository cloning, patching, and CMake configuration, reducing manual intervention and potential errors. From 3538b9b82edad56f601507b2fdba1695417c97ba Mon Sep 17 00:00:00 2001 From: Alan de Freitas Date: Thu, 17 Jul 2025 19:53:43 -0500 Subject: [PATCH 09/10] docs: set up @asciidoctor/tabs in UI bundle --- docs/modules/ROOT/pages/install.adoc | 32 +++++++------------------ docs/package-lock.json | 16 ++++--------- docs/ui/package-lock.json | 11 +++++++++ docs/ui/package.json | 5 ++-- docs/ui/preview-src/ui-model.yml | 3 +++ docs/ui/src/css/vendor/tabs.css | 1 + docs/ui/src/js/vendor/tabs.bundle.js | 1 + docs/ui/src/partials/footer-scripts.hbs | 1 + docs/ui/src/partials/head-styles.hbs | 1 + 9 files changed, 33 insertions(+), 38 deletions(-) create mode 100644 docs/ui/src/css/vendor/tabs.css create mode 100644 docs/ui/src/js/vendor/tabs.bundle.js diff --git a/docs/modules/ROOT/pages/install.adoc b/docs/modules/ROOT/pages/install.adoc index eec93e787..53fdb5e20 100644 --- a/docs/modules/ROOT/pages/install.adoc +++ b/docs/modules/ROOT/pages/install.adoc @@ -1,4 +1,5 @@ = Install +:tabs-sync-option: [#mrdocs-binaries] == Binary Packages @@ -8,10 +9,10 @@ Most users should use these packages. mrdocs-releases::[] -[#mrdocs-source-script] -== Python Bootstrap Script +[#mrdocs-bootstrap-script] +== Bootstrap Script -The Python bootstrap script available in the repository provides an alternative way to install MrDocs and its +The bootstrap script available in the repository provides an alternative way to install MrDocs and its dependencies from source. Just run the script from the root of the MrDocs repository: [source,bash] @@ -34,16 +35,7 @@ python -c "$(Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/cppallian ---- -- -Linux:: -+ --- -[source,bash] ----- -python3 -c "$(curl -fsSL https://raw.githubusercontent.com/cppalliance/mrdocs/refs/heads/develop/bootstrap.py)" ----- --- - -macOS:: +Unix Variants:: + -- [source,bash] @@ -53,6 +45,7 @@ python -c "$(curl -fsSL https://raw.githubusercontent.com/cppalliance/mrdocs/ref -- ==== + This method automates the download, configuration, and build steps for MrDocs and all required third-party libraries. It is especially useful for developers and for users who prefer a streamlined, interactive setup or need to install MrDocs in custom environments. @@ -75,16 +68,7 @@ python -c "$(Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/cppallian ---- -- -Linux:: -+ --- -[source,bash] ----- -python3 -c "$(curl -fsSL https://raw.githubusercontent.com/cppalliance/mrdocs/refs/heads/develop/bootstrap.py)" --non-interactive ----- --- - -macOS:: +Unix Variants:: + -- [source,bash] @@ -100,7 +84,7 @@ This approach is recommended for developers, advanced users, or those integratin into larger projects. [#mrdocs-source] -== Install from Source +== Manually Install from Source The following instructions assume we are at a parent directory that's going to contain both the MrDocs and the third-party dependencies directories. diff --git a/docs/package-lock.json b/docs/package-lock.json index 545da00fd..f8f5e7de8 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -9,7 +9,6 @@ "@antora/lunr-extension": "^1.0.0-alpha.8", "@asciidoctor/tabs": "^1.0.0-beta.3", "asciidoctor": "^2.2.6", - "c-preprocessor": "^0.2.13", "sync-request": "^6.1.0" }, "devDependencies": { @@ -336,9 +335,10 @@ } }, "node_modules/@asciidoctor/tabs": { - "version": "1.0.0-beta.3", - "resolved": "https://registry.npmjs.org/@asciidoctor/tabs/-/tabs-1.0.0-beta.3.tgz", - "integrity": "sha512-Cx6LQCLl703BwuejZZSwBy1s7CuJxD9AVY2mAgE0UDXfPmFsY3Il3JMGQ+1JAwHH0hd7htLEq+yG5EiiLdCJeg==", + "version": "1.0.0-beta.6", + "resolved": "https://registry.npmjs.org/@asciidoctor/tabs/-/tabs-1.0.0-beta.6.tgz", + "integrity": "sha512-gGZnW7UfRXnbiyKNd9PpGKtSuD8+DsqaaTSbQ1dHVkZ76NaolLhdQg8RW6/xqN3pX1vWZEcF4e81+Oe9rNRWxg==", + "license": "MIT", "engines": { "node": ">=16.0.0" } @@ -589,14 +589,6 @@ "resolved": "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.2.tgz", "integrity": "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==" }, - "node_modules/c-preprocessor": { - "version": "0.2.13", - "resolved": "https://registry.npmjs.org/c-preprocessor/-/c-preprocessor-0.2.13.tgz", - "integrity": "sha512-mP7bQewcGO51mb8sPx6WPX7PqmcyRRrv4y59Ldg39Zj/mvtJIXLWiRVM2+cG1oRGLSKMz01StqpBC2sa7+I6RA==", - "bin": { - "c-preprocessor": "bin/global.js" - } - }, "node_modules/cache-directory": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/cache-directory/-/cache-directory-2.0.0.tgz", diff --git a/docs/ui/package-lock.json b/docs/ui/package-lock.json index 5bfe2833c..1090241c8 100644 --- a/docs/ui/package-lock.json +++ b/docs/ui/package-lock.json @@ -8,6 +8,7 @@ "license": "MPL-2.0", "devDependencies": { "@asciidoctor/core": "~2.2", + "@asciidoctor/tabs": "^1.0.0-beta.6", "@fontsource/roboto": "~4.5", "@fontsource/roboto-mono": "~4.5", "@vscode/gulp-vinyl-zip": "~2.5", @@ -80,6 +81,16 @@ "yarn": ">=1.1.0" } }, + "node_modules/@asciidoctor/tabs": { + "version": "1.0.0-beta.6", + "resolved": "https://registry.npmjs.org/@asciidoctor/tabs/-/tabs-1.0.0-beta.6.tgz", + "integrity": "sha512-gGZnW7UfRXnbiyKNd9PpGKtSuD8+DsqaaTSbQ1dHVkZ76NaolLhdQg8RW6/xqN3pX1vWZEcF4e81+Oe9rNRWxg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=16.0.0" + } + }, "node_modules/@babel/code-frame": { "version": "7.26.0", "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.26.0.tgz", diff --git a/docs/ui/package.json b/docs/ui/package.json index 1ec5817d7..d64c9dc72 100644 --- a/docs/ui/package.json +++ b/docs/ui/package.json @@ -15,6 +15,7 @@ ], "devDependencies": { "@asciidoctor/core": "~2.2", + "@asciidoctor/tabs": "^1.0.0-beta.6", "@fontsource/roboto": "~4.5", "@fontsource/roboto-mono": "~4.5", "@vscode/gulp-vinyl-zip": "~2.5", @@ -36,6 +37,7 @@ "gulp-eslint": "~6.0", "gulp-imagemin": "~6.2", "gulp-postcss": "~8.0", + "gulp-prettier": "^6.0.0", "gulp-stylelint": "~13.0", "gulp-uglify": "~3.0", "gulp-vinyl-zip": "~2.2", @@ -52,7 +54,6 @@ "require-from-string": "~2.0", "stylelint": "~13.3", "stylelint-config-standard": "~20.0", - "vinyl-fs": "~3.0", - "gulp-prettier": "^6.0.0" + "vinyl-fs": "~3.0" } } diff --git a/docs/ui/preview-src/ui-model.yml b/docs/ui/preview-src/ui-model.yml index 9fa2e1aff..4c05535eb 100644 --- a/docs/ui/preview-src/ui-model.yml +++ b/docs/ui/preview-src/ui-model.yml @@ -124,3 +124,6 @@ page: - content: Some Code url: '/xyz/5.2/index.html#some-code' urlType: internal +asciidoc: + extensions: + - '@asciidoctor/tabs' diff --git a/docs/ui/src/css/vendor/tabs.css b/docs/ui/src/css/vendor/tabs.css new file mode 100644 index 000000000..9440ddfc6 --- /dev/null +++ b/docs/ui/src/css/vendor/tabs.css @@ -0,0 +1 @@ +@import "@asciidoctor/tabs" diff --git a/docs/ui/src/js/vendor/tabs.bundle.js b/docs/ui/src/js/vendor/tabs.bundle.js new file mode 100644 index 000000000..8d1016f85 --- /dev/null +++ b/docs/ui/src/js/vendor/tabs.bundle.js @@ -0,0 +1 @@ +require('@asciidoctor/tabs') diff --git a/docs/ui/src/partials/footer-scripts.hbs b/docs/ui/src/partials/footer-scripts.hbs index 3d9b577af..f5ed34efe 100644 --- a/docs/ui/src/partials/footer-scripts.hbs +++ b/docs/ui/src/partials/footer-scripts.hbs @@ -3,3 +3,4 @@ {{#if env.SITE_SEARCH_PROVIDER}} {{> search-scripts}} {{/if}} + diff --git a/docs/ui/src/partials/head-styles.hbs b/docs/ui/src/partials/head-styles.hbs index d6839e546..7335a23eb 100644 --- a/docs/ui/src/partials/head-styles.hbs +++ b/docs/ui/src/partials/head-styles.hbs @@ -1 +1,2 @@ + From 150686308b1db51946f2981c09a3e4f41b8e6dc2 Mon Sep 17 00:00:00 2001 From: Alan de Freitas Date: Thu, 17 Jul 2025 20:15:35 -0500 Subject: [PATCH 10/10] docs: update manual installation instructions --- docs/modules/ROOT/pages/install.adoc | 243 +++------------------------ 1 file changed, 19 insertions(+), 224 deletions(-) diff --git a/docs/modules/ROOT/pages/install.adoc b/docs/modules/ROOT/pages/install.adoc index 53fdb5e20..1b662d0a4 100644 --- a/docs/modules/ROOT/pages/install.adoc +++ b/docs/modules/ROOT/pages/install.adoc @@ -26,7 +26,7 @@ Or if you just want to install MrDocs without cloning the repository, you can ru [tabs] ==== -Windows:: +Windows PowerShell:: + -- [source,powershell] @@ -143,56 +143,6 @@ All instructions in this document assume you are using a CMake version above 3.2 Binaries are available at https://cmake.org/download/[CMake's official website,window="_blank"]. ==== -If you prefer using Vcpkg to install dependencies, you can install VcPkg and `fmt` with the following commands from the `third-party` directory: - -:tabs-sync-option: - -[tabs] -==== -Windows PowerShell:: -+ --- -[source,bash] ----- -git clone https://github.com/microsoft/vcpkg.git -b master <.> -cd vcpkg -bootstrap-vcpkg.bat <.> -vcpkg.exe install fmt --triplet x64-windows <.> ----- - -<.> Clones the Vcpkg repository. -<.> Bootstraps Vcpkg. -<.> Installs the `fmt` library. --- - -Unix Variants:: -+ --- -[source,bash] ----- -git clone https://github.com/microsoft/vcpkg.git -b master <.> -cd vcpkg -./bootstrap-vcpkg.sh <.> -./vcpkg install fmt <.> ----- - -<.> Clones the Vcpkg repository. -<.> Bootstraps Vcpkg. -<.> Installs the `fmt` library. --- -==== - -[NOTE] -==== -You can also install `fmt` with Vcpkg in _Manifest mode_. -In https://learn.microsoft.com/en-us/vcpkg/users/manifests[manifest mode,windows=blank_], you declare your project's direct dependencies in a manifest file named `vcpkg.json`. -MrDocs includes a `vcpkg.json.example` file you can duplicate or create a symlink as `vcpkg.json` to use this mode. -This file includes all the dependencies MrDocs needs, except for LLVM. - -In this mode, VcPkg will create separate installed trees for each project and configuration. -This is the recommended vcpkg mode for most users, according to the https://learn.microsoft.com/en-us/vcpkg/users/manifests[vcpkg documentation,window=blank_]. -==== - === Duktape MrDocs uses the `duktape` library for JavaScript parsing. @@ -295,37 +245,6 @@ cmake --install ./build --prefix ./install <.> The scripts above download the `duktape` source code, extract it, and configure it with CMake. The CMake scripts provided by MrDocs are copied to the `duktape-2.7.0` directory to facilitate the build process with CMake and provide CMake installation scripts for other projects. -If you prefer using Vcpkg to install dependencies, you can install `duktape` with the following commands from the `third-party` directory: - -[tabs] -==== -Windows PowerShell:: -+ --- -[source,bash] ----- -cd vcpkg -vcpkg.exe install duktape --triplet x64-windows <.> ----- - -<.> Installs the `duktape` library. --- - -Unix Variants:: -+ --- -[source,bash] ----- -cd vcpkg -./vcpkg install duktape <.> ----- - -<.> Installs the `duktape` library. --- -==== - -NOTE: These examples assume VcPkg is already installed in the `third-party/vcpkg` directory (see the <> section). - === Libxml2 MrDocs uses `libxml2` tools for tests. @@ -349,37 +268,6 @@ cd .. <.> Builds libxml2 in the `build` directory. <.> Installs libxml2 in the `install` directory. -If you prefer using Vcpkg to install dependencies, you can install `libxml2` with the following commands from the `third-party` directory: - -[tabs] -==== -Windows PowerShell:: -+ --- -[source,bash] ----- -cd vcpkg -vcpkg.exe install libxml2[tools] --triplet x64-windows <.> ----- - -<.> Installs `libxml2`. --- - -Unix Variants:: -+ --- -[source,bash] ----- -cd vcpkg -./vcpkg install libxml2[tools] <.> ----- - -<.> Installs `libxml2`. --- -==== - -NOTE: These examples assume VcPkg is already installed in the `third-party/vcpkg` directory (see the <> section). - === LLVM MrDocs uses LLVM to parse C++ code and extract documentation from it. @@ -428,7 +316,7 @@ Windows PowerShell:: [source,bash] ---- cd llvm -cmake -S . -B ./build --preset=release-win +cmake -S . -B ./build --preset=release-win -DLLVM_ENABLE_RUNTIMES=libcxx ---- -- @@ -438,7 +326,7 @@ Unix Variants:: [source,bash] ---- cd llvm -cmake -S . -B ./build --preset=release-unix +cmake -S . -B ./build --preset=release-unix -DLLVM_ENABLE_RUNTIMES=libcxx;libcxxabi;libunwind ---- -- ==== @@ -475,68 +363,26 @@ Return from `./third-party/llvm-project/llvm` to the LLVM project directory: cd ../.. ---- -=== LibC++ - -In addition to LLVM, MrDocs requires a deterministic version of the C++ standard library (LibC++) to ensure consistent behavior across various environments. -This step is crucial for replicating specific compiler and library configurations. - -**Download**: - -Continue using the same LLVM project directory. - -**Configure**: +=== MrDocs -Configure and build LibC++ using the existing structure: +Return to the parent directory of `third-party` (the one containing the `mrdocs` directory) to build and install MrDocs: [source,bash] ---- -export CXX="./install/bin/clang++" -export CC="./install/bin/clang" +cd ../.. ---- -These options set the C and pass:[C++] compilers to the ones previously installed by LLVM. -MrDocs only depends on the pass:[LibC++] headers, so any compiler that works for this step should be fine. - -Run a command such as the following to configure LLVM: +**Configure**: -[tabs] -==== -Windows PowerShell:: -+ --- -[source,bash] ----- -cmake -G Ninja \ - -S runtimes \ - -B build-libcxx \ - -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" \ - -DCMAKE_INSTALL_PREFIX="$(pwd)/install" \ - -DLIBCXXABI_USE_LLVM_UNWINDER=OFF \ - -DLIBCXXABI_ENABLE_SHARED=OFF \ - -DLIBCXXABI_ENABLE_STATIC=ON \ - -DLIBCXX_ENABLE_SHARED=OFF \ - -DLIBCXX_NO_VCRUNTIME=ON \ - -DCMAKE_CXX_FLAGS="-D__ORDER_LITTLE_ENDIAN__=1234 -D__ORDER_BIG_ENDIAN__=4321 -D__BYTE_ORDER__=__ORDER_LITTLE_ENDIAN__" ----- --- +The MrDocs repository also includes a `CMakePresets.json` file that contains the parameters to configure MrDocs with CMake. -Unix Variants:: -+ --- -[source,bash] ----- -cmake -G Ninja \ - -S runtimes \ - -B build-libcxx \ - -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" \ - -DCMAKE_INSTALL_PREFIX="$(pwd)/install" ----- --- -==== +To specify the installation directories, you can use the `LLVM_ROOT`, `DUKTAPE_ROOT`, `FMT_ROOT`, and `LIBXML2_ROOT` environment variables. +To specify a generator (`-G`) and platform name (`-A`), you can use the `CMAKE_GENERATOR` and `CMAKE_GENERATOR_PLATFORM` environment variables. -**Build**: +You can also customize the presets by duplicating and editing the `CMakeUserPresets.json.example` file in the `mrdocs` directory. +This is typically more convenient than using environment variables. -Build and install the configured version of LibC++ with: +For instance, to build MrDocs with the default `Release` preset, you can run the following command: [tabs] ==== @@ -545,8 +391,8 @@ Windows PowerShell:: -- [source,bash] ---- -ninja -C build-libcxx cxx -ninja -C build-libcxx install-cxx +cd mrdocs +cmake -S . --preset=release-win ---- -- @@ -555,69 +401,19 @@ Unix Variants:: -- [source,bash] ---- -ninja -C build-libcxx cxx cxxabi unwind -ninja -C build-libcxx install-cxx install-cxxabi install-unwind +cd mrdocs +cmake -S . --preset=release-unix ---- -- ==== -Return from `./third-party/llvm-project` to the parent directory to build and install MrDocs: +To list the available presets, you can run: [source,bash] ---- -cd ../.. +cmake --list-presets ---- -=== MrDocs - -Return from `./third-party/vcpkg` to the parent directory of `third-party` (the one containing the `mrdocs` directory) to build and install MrDocs: - -[source,bash] ----- -cd ../.. ----- - -**Configure**: - -You can also configure MrDocs with <> or <>. - -[#mrdocs-configure-cmd-line] -_Configure with Command Line Arguments_: - -With the dependencies are available in `third-party`, you can configure MrDocs with: - -[tabs] -==== -Windows PowerShell:: -+ --- -[source,commandline] ----- -cmake -S mrdocs -B build -G "Visual Studio 17 2022" -A x64 -D CMAKE_CONFIGURATION_TYPES="RelWithDebInfo" -D CMAKE_EXPORT_COMPILE_COMMANDS=ON -D LLVM_ROOT="%cd%/third-party/llvm+clang/RelWithDebInfo" -D DUKTAPE_SOURCE_ROOT="%cd%/third-party/duktape-2.7.0" -D CMAKE_TOOLCHAIN_FILE="%cd%/third-party/vcpkg/scripts/buildsystems/vcpkg.cmake" ----- --- - -Unix Variants:: -+ --- -[source,bash] ----- -cmake -S mrdocs -B build -D CMAKE_BUILD_TYPE=RelWithDebInfo -D CMAKE_EXPORT_COMPILE_COMMANDS=ON -D LLVM_ROOT="$(pwd)/third-party/llvm+clang/RelWithDebInfo" -D DUKTAPE_SOURCE_ROOT="$(pwd)/third-party/duktape-2.7.0" -D CMAKE_TOOLCHAIN_FILE="$(pwd)/third-party/vcpkg/scripts/buildsystems/vcpkg.cmake" ----- --- -==== - -[#mrdocs-configure-presets] -_Configure with CMake Presets_: - -The MrDocs repository also includes a `CMakePresets.json` file that contains the parameters to configure MrDocs with CMake. - -To specify the installation directories, you can use the `LLVM_ROOT`, `DUKTAPE_SOURCE_ROOT`, `CMAKE_TOOLCHAIN_FILE` environment variables. -To specify a generator (`-G`) and platform name (`-A`), you can use the `CMAKE_GENERATOR` and `CMAKE_GENERATOR_PLATFORM` environment variables. - -You can also customize the presets by duplicating and editing the `CMakeUserPresets.json.example` file in the `mrdocs` directory. -This is typically more convenient than using environment variables. - **Build**: Then build and install MrDocs with: @@ -635,7 +431,6 @@ To customize the C and C++ compilers, use the `CMAKE_C_COMPILER` and `CMAKE_CXX_ [NOTE] ==== Developers should also enable `-D BUILD_TESTING=ON`. -If any custom build of LLVM other than `RelWithDebInfo` is being used, the `LLVM_ROOT` variable should be set to the installation directory of that build. ==== == Package layout