feat: javascript helpers extension

fix #881

Author: alandefreitas

.github/workflows/ci.yml

@@ -428,14 +428,14 @@ jobs:
         run: |
           rm -r ../third-party/llvm-project
 
-      - name: Install Duktape
+      - name: Install JerryScript
         uses: alandefreitas/cpp-actions/[email protected]
         with:
-          source-dir: ../third-party/duktape
-          url: https://github.com/svaarala/duktape/releases/download/v2.7.0/duktape-2.7.0.tar.xz
+          source-dir: ../third-party/jerryscript
+          url: https://github.com/jerryscript-project/jerryscript/archive/refs/tags/v3.0.0.tar.gz
           patches: |
-            ./third-party/patches/duktape/CMakeLists.txt
-            ./third-party/patches/duktape/duktapeConfig.cmake.in
+            ./third-party/patches/jerryscript/CMakeLists.txt
+            ./third-party/patches/jerryscript/jerryscriptConfig.cmake.in
           build-dir: ${sourceDir}/build
           cc: ${{ steps.setup-cpp.outputs.cc }}
           cxx: ${{ steps.setup-cpp.outputs.cxx }}
@@ -547,7 +547,7 @@ jobs:
             -D MRDOCS_BUILD_DOCS=OFF
             -D CMAKE_EXE_LINKER_FLAGS="${{ steps.rmatrix.outputs.common-ldflags }}"
             -D LLVM_ROOT="${{ steps.rmatrix.outputs.llvm-path }}"
-            -D duktape_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/duktape/install"
+            -D jerryscript_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/jerryscript/install"
             -D LUA_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/lua/install"
             -D Lua_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/lua/install"
             -D lua_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/lua/install"

.gitignore

@@ -28,4 +28,5 @@
 /.roadmap
 /AGENTS.md
 # Ignore hidden OS files under golden fixtures
-test-files/golden-tests/**/.*
+/test-files/golden-tests/**/.*
+/.code

CMakeLists.txt

@@ -277,13 +277,8 @@ llvm_map_components_to_libnames(llvm_libs all)
 string(REGEX REPLACE " /W[0-4]" "" CMAKE_C_FLAGS "${CMAKE_C_FLAGS}")
 string(REGEX REPLACE " /W[0-4]" "" CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS}")
 
-# Duktape
-find_package(duktape CONFIG)
-if (NOT DUKTAPE_FOUND)
-    # Duktape doesn't natively support CMake.
-    # Some config script patches use the capitalized version.
-    find_package(Duktape REQUIRED CONFIG)
-endif()
+# JerryScript
+find_package(jerryscript REQUIRED CONFIG)
 
 # Lua
 find_package(Lua CONFIG REQUIRED)
@@ -344,10 +339,11 @@ target_include_directories(mrdocs-core
 )
 target_include_directories(mrdocs-core
         SYSTEM PRIVATE
-        "$<BUILD_INTERFACE:${DUKTAPE_INCLUDE_DIRS}>"
-        "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>"
+        "$<BUILD_INTERFACE:${JERRYSCRIPT_INCLUDE_DIRS}>"
+        "$<BUILD_INTERFACE:${jerryscript_ROOT}/include>"
+        "$<BUILD_INTERFACE:/usr/local/include>"
 )
-target_link_libraries(mrdocs-core PRIVATE ${DUKTAPE_LIBRARY})
+target_link_libraries(mrdocs-core PRIVATE ${JERRYSCRIPT_LIBRARY})
 target_link_libraries(mrdocs-core PRIVATE Lua::lua)
 
 # Clang
@@ -425,8 +421,6 @@ list(APPEND TOOL_SOURCES
         ${CMAKE_CURRENT_BINARY_DIR}/src/tool/PublicToolArgs.cpp)
 
 add_executable(mrdocs ${TOOL_SOURCES})
-target_compile_definitions(mrdocs PRIVATE -DMRDOCS_TOOL)
-
 target_include_directories(mrdocs
     PUBLIC
     "$<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include/>"

CMakePresets.json

@@ -17,8 +17,7 @@
         "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
         "LLVM_ROOT": "$env{LLVM_ROOT}",
         "Clang_ROOT": "$env{LLVM_ROOT}",
-        "duktape_ROOT": "$env{DUKTAPE_ROOT}",
-        "Duktape_ROOT": "$env{DUKTAPE_ROOT}",
+        "jerryscript_ROOT": "$env{JERRYSCRIPT_ROOT}",
         "libxml2_ROOT": "$env{LIBXML2_ROOT}",
         "LibXml2_ROOT": "$env{LIBXML2_ROOT}",
         "MRDOCS_BUILD_TESTS": "ON",

docs/modules/ROOT/pages/contribute/codebase-tour.adoc

@@ -59,8 +59,3 @@ The documentation is written in AsciiDoc and can be built using the Antora tool.
 ==== `third-party/`—Helpers for third-party libraries
 
 This directory contains build scripts and configuration files for third-party libraries.
-
-* `third-party/`—Third-party libraries
-** `third-party/llvm/`—CMake Presets for LLVM
-** `third-party/duktape/`—CMake scripts for Duktape
-** `third-party/lua/`—A bundled Lua interpreter

docs/modules/ROOT/pages/install.adoc

@@ -80,14 +80,14 @@ Feel free to install them anywhere you want and adjust the main Mr.Docs configur
 
 [IMPORTANT]
 ====
-All instructions in this document assume you are using a CMake version above 3.26.
+All instructions in this document assume you are using a CMake version at or above 3.13 (project minimum).
 Binaries are available at https://cmake.org/download/[CMake's official website,window="_blank"].
 ====
 
-=== Duktape
+=== JerryScript
 
-Mr.Docs uses the `duktape` library for JavaScript parsing.
-From the `third-party` directory, you can download the `duktape` source code from the official release:
+Mr.Docs embeds the `JerryScript` engine for JavaScript helpers.
+From the `third-party` directory, download the 3.0.0 source archive from the official repository:
 
 [tabs]
 ====
@@ -96,95 +96,47 @@ Windows PowerShell::
 --
 [source,bash]
 ----
-Invoke-WebRequest -Uri "https://github.com/svaarala/duktape/releases/download/v2.7.0/duktape-2.7.0.tar.xz" -OutFile "duktape-2.7.0.tar.xz" <.>
+Invoke-WebRequest -Uri "https://github.com/jerryscript-project/jerryscript/archive/refs/tags/v3.0.0.tar.gz" -OutFile "jerryscript-3.0.0.tar.gz" <.>
 ----
 
-<.> Downloads the `duktape` source code.
+<.> Downloads the `JerryScript` source code.
 --
 
 Unix Variants::
 +
 --
 [source,bash]
 ----
-curl -LJO https://github.com/svaarala/duktape/releases/download/v2.7.0/duktape-2.7.0.tar.xz <.>
+curl -LJO https://github.com/jerryscript-project/jerryscript/archive/refs/tags/v3.0.0.tar.gz <.>
 ----
 
-<.> Downloads the `duktape` source code.
+<.> Downloads the `JerryScript` source code.
 --
 ====
 
-Then patch the Duktape source code to provide CMake support.
+Patch the JerryScript source with our CMake shim and install it:
 
 [source,bash]
 ----
-tar -xf duktape-2.7.0.tar.xz <.>
-cp ../mrdocs/third-party/duktape/CMakeLists.txt ./duktape-2.7.0/CMakeLists.txt <.>
-cp ../mrdocs/third-party/duktape/duktapeConfig.cmake.in ./duktape-2.7.0/duktapeConfig.cmake.in <.>
-cd duktape-2.7.0
-----
-
-<.> Extracts the `duktape` source code.
-<.> Patches the source code with a `CMakeLists.txt` file to the `duktape-2.7.0` directory so that we can build it with CMake.
-<.> Copies the `duktapeConfig.cmake.in` file to the `duktape-2.7.0` directory so that we can install it with CMake and find it later from other CMake projects.
-
-Now adjust the `duk_config.h` file to indicate we are statically building Duktape.
+tar -xf jerryscript-3.0.0.tar.gz <.>
+cp ../mrdocs/third-party/patches/jerryscript/CMakeLists.txt ./jerryscript-3.0.0/CMakeLists.txt <.>
+cp ../mrdocs/third-party/patches/jerryscript/jerryscriptConfig.cmake.in ./jerryscript-3.0.0/jerryscriptConfig.cmake.in <.>
+cd jerryscript-3.0.0
 
-[tabs]
-====
-Windows PowerShell::
-+
---
-[source,bash]
-----
-$content = Get-Content -Path "src\duk_config.h" <.>
-$content = $content -replace '#define DUK_F_DLL_BUILD', '#undef DUK_F_DLL_BUILD' <.>
-$content | Set-Content -Path "src\duk_config.h" <.>
-----
-
-<.> Read the content of `duk_config.h`
-<.> Replace the `DUK_F_DLL_BUILD` macro with `#undef DUK_F_DLL_BUILD`
-<.> Write the content back to the file
---
-
-Unix Variants::
-+
---
-[source,bash]
-----
-sed -i 's/#define DUK_F_DLL_BUILD/#undef DUK_F_DLL_BUILD/g' "src/duk_config.h" <.>
-----
-
-<.> Disables the `DUK_F_DLL_BUILD` macro in the `duk_config.h` file to indicate we are statically building duktape.
---
-
-MacOS::
-+
---
-[source,bash]
-----
-sed -i '' 's/#define DUK_F_DLL_BUILD/#undef DUK_F_DLL_BUILD/g' src/duk_config.h <.>
-----
-
-<.> Disables the `DUK_F_DLL_BUILD` macro in the `duk_config.h` file to indicate we are statically building duktape.
---
-====
-
-And finally install the library with CMake:
-
-[source,bash]
-----
-cmake -S . -B ./build -DCMAKE_BUILD_TYPE=Release <.>
-cmake --build ./build --config Release <.>
-cmake --install ./build --prefix ./install <.>
+cmake -S . -B ./build -DCMAKE_BUILD_TYPE=Release \
+  -DJERRY_PROFILE=es.next -DJERRY_CMDLINE=OFF -DJERRY_TESTS=OFF -DJERRY_DEBUGGER=OFF \
+  -DJERRY_SNAPSHOT_SAVE=OFF -DJERRY_SNAPSHOT_EXEC=OFF \
+  -DJERRY_MEM_STATS=OFF -DJERRY_PARSER_STATS=OFF -DJERRY_LINE_INFO=OFF \
+  -DJERRY_LTO=OFF -DJERRY_LIBC=OFF -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL
+cmake --build ./build --config Release
+cmake --install ./build --prefix ./install
 ----
 
-<.> Configures the `duktape` library with CMake.
-<.> Builds the `duktape` library in the `build` directory.
-<.> Installs the `duktape` library with CMake support in the `install` directory.
+<.> Extracts the `JerryScript` source code.
+<.> Adds CMake packaging files maintained in this repository.
 
-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.
+The build uses JerryScript's upstream default port implementation; no custom
+`port.c` from MrDocs is required.
 
 === Libxml2
 
@@ -317,7 +269,7 @@ cd ../..
 
 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_ROOT`, and `LIBXML2_ROOT` environment variables.
+To specify the installation directories, you can use the `LLVM_ROOT`, `JERRYSCRIPT_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.
 
 You can also customize the presets by duplicating and editing the `CMakeUserPresets.json.example` file in the `mrdocs` directory.

docs/mrdocs.schema.json

@@ -7,6 +7,15 @@
       "title": "Path to the Addons directory",
       "type": "string"
     },
+    "addons-supplemental": {
+      "default": [],
+      "description": "Optional list of supplemental addons directories that are loaded after the base addons (built-in or replacement). Files in later supplemental directories override files from earlier ones and from the base addons. Use this to add or override a few templates/helpers without copying the entire addons tree.",
+      "items": {
+        "type": "string"
+      },
+      "title": "Additional addons layered on top of the base addons",
+      "type": "array"
+    },
     "auto-brief": {
       "default": true,
       "description": "When set to `true`, Mr.Docs uses the first line (until the first dot, question mark, or exclamation mark) of the comment as the brief of the symbol. When set to `false`, a explicit @brief command is required.",