APL-CORE: July 2023 Release of APL 2023.2 compilant core engine (2023.2.0)

For more details on this release refer to CHANGELOG.md

To learn about APL see: https://developer.amazon.com/docs/alexa-presentation-language/understand-apl.html

Author: achsaini

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [2023.2]
+
+This release adds support for version 2023.2 of the APL specification.
+
+### Added
+
+- Deferred evaluation
+- SeekTo command for video
+- Alpha feature: Host component
+- Alpha feature: Support for viewport autosize
+- Alpha feature: InsertItem and RemoveItem command
+
+### Changed
+
+- Bug fixes
+- Performance improvements.
+
 ## [2023.1]
 
 ### Added

CMakeLists.txt

@@ -19,6 +19,11 @@ cmake_minimum_required(VERSION 3.11)
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
+if(POLICY CMP0135)
+    # If available, use the new timestamp policy for FetchContent
+    cmake_policy(SET CMP0135 NEW)
+endif()
+
 project(APLCoreEngine
         VERSION 1.0.0
         LANGUAGES CXX)
@@ -32,3 +37,13 @@ include(options.cmake)
 set(APL_PATCH_DIR "${CMAKE_CURRENT_SOURCE_DIR}/patches")
 
 include(components.cmake)
+
+if (BUILD_UNIT_TESTS)
+    include(CTest)
+
+    set(MEMCHECK_OPTIONS "--tool=memcheck --leak-check=full --show-reachable=no --error-exitcode=1 --errors-for-leak-kinds=definite,possible")
+    add_custom_target(unittest_memcheck
+        COMMAND ${CMAKE_CTEST_COMMAND} -VV
+        --overwrite MemoryCheckCommandOptions=${MEMCHECK_OPTIONS}
+        -T memcheck)
+endif()

README.md

@@ -263,12 +263,6 @@ To build lib with memory debugging support use:
 $ cmake -DDEBUG_MEMORY_USE=ON
 ```
 
-## Tools
-In order to build the tools use:
-```
-$ cmake -DTOOLS=ON
-```
-
 ## Paranoid build
 In order to build library with -Werror use:
 ```

apl-dev-env.sh

@@ -130,7 +130,9 @@ function apl-test-core {  # Run unit tests in the core build
         apl-switch-to-build-directory build $@ && \
         $CMAKE -DBUILD_TESTS=ON  -DCOVERAGE=OFF .. && \
         make -j$APL_BUILD_PROCS && \
-        unit/unittest
+        aplcore/unit/unittest && \
+        tools/unit/tools-unittest && \
+        extensions/unit/alexaext-unittest
     )
 }
 
@@ -139,7 +141,9 @@ function apl-memcheck-core {  # Run unit tests in the core build
         apl-switch-to-build-directory build $@ && \
         $CMAKE -DBUILD_TESTS=ON  -DCOVERAGE=OFF .. && \
         make -j$APL_BUILD_PROCS && \
-        valgrind --tool=memcheck --gen-suppressions=all --track-origins=yes --leak-check=full --num-callers=50 ./unit/unittest
+        valgrind --tool=memcheck --gen-suppressions=all --track-origins=yes --leak-check=full --num-callers=50 ./aplcore/unit/unittest && \
+        valgrind --tool=memcheck --gen-suppressions=all --track-origins=yes --leak-check=full --num-callers=50 ./tools/unit/tools-unittest && \
+        valgrind --tool=memcheck --gen-suppressions=all --track-origins=yes --leak-check=full --num-callers=50 ./extensions/unit/alexaext-unittest
     )
 }
 

aplcore/CMakeLists.txt

@@ -57,13 +57,12 @@ if (TARGET yoga)
     add_dependencies(apl yoga)
 endif()
 
-if (NOT HAS_FETCH_CONTENT)
-    add_dependencies(apl pegtl-build)
+if (NOT USE_PROVIDED_YOGA_INLINE)
+    target_link_libraries(apl PUBLIC $<BUILD_INTERFACE:libyoga>)
 endif()
 
-# When not using the system rapidjson build the library, add a dependency on the build step
-if (NOT USE_SYSTEM_RAPIDJSON AND NOT HAS_FETCH_CONTENT)
-    add_dependencies(apl rapidjson-build)
+if (NOT HAS_FETCH_CONTENT)
+    add_dependencies(apl pegtl-build)
 endif()
 
 add_subdirectory(src/action)
@@ -75,6 +74,7 @@ add_subdirectory(src/content)
 add_subdirectory(src/datagrammar)
 add_subdirectory(src/datasource)
 add_subdirectory(src/document)
+add_subdirectory(src/embed)
 add_subdirectory(src/engine)
 add_subdirectory(src/extension)
 add_subdirectory(src/focus)
@@ -100,7 +100,9 @@ set_target_properties(apl
     PROPERTIES
         VERSION "${PROJECT_VERSION}"
         SOVERSION 1
-        PUBLIC_HEADER "${PUBLIC_HEADER_LIST}")
+        PUBLIC_HEADER "${PUBLIC_HEADER_LIST}"
+        EXPORT_NAME "core"
+)
 
 if (ENABLE_PIC)
   set_target_properties(apl
@@ -116,19 +118,16 @@ target_include_directories(apl
     PUBLIC
         $<BUILD_INTERFACE:${CMAKE_CURRENT_LIST_DIR}/include>
         $<BUILD_INTERFACE:${PROJECT_BINARY_DIR}/aplcore/include>
-        $<BUILD_INTERFACE:${RAPIDJSON_INCLUDE}>
         $<INSTALL_INTERFACE:include>
     PRIVATE
         $<BUILD_INTERFACE:${PEGTL_INCLUDE}>
         $<BUILD_INTERFACE:${YOGA_INCLUDE}>
 )
 
+target_link_libraries(apl PUBLIC rapidjson-apl)
+
 if (USE_PROVIDED_YOGA_INLINE)
     target_sources(apl PRIVATE ${YOGA_SRC})
-else()
-    target_link_libraries(apl
-        PRIVATE
-            libyoga)
 endif()
 
 # include the alexa extensions library
@@ -159,6 +158,12 @@ target_link_libraries(apl PRIVATE ${log-lib})
 
 endif(ANDROID)
 
+# Test cases are built conditionally. Only affect core do not build them for everything else.
+if (BUILD_UNIT_TESTS)
+    include_directories(${GTEST_INCLUDE})
+    add_subdirectory(unit)
+endif (BUILD_UNIT_TESTS)
+
 install(TARGETS apl
         EXPORT apl-targets
         ARCHIVE DESTINATION lib
@@ -173,12 +178,6 @@ install(DIRECTORY ${PROJECT_SOURCE_DIR}/aplcore/include/apl
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/apl.pc
         DESTINATION lib/pkgconfig)
 
-if (NOT USE_SYSTEM_RAPIDJSON)
-install(DIRECTORY ${RAPIDJSON_INCLUDE}/rapidjson
-        DESTINATION include
-        FILES_MATCHING PATTERN "*.h")
-endif()
-
 if (USE_PROVIDED_YOGA_AS_LIB)
     # We built the bundled yoga lib, install it
     install(FILES ${YOGA_LIB}
@@ -189,16 +188,6 @@ if (USE_PROVIDED_YOGA_AS_LIB)
     set(YOGA_EXTERNAL_LIB ${YOGA_LIB}) # used by aplcoreConfig.cmake.in
 endif()
 
-if (NOT USE_PROVIDED_YOGA_INLINE)
-set_target_properties(apl PROPERTIES
-    EXPORT_NAME
-        core
-    INTERFACE_LINK_LIBRARIES
-        # Only set this for builds, the find module will handle the other cases
-        $<BUILD_INTERFACE:${YOGA_LIB}>
-)
-endif()
-
 export(
     EXPORT
         apl-targets
@@ -227,4 +216,4 @@ install(
         ${CMAKE_CURRENT_BINARY_DIR}/aplcoreConfig.cmake
     DESTINATION
         lib/cmake/aplcore
-)
+)

aplcore/aplcoreConfig.cmake.in

@@ -1,30 +1,51 @@
 @PACKAGE_INIT@
 
+set(USE_PROVIDED_YOGA_INLINE @USE_PROVIDED_YOGA_INLINE@)
 set(YOGA_EXTERNAL_LIB @YOGA_EXTERNAL_LIB@)
-
-if(YOGA_EXTERNAL_LIB)
-    set_and_check(aplcore_yoga_LIBRARY "${YOGA_EXTERNAL_LIB}")
-else()
-    # This file gets installed at ${APL_CORE_INSTALL_DIR}/lib/cmake/aplcore/aplcoreConfig.cmake, so go up 3 directories
-    # to find the root
-    get_filename_component(APL_CORE_INSTALL_DIR "${CMAKE_CURRENT_LIST_DIR}/../../../" ABSOLUTE)
-
-    set_and_check(aplcore_yoga_LIBRARY "${APL_CORE_INSTALL_DIR}/lib/@YOGA_LIB_NAME@")
-
-endif()
+set(USE_SYSTEM_RAPIDJSON @USE_SYSTEM_RAPIDJSON@)
 
 set(ENABLE_ALEXAEXTENSIONS @ENABLE_ALEXAEXTENSIONS@)
-set(USE_INTERNAL_ALEXAEXT @BUILD_ALEXAEXTENSIONS@)
 
 if(ENABLE_ALEXAEXTENSIONS)
-    if(NOT USE_INTERNAL_ALEXAEXT)
-        find_package(alexaext REQUIRED)
-    endif()
+    find_package(alexaext REQUIRED)
 endif(ENABLE_ALEXAEXTENSIONS)
 
+# For backwards-compatibility with the old build logic, try to locate RapidJSON on the system if the
+# new CMake package is not found
+if (NOT TARGET rapidjson-apl)
+    if (USE_SYSTEM_RAPIDJSON)
+        find_package(aplrapidjson QUIET)
+        if (NOT aplrapidjson_FOUND)
+            # Try to locate RapidJSON on the system
+            find_package(RapidJSON QUIET)
+
+            if (NOT RapidJSON_FOUND)
+                # Try to find the headers directly on the system
+                find_path(RAPIDJSON_INCLUDE_DIRS
+                NAMES rapidjson/document.h
+                REQUIRED)
+            endif()
+
+            add_library(rapidjson-apl INTERFACE IMPORTED)
+            target_include_directories(rapidjson-apl INTERFACE ${RAPIDJSON_INCLUDE_DIRS})
+        endif()
+    else()
+        find_package(aplrapidjson REQUIRED)
+    endif()
+endif()
+
 include("${CMAKE_CURRENT_LIST_DIR}/aplcoreTargets.cmake")
 
-set_target_properties(apl::core
-    PROPERTIES
-        INTERFACE_LINK_LIBRARIES "${aplcore_yoga_LIBRARY}"
-)
+if (NOT USE_PROVIDED_YOGA_INLINE)
+    # Yoga is not built into core, so add the dependency here
+    if(YOGA_EXTERNAL_LIB)
+        set_and_check(aplcore_yoga_LIBRARY "${YOGA_EXTERNAL_LIB}")
+    else()
+        # This file gets installed at ${APL_CORE_INSTALL_DIR}/lib/cmake/aplcore/aplcoreConfig.cmake, so go up 3 directories
+        # to find the root
+        get_filename_component(APL_CORE_INSTALL_DIR "${CMAKE_CURRENT_LIST_DIR}/../../../" ABSOLUTE)
+
+        set_and_check(aplcore_yoga_LIBRARY "${APL_CORE_INSTALL_DIR}/lib/@YOGA_LIB_NAME@")
+    endif()
+    target_link_libraries(apl::core INTERFACE "${aplcore_yoga_LIBRARY}")
+endif()

aplcore/buildTimeConstants.cpp.in

@@ -17,4 +17,6 @@ namespace apl {
 
 const char *sCoreRepositoryVersion = "@CORE_REPOSITORY_VERSION@";
 
+int kEvaluationDepthLimit = @EVALUATION_DEPTH_LIMIT@;
+
 } // namespace apl

aplcore/include/apl/action/action.h

@@ -16,18 +16,13 @@
 #ifndef _APL_ACTION_H
 #define _APL_ACTION_H
 
-#include <cassert>
-#include <functional>
-#include <memory>
-#include <vector>
-
 #include "apl/common.h"
+#include "apl/primitives/rect.h"
 #include "apl/time/timers.h"
 #include "apl/utils/counter.h"
 #include "apl/utils/noncopyable.h"
 #include "apl/utils/streamer.h"
 #include "apl/utils/userdata.h"
-#include "apl/primitives/rect.h"
 
 namespace apl {
 
@@ -200,10 +195,10 @@ class Action : public std::enable_shared_from_this<Action>,
 
     /**
      * Revive an action in the new context.
-     * @param context new RootContext.
+     * @param context new DocumentContext.
      * @return true if successful, false otherwise.
      */
-    virtual bool rehydrate(const RootContext& context);
+    virtual bool rehydrate(const CoreDocumentContext& context);
 
 protected:
     virtual void onFinish() {}

aplcore/include/apl/action/animatedscrollaction.h

@@ -30,7 +30,7 @@ class AnimatedScrollAction : public ResourceHoldingAction {
 
 
     void freeze() override;
-    bool rehydrate(const RootContext& context) override;
+    bool rehydrate(const CoreDocumentContext& context) override;
 
 protected:
     AnimatedScrollAction(const TimersPtr& timers,

aplcore/include/apl/action/animateitemaction.h

@@ -38,7 +38,7 @@ class AnimateItemAction : public ResourceHoldingAction {
                       bool fastMode);
 
     void freeze() override;
-    bool rehydrate(const RootContext& context) override;
+    bool rehydrate(const CoreDocumentContext& context) override;
 
 private:
     void start();

aplcore/include/apl/action/arrayaction.h

@@ -25,14 +25,14 @@ namespace apl {
 class ArrayAction : public Action {
 public:
     static std::shared_ptr<ArrayAction> make(const TimersPtr& timers,
-                                             std::shared_ptr<const ArrayCommand> command,
+                                             std::shared_ptr<const ArrayCommand>&& command,
                                              bool fastMode) {
-        auto ptr = std::make_shared<ArrayAction>(timers, command, fastMode);
+        auto ptr = std::make_shared<ArrayAction>(timers, std::move(command), fastMode);
         ptr->advance();
         return ptr;
     }
 
-    ArrayAction(const TimersPtr& timers, std::shared_ptr<const ArrayCommand> command, bool fastMode);
+    ArrayAction(const TimersPtr& timers, std::shared_ptr<const ArrayCommand>&& command, bool fastMode);
 
 private:
     void advance();

aplcore/include/apl/action/autopageaction.h

@@ -16,8 +16,8 @@
 #ifndef _APL_AUTO_PAGE_ACTION_H
 #define _APL_AUTO_PAGE_ACTION_H
 
-#include "apl/action/resourceholdingaction.h"
 #include "apl/common.h"
+#include "apl/action/resourceholdingaction.h"
 
 namespace apl {
 
@@ -40,7 +40,7 @@ class AutoPageAction : public ResourceHoldingAction {
                    apl_time_t duration);
 
     void freeze() override;
-    bool rehydrate(const RootContext& context) override;
+    bool rehydrate(const CoreDocumentContext& context) override;
 
 private:
     void advance();

aplcore/include/apl/action/delayaction.h

@@ -36,7 +36,7 @@ class DelayAction : public Action {
     DelayAction(const TimersPtr& timers, const CommandPtr& command, bool fastMode);
 
     void freeze() override;
-    bool rehydrate(const RootContext& context) override;
+    bool rehydrate(const CoreDocumentContext& context) override;
 
 private:
     /**

aplcore/include/apl/action/playmediaaction.h

@@ -40,7 +40,7 @@ class PlayMediaAction : public ResourceHoldingAction {
                     const ComponentPtr& target);
 
     void freeze() override;
-    bool rehydrate(const RootContext& context) override;
+    bool rehydrate(const CoreDocumentContext& context) override;
 
 private:
     void start();

aplcore/include/apl/action/resourceholdingaction.h

@@ -29,7 +29,7 @@ class ResourceHoldingAction : public Action {
                           const ContextPtr& context);
 
     void freeze() override;
-    bool rehydrate(const RootContext& context) override;
+    bool rehydrate(const CoreDocumentContext& context) override;
 
 protected:
     void onFinish() override;

aplcore/include/apl/action/scrollaction.h

@@ -58,7 +58,7 @@ class ScrollAction : public AnimatedScrollAction {
                  apl_duration_t duration);
 
     void freeze() override;
-    bool rehydrate(const RootContext& context) override;
+    bool rehydrate(const CoreDocumentContext& context) override;
 
 private:
     void start();