APL-CORE: March 2020 Release of APL 1.3 compilant core engine

For more details on theis release refer to CHANGELOG.md

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

Author: cohenmic

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+## [1.3.0]
+
+Welcome to the March 2020 release of apl-core-library. This release supports version
+1.3 of the APL specification.
+
+### Added
+
+- Added support for Windows and the Microsoft Visual C++ compiler.
+- Added support for Finish Command.
+- Added background property to documents.
+- Added Time functions for displaying and formatting time values. Included
+  three top-level bound variables for the current time: elapsedTime, localTime,
+  and utcTime.
+- Added export to documents.
+- Added support for the Select command.
+- Added document extensions, extension event handlers and extension commands.
+  The data-binding environment includes a new extensions property that informs
+  the APL document which extensions have been loaded.
+- Added definition for new Backstack Extension to enable back navigation.
+- Added handleKeyUp and handleKeydown properties to the top-level APL document and components.
+- Added dynamic data containers:  LiveArray and LiveMaps.
+
+### Changed
+
+- Updated reported version numbers from 1.2 to 1.3.
+- Bug fixes.
+
+

CMakeLists.txt

@@ -12,6 +12,7 @@
 # permissions and limitations under the License.
 
 cmake_minimum_required(VERSION 3.5)
+project(APLCoreEngine)
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 

Docker.md

@@ -0,0 +1,52 @@
+# README: APL Docker
+
+This Dockerfile provides an image for building and testing the `APL Core Engine` library.
+This image can be used to build and test the core library and to build the library
+documentation.
+
+## Docker
+
+* Install Docker: https://docs.docker.com/get-started/
+* Start in the APLCoreEngine directory
+```bash
+$ cd <workspace>
+$ ls
+APLCoreEngine   APLViewhostAndroid
+$ cd APLCoreEngine
+```
+
+### 1) Create the Docker image
+
+Build an image from the Dockerfile:
+```bash
+$ docker build -t apl:apl-core .
+$ docker images
+```
+
+### 2) Running an interactive shell
+
+Run an interactive bash shell to directly test the container.
+```bash
+$ docker run -it -v "$PWD":/apl/ apl:apl-core
+```
+
+### 3) Build and run the unit tests
+
+Test the core engine by running the unit tests.  This command
+expects your current directory to be `APLCoreEngine`:
+
+```bash
+$ docker run --rm -v "$PWD":/apl/ -w /apl apl:apl-core -c "source apl-dev-env.sh && apl-test-core"
+```
+
+If you had previously built and tested the core engine from outside of Docker, you may need to
+remove your old build directory.  Append a `-f` (force) flag to the `apl-test-core` command.
+
+### 4) Build the documentation
+
+Build the core engine documentation.  This command expects
+your current directory to be `APLCoreEngine`:
+
+```bash
+$ docker run --rm -v "$PWD":/apl/ -w /apl apl:apl-core -c "source apl-dev-env.sh && apl-build-doc"
+```

README.md

@@ -152,10 +152,16 @@ input focus events.
 - Supported Compilers:
   - GNU GCC and G++ version 5.3.1 or higher
   - LLVM and clang version 6.0.0 or higher
+  - MSVC version 16 2019 or higher
 - CMake, version 3.5 or higher
-
-# Building APL Core + Running Tests
-To compile `libaplcore.a` and test in your favorite C++ environment, do the
+- For Windows, Ninja build system, 1.9.0 or higher, see:
+  https://github.com/ninja-build/ninja
+- For Windows, the patch executable should be accessible on the system's PATH.
+  The Windows build has been tested using the patch executable that ships with Git.
+  The GnuWin32 patch executable is NOT recommended.
+
+# Building APL Core + Tests (Linux and Mac OS)
+To build `libaplcore.a` and tests in your favorite C++ environment, do the
 following:
 
 ```
@@ -164,6 +170,21 @@ following:
  $ apl-test-core
 ```
 
+# Building APL Core + Tests (Windows)
+To build `apl.lib` and tests in in a Windows or UWP environment, do the
+following:
+
+```
+ Start a VS Command Prompt (tested with "x64 Native Tools Command Prompt for VS 2019")
+ C:\APLCoreEngine> mkdir build
+ C:\APLCoreEngine> cd build
+ C:\APLCoreEngine\build> cmake -G"Ninja" -DBUILD_TESTS=ON -DCOVERAGE=OFF -DCMAKE_BUILD_TYPE=Release ..
+ C:\APLCoreEngine\build> ninja -j1
+```
+(If using the GnuWin32 patch.exe instead Git's patch.exe, the command prompt may need to run in
+ Administrator Mode)
+
+# Running Tests
 After the build succeeds, there are a number of test programs included in the `build/test`
 directory.  For example, to validate the color parser, try:
 
@@ -212,4 +233,11 @@ In order to build the tools use:
 ```
 $ cmake -DTOOLS=ON
 ```
+
+## Paranoid build
+In order to build library with -Werror use:
+```
+$ cmake -DWERROR=ON
+```
+
 ≠≠≠

apl-dev-env.sh

@@ -19,6 +19,15 @@ export APL_DIR=$(pwd)
 # Amazon Linux uses cmake3
 export CMAKE=$(command -v cmake3 || command -v cmake)
 
+if [ -e /proc/cpuinfo ]; then # Linux
+    APL_BUILD_PROCS=$(grep -c ^processor /proc/cpuinfo)
+elif [ $(sysctl -n hw.ncpu) ]; then # Mac
+    APL_BUILD_PROCS=$(sysctl -n hw.ncpu)
+else # Other/fail
+    APL_BUILD_PROCS=4
+fi
+export APL_BUILD_PROCS
+
 
 function apl-parse-args {
     FORCE=false
@@ -96,15 +105,23 @@ function apl-build-core {  # Run make for the core build
     (
         apl-switch-to-build-directory build $@ && \
         $CMAKE -DBUILD_TESTS=ON -DCOVERAGE=OFF .. && \
-        make -j4
+        make -j$APL_BUILD_PROCS
+    )
+}
+
+function apl-check-core {  # Run make for the core build with -Werror
+    (
+        apl-switch-to-build-directory build $@ && \
+        $CMAKE -DBUILD_TESTS=ON -DWERROR=ON -DCOVERAGE=OFF .. && \
+        make -j$APL_BUILD_PROCS
     )
 }
 
 function apl-test-core {  # Run unit tests in the core build
     (
         apl-switch-to-build-directory build $@ && \
         $CMAKE -DBUILD_TESTS=ON -DCOVERAGE=OFF .. && \
-        make -j4 && \
+        make -j$APL_BUILD_PROCS && \
         unit/unittest
     )
 }
@@ -134,15 +151,15 @@ function apl-build-doc {  # Run make for the documentation
     (
         apl-switch-to-build-directory doc-build $@ && \
         $CMAKE .. && \
-        make -j4 doc
+        make -j$APL_BUILD_PROCS doc
     )
 }
 
 function apl-open-doc {   # Open the documentation (works on MacOS)
     (
         apl-switch-to-build-directory doc-build $@ && \
         $CMAKE .. && \
-        make -j4 doc && \
+        make -j$APL_BUILD_PROCS doc && \
         open html/index.html
     )
 }
@@ -215,15 +232,13 @@ function apl-config-android { # Run cmake for Android
             rm -rf android-build
         fi
 
-        if [[ ! -e android-build ]] ; then
-            mkdir android-build
-            cd android-build
-            echo "Running $CMAKE"
-            $CMAKE -DANDROID_ABI="x86" \
-                   -DANDROID_PLATFORM=android-24 \
-                   -DCMAKE_TOOLCHAIN_FILE=$TOOLCHAIN_FILE \
-                   -DAPL_JNI=ON ..
-        fi
+        mkdir -p android-build
+        cd android-build
+        echo "Running $CMAKE"
+        $CMAKE -DANDROID_ABI="x86" \
+               -DANDROID_PLATFORM=android-24 \
+               -DCMAKE_TOOLCHAIN_FILE=$TOOLCHAIN_FILE \
+               -DAPL_JNI=ON ..
     )
 }
 
@@ -245,8 +260,8 @@ function apl-clean-android {
 function apl-build-android { # Run make for the Android build
     (
         cd $APL_DIR
-        [[ -e android-build ]] || apl-config-android
-        cd android-build && make -j4
+        apl-config-android
+        cd android-build && make -j$APL_BUILD_PROCS
     )
 }
 
@@ -264,18 +279,16 @@ function apl-verify-android { # verify android - assemble, test, build without l
 function apl-config-wasm {  # Run cmake in the wasm build
     (
         cd $APL_DIR
-        if [[ ! -e wasm-build ]] ; then
-            mkdir wasm-build
-            cd wasm-build
-            emcmake cmake -DEMSCRIPTEN=ON -DBUILD_TESTS=OFF -DCMAKE_BUILD_TYPE=Debug -DEMSCRIPTEN_SOURCEMAPS=ON -DBUILD_TESTS=OFF ..
-        fi
+        mkdir -p wasm-build
+        cd wasm-build
+        emcmake cmake -DEMSCRIPTEN=ON -DBUILD_TESTS=OFF -DCMAKE_BUILD_TYPE=Debug -DEMSCRIPTEN_SOURCEMAPS=ON -DBUILD_TESTS=OFF ..
     )
 }
 
 function apl-clean-wasm {
     (
         cd $APL_DIR
-        [[ -e wasm-build ]] || apl-config-wasm
+        apl-config-wasm
 
         cd wasm-build && make clean
     )
@@ -284,16 +297,16 @@ function apl-clean-wasm {
 function apl-build-wasm { # Build the wasm source
     (
         cd $APL_DIR
-        [[ -e wasm-build ]] || apl-config-wasm
+        apl-config-wasm
 
-        cd wasm-build && make -j4 && make wasm-build
+        cd wasm-build && make -j$APL_BUILD_PROCS && make wasm-build
     )
 }
 
 function apl-install-wasm {  # Install the wasm source for the sandbox
     (
         cd $APL_DIR
-        [[ -e wasm-build ]] || apl-build-wasm
+        apl-build-wasm
 
         cd wasm-build && make install
     )
@@ -302,7 +315,7 @@ function apl-install-wasm {  # Install the wasm source for the sandbox
 function apl-run-wasm-sandbox {  # Run the wasm sandbox.  Does not return
     (
         cd $APL_DIR
-        [[ -e wasm-build ]] || apl-install-wasm
+        apl-install-wasm
 
         cd wasm/js/apl-wasm-sandbox && node server.js public
     )
@@ -311,7 +324,7 @@ function apl-run-wasm-sandbox {  # Run the wasm sandbox.  Does not return
 function apl-test-wasm {  # Run wasm tests.  Does not return
     (
         cd $APL_DIR
-        [[ -e wasm-build ]] || apl-config-wasm
+        apl-config-wasm
 
         cd wasm-build && make install && make wasm-test
     )
@@ -339,3 +352,9 @@ function apl-test-all { # Test all sources
     apl-test-core
     apl-test-wasm
 }
+
+function apl-distclean { # Distclean removes all artifacts from building and configuring
+    apl-clean-all
+    rm -rf build # remove core artifacts
+    rm -rf ./*-build* # remove viewhost artifacts
+}