Turn port implementations into proper libraries

This commit changes the concept of JerryScript port implementations
from a simple directory of C source files (which get injected among
the sources of `jerry-core`) into a proper static library (which
may be linked to an application together with `jerry-core`). As a
consequence, this commit introduces a new library to the
JerryScript component architecture: the sources of the default port
implementation form `jerry-port-default`.

Changes in more detail:

- The sources in `targets/default` are moved to `jerry-port/default`
  and are turned into a proper static library.
  - Actually, the default port implementation has two library
    variants, one that implements the bare minimum only
    (`jerry-port-default-minimal`) and one that has some extra
    functionalities specific to this implementation (the "full"
    `jerry-port-default`).
  - The new libraries have an interface header in
    `jerry-port/default/include`, which extends the common
    `jerryscript-port.h` API with functions specific to these
    libraries.
  - All non-standard port functions have now the
    `jerry_port_default_` prefix (this affects `jobqueue_init` and
    `jobqueue_run`).
  - The jobqueue implementation functions became config macro
    independent: it is now the responsibility of the linker to pick
    the needed objects from the library, and omit those (e.g.,
    jobqueue-related code) that are not referenced.
  - Build of the libraries can be controlled with the new
    `JERRY_PORT_DEFAULT` cmake option.

- The cmake option `PORT_DIR` is dropped, and `PORT_DIR/*.c` is not
  appended to `jerry-core` sources.
  - Instead, the `jerry` tool of `jerry-main` links to
    `jerry-port-default`, while `jerry-minimal` links to
    `jerry-port-default-minimal`.
  - `tests/unit-core` tests are also linked to
    `jerry-port-default-minimal`.

- Tools adapted.
  - `build.py` has `--jerry-port-default` instead of `--port-dir`.
  - `check-*.sh` have paths updated (`jerry-port/default` instead
    of `targets/default`).

- Miscellaneous.
  - Dropped `#ifndef`s from `jerryscript-port.h`. It is a public
    header of the `jerry-core` library, which means that it must
    not contain configuration-dependent parts (once the library is
    built with some config macros and the archive and the headers
    are installed, there is no way for the header to tell what
    those config macrose were).
  - Added documentation comments to the JobQueue Port API (in
    `jerryscript-port.h`) and to several default port
    implementation functions (in `jerry-port/default`).

JerryScript-DCO-1.0-Signed-off-by: Akos Kiss [email protected]

Author: akosthekiss

CMakeLists.txt

@@ -25,21 +25,27 @@ set(CMAKE_SHARED_LIBRARY_LINK_C_FLAGS )
 # Components
 set(JERRY_CMDLINE         ON  CACHE BOOL "Build jerry command line tool?")
 set(JERRY_CMDLINE_MINIMAL OFF CACHE BOOL "Build jerry minimal command line tool?")
+set(JERRY_PORT_DEFAULT    ON  CACHE BOOL "Build default jerry port implementation?")
 set(JERRY_LIBC            ON  CACHE BOOL "Build and use jerry-libc?")
 set(JERRY_LIBM            ON  CACHE BOOL "Build and use jerry-libm?")
 set(UNITTESTS             OFF CACHE BOOL "Build unit tests?")
 
 # Optional build settings
-set(ENABLE_ALL_IN_ONE         OFF                                   CACHE BOOL   "Enable all-in-one build?")
-set(ENABLE_LTO                ON                                    CACHE BOOL   "Enable LTO build?")
-set(ENABLE_STATIC_LINK        ON                                    CACHE BOOL   "Enable static linking?")
-set(ENABLE_STRIP              ON                                    CACHE BOOL   "Enable stripping all symbols from release binary?")
-set(PORT_DIR                  "${CMAKE_SOURCE_DIR}/targets/default" CACHE STRING "Use default or external port?")
+set(ENABLE_ALL_IN_ONE  OFF CACHE BOOL "Enable all-in-one build?")
+set(ENABLE_LTO         ON  CACHE BOOL "Enable LTO build?")
+set(ENABLE_STATIC_LINK ON  CACHE BOOL "Enable static linking?")
+set(ENABLE_STRIP       ON  CACHE BOOL "Enable stripping all symbols from release binary?")
 
 if(NOT CMAKE_BUILD_TYPE)
   set(CMAKE_BUILD_TYPE "MinSizeRel")
 endif()
 
+if(JERRY_CMDLINE OR JERRY_CMDLINE_MINIMAL)
+  set(JERRY_PORT_DEFAULT "ON")
+
+  set(JERRY_PORT_DEFAULT_MESSAGE " (FORCED BY CMDLINE)")
+endif()
+
 if("${PLATFORM}" STREQUAL "DARWIN")
   set(JERRY_LIBC         "OFF")
   set(JERRY_LIBM         "OFF")
@@ -85,9 +91,9 @@ message(STATUS "ENABLE_STATIC_LINK        " ${ENABLE_STATIC_LINK} ${ENABLE_STATI
 message(STATUS "ENABLE_STRIP              " ${ENABLE_STRIP} ${ENABLE_STRIP_MESSAGE})
 message(STATUS "JERRY_CMDLINE             " ${JERRY_CMDLINE})
 message(STATUS "JERRY_CMDLINE_MINIMAL     " ${JERRY_CMDLINE_MINIMAL})
+message(STATUS "JERRY_PORT_DEFAULT        " ${JERRY_PORT_DEFAULT} ${JERRY_PORT_DEFAULT_MESSAGE})
 message(STATUS "JERRY_LIBC                " ${JERRY_LIBC} ${JERRY_LIBC_MESSAGE})
 message(STATUS "JERRY_LIBM                " ${JERRY_LIBM} ${JERRY_LIBM_MESSAGE})
-message(STATUS "PORT_DIR                  " ${PORT_DIR})
 message(STATUS "UNITTESTS                 " ${UNITTESTS})
 
 # Setup directories
@@ -156,11 +162,6 @@ if(ENABLE_LTO)
   endif()
 endif()
 
-# Define _BSD_SOURCE and _DEFAULT_SOURCE if we use default port and compiler default libc
-if(${PORT_DIR} STREQUAL "${CMAKE_SOURCE_DIR}/targets/default" AND NOT JERRY_LIBC)
-  set(DEFINES_JERRY ${DEFINES_JERRY} _BSD_SOURCE _DEFAULT_SOURCE)
-endif()
-
 # Compiler / Linker flags
 if (USING_GCC OR USING_CLANG)
   jerry_add_compile_flags(-fno-builtin)
@@ -232,6 +233,11 @@ endif()
 # Jerry's core
 add_subdirectory(jerry-core)
 
+# Jerry's default port implementation
+if(JERRY_PORT_DEFAULT)
+  add_subdirectory(jerry-port/default)
+endif()
+
 # Jerry command line tool
 if(JERRY_CMDLINE OR JERRY_CMDLINE_MINIMAL)
   add_subdirectory(jerry-main)

jerry-core/CMakeLists.txt

@@ -106,9 +106,6 @@ if(FEATURE_DEBUGGER)
   set(SOURCE_CORE_FILES ${SOURCE_CORE_FILES} ${SOURCE_CORE_DEBUGGER})
 endif()
 
-# Jerry port
-file(GLOB SOURCE_PORT_FILES "${PORT_DIR}/*.c")
-
 # All-in-one build
 if(ENABLE_ALL_IN_ONE)
   set(ALL_IN_FILE "${CMAKE_BINARY_DIR}/jerry-all-in.c")

jerry-core/jerryscript-port.h

@@ -140,16 +140,31 @@ bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p);
  */
 double jerry_port_get_current_time (void);
 
-#ifndef CONFIG_DISABLE_ES2015_PROMISE_BUILTIN
-
-#define JERRY_PORT_ENABLE_JOBQUEUE
+/*
+ * JobQueue Port API
+ */
 
+/**
+ * Jerry job handler function type
+ */
 typedef uint32_t (*jerry_job_handler_t) (void *);
 
+/**
+ * Enqueue a job described by a pair of function and data pointers. The port is
+ * expected to call the handler function with the given data at some (later)
+ * point of time.
+ *
+ * @param handler the pointer of the handler function associated with the job.
+ * @param job_p the data pointer to be passed to handler when called.
+ *
+ * Note:
+ *      This port function is only called by the implementation of the Promise
+ *      builtin (mandated by the ES2015 standard). If the engine is built with
+ *      Promise disabled (e.g., with ES5.1 profile), then the port does not have
+ *      to implement this function.
+ */
 void jerry_port_jobqueue_enqueue (jerry_job_handler_t handler, void *job_p);
 
-#endif /* !CONFIG_DISABLE_ES2015_PROMISE_BUILTIN */
-
 /**
  * @}
  */

jerry-main/CMakeLists.txt

@@ -48,7 +48,6 @@ macro(jerry_create_executable JERRY_NAME SOURCE_JERRY_STANDALONE_MAIN)
   set_property(TARGET ${JERRY_NAME}
                PROPERTY LINK_FLAGS "${LINKER_FLAGS_COMMON}")
   target_compile_definitions(${JERRY_NAME} PRIVATE ${DEFINES_JERRY})
-  target_include_directories(${JERRY_NAME} PRIVATE ${PORT_DIR})
   link_directories(${CMAKE_BINARY_DIR})
 
   target_link_libraries(${JERRY_NAME} jerry-core)
@@ -59,8 +58,10 @@ endmacro()
 # Jerry standalones
 if(JERRY_CMDLINE)
   jerry_create_executable("jerry" "main-unix.c")
+  target_link_libraries("jerry" jerry-port-default)
 endif()
 
 if(JERRY_CMDLINE_MINIMAL)
   jerry_create_executable("jerry-minimal" "main-unix-minimal.c")
-endif()
+  target_link_libraries("jerry-minimal" jerry-port-default-minimal)
+endif()

jerry-main/main-unix.c

@@ -593,9 +593,9 @@ main (int argc,
     is_repl_mode = true;
   }
 
-#ifdef JERRY_PORT_ENABLE_JOBQUEUE
-  jerry_port_jobqueue_init ();
-#endif /* JERRY_PORT_ENABLE_JOBQUEUE */
+#ifndef CONFIG_DISABLE_ES2015_PROMISE_BUILTIN
+  jerry_port_default_jobqueue_init ();
+#endif /* !CONFIG_DISABLE_ES2015_PROMISE_BUILTIN */
   jerry_init (flags);
 
   register_js_function ("assert", assert_handler);
@@ -776,15 +776,15 @@ main (int argc,
                                                              args,
                                                              1);
           jerry_release_value (ret_val_print);
-#ifdef JERRY_PORT_ENABLE_JOBQUEUE
+#ifndef CONFIG_DISABLE_ES2015_PROMISE_BUILTIN
           jerry_release_value (ret_val_eval);
-          ret_val_eval = jerry_port_jobqueue_run ();
+          ret_val_eval = jerry_port_default_jobqueue_run ();
 
           if (jerry_value_has_error_flag (ret_value))
           {
             print_unhandled_exception (ret_value);
           }
-#endif /* JERRY_PORT_ENABLE_JOBQUEUE */
+#endif /* !CONFIG_DISABLE_ES2015_PROMISE_BUILTIN */
         }
         else
         {
@@ -807,19 +807,19 @@ main (int argc,
 
     ret_code = JERRY_STANDALONE_EXIT_CODE_FAIL;
   }
-#ifdef JERRY_PORT_ENABLE_JOBQUEUE
+#ifndef CONFIG_DISABLE_ES2015_PROMISE_BUILTIN
   else
   {
     jerry_release_value (ret_value);
-    ret_value = jerry_port_jobqueue_run ();
+    ret_value = jerry_port_default_jobqueue_run ();
 
     if (jerry_value_has_error_flag (ret_value))
     {
       print_unhandled_exception (ret_value);
       ret_code = JERRY_STANDALONE_EXIT_CODE_FAIL;
     }
   }
-#endif /* JERRY_PORT_ENABLE_JOBQUEUE */
+#endif /* !CONFIG_DISABLE_ES2015_PROMISE_BUILTIN */
   jerry_release_value (ret_value);
   jerry_cleanup ();
 

jerry-port/default/CMakeLists.txt

@@ -0,0 +1,43 @@
+# Copyright JS Foundation and other contributors, http://js.foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+cmake_minimum_required (VERSION 2.8.12)
+set(JERRY_PORT_DEFAULT_NAME jerry-port-default)
+project (${JERRY_PORT_DEFAULT_NAME} C)
+
+# Include directories
+set(INCLUDE_PORT_DEFAULT "${CMAKE_CURRENT_SOURCE_DIR}/include")
+
+# Source directories
+file(GLOB SOURCE_PORT_DEFAULT *.c)
+
+# Define _BSD_SOURCE and _DEFAULT_SOURCE
+# (should only be necessary if we used compiler default libc but not checking that)
+set(DEFINES_PORT_DEFAULT _BSD_SOURCE _DEFAULT_SOURCE)
+
+# Default Jerry port implementation library variants:
+#   - default
+#   - default-minimal (no extra termination and log APIs)
+foreach(JERRY_PORT_LIBRARY_NAME ${JERRY_PORT_DEFAULT_NAME} ${JERRY_PORT_DEFAULT_NAME}-minimal)
+  add_library(${JERRY_PORT_LIBRARY_NAME} STATIC ${SOURCE_PORT_DEFAULT})
+  target_include_directories(${JERRY_PORT_LIBRARY_NAME} PUBLIC ${INCLUDE_PORT_DEFAULT})
+  target_compile_definitions(${JERRY_PORT_LIBRARY_NAME} PRIVATE ${DEFINES_PORT_DEFAULT})
+  target_link_libraries(${JERRY_PORT_LIBRARY_NAME} jerry-core)
+endforeach()
+
+target_compile_definitions(${JERRY_PORT_DEFAULT_NAME}-minimal PRIVATE DISABLE_EXTRA_API)
+
+# Installation
+install(TARGETS ${JERRY_PORT_DEFAULT_NAME} ${JERRY_PORT_DEFAULT_NAME}-minimal DESTINATION lib)
+install(DIRECTORY ${INCLUDE_PORT_DEFAULT}/ DESTINATION include)

targets/default/jerry-port-default-date.c renamed to jerry-port/default/default-date.c

@@ -21,9 +21,13 @@
 #include "jerryscript-port-default.h"
 
 /**
- * Default implementation of jerry_port_get_time_zone.
+ * Default implementation of jerry_port_get_time_zone. Uses 'gettimeofday' if
+ * available on the system, does nothing otherwise.
+ *
+ * @return true - if 'gettimeofday' is available and executed successfully,
+ *         false - otherwise.
  */
-bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p)
+bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p) /**< [out] time zone structure to fill */
 {
 #ifdef __GNUC__
   struct timeval tv;
@@ -48,7 +52,12 @@ bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p)
 } /* jerry_port_get_time_zone */
 
 /**
- * Default implementation of jerry_port_get_current_time.
+ * Default implementation of jerry_port_get_current_time. Uses 'gettimeofday' if
+ * available on the system, does nothing otherwise.
+ *
+ * @return milliseconds since Unix epoch - if 'gettimeofday' is available and
+ *                                         executed successfully,
+ *         0 - otherwise.
  */
 double jerry_port_get_current_time (void)
 {

targets/default/jerry-port-default-fatal.c renamed to jerry-port/default/default-fatal.c

@@ -18,11 +18,17 @@
 #include "jerryscript-port.h"
 #include "jerryscript-port-default.h"
 
+#ifndef DISABLE_EXTRA_API
+
 static bool abort_on_fail = false;
 
 /**
  * Sets whether 'abort' should be called instead of 'exit' upon exiting with
  * non-zero exit code in the default implementation of jerry_port_fatal.
+ *
+ * Note:
+ *      This function is only available if the port implementation library is
+ *      compiled without the DISABLE_EXTRA_API macro.
  */
 void jerry_port_default_set_abort_on_fail (bool flag) /**< new value of 'abort on fail' flag */
 {
@@ -35,17 +41,29 @@ void jerry_port_default_set_abort_on_fail (bool flag) /**< new value of 'abort o
  *
  * @return true - if 'abort on fail' flag is set,
  *         false - otherwise
+ *
+ * Note:
+ *      This function is only available if the port implementation library is
+ *      compiled without the DISABLE_EXTRA_API macro.
  */
 bool jerry_port_default_is_abort_on_fail (void)
 {
   return abort_on_fail;
 } /* jerry_port_default_is_abort_on_fail */
 
+#endif /* !DISABLE_EXTRA_API */
+
 /**
- * Default implementation of jerry_port_fatal.
+ * Default implementation of jerry_port_fatal. Calls 'abort' if exit code is
+ * non-zero and "abort-on-fail" behaviour is enabled, 'exit' otherwise.
+ *
+ * Note:
+ *      The "abort-on-fail" behaviour is only available if the port
+ *      implementation library is compiled without the DISABLE_EXTRA_API macro.
  */
 void jerry_port_fatal (jerry_fatal_code_t code)
 {
+#ifndef DISABLE_EXTRA_API
   if (code != 0
       && code != ERR_OUT_OF_MEMORY
       && jerry_port_default_is_abort_on_fail ())
@@ -54,6 +72,9 @@ void jerry_port_fatal (jerry_fatal_code_t code)
   }
   else
   {
+#endif /* !DISABLE_EXTRA_API */
     exit (code);
+#ifndef DISABLE_EXTRA_API
   }
+#endif /* !DISABLE_EXTRA_API */
 } /* jerry_port_fatal */

targets/default/jerry-port-default-io.c renamed to jerry-port/default/default-io.c

@@ -18,31 +18,47 @@
 #include "jerryscript-port.h"
 #include "jerryscript-port-default.h"
 
+#ifndef DISABLE_EXTRA_API
+
 /**
  * Actual log level
  */
-static jerry_log_level_t jerry_log_level = JERRY_LOG_LEVEL_ERROR;
+static jerry_log_level_t jerry_port_default_log_level = JERRY_LOG_LEVEL_ERROR;
+
+#define JERRY_PORT_DEFAULT_LOG_LEVEL jerry_port_default_log_level
 
 /**
  * Get the log level
  *
  * @return current log level
+ *
+ * Note:
+ *      This function is only available if the port implementation library is
+ *      compiled without the DISABLE_EXTRA_API macro.
  */
 jerry_log_level_t
 jerry_port_default_get_log_level (void)
 {
-  return jerry_log_level;
+  return jerry_port_default_log_level;
 } /* jerry_port_default_get_log_level */
 
 /**
  * Set the log level
+ *
+ * Note:
+ *      This function is only available if the port implementation library is
+ *      compiled without the DISABLE_EXTRA_API macro.
  */
 void
 jerry_port_default_set_log_level (jerry_log_level_t level) /**< log level */
 {
-  jerry_log_level = level;
+  jerry_port_default_log_level = level;
 } /* jerry_port_default_set_log_level */
 
+#else /* DISABLE_EXTRA_API */
+#define JERRY_PORT_DEFAULT_LOG_LEVEL JERRY_LOG_LEVEL_ERROR
+#endif /* !DISABLE_EXTRA_API */
+
 /**
  * Provide console message implementation for the engine.
  */
@@ -57,14 +73,21 @@ jerry_port_console (const char *format, /**< format string */
 } /* jerry_port_console */
 
 /**
- * Provide log message implementation for the engine.
+ * Default implementation of jerry_port_log. Prints log message to standard
+ * error with 'vfprintf' if message level is less than or equal to the set log
+ * level.
+ *
+ * Note:
+ *      Changing the log level from JERRY_LOG_LEVEL_ERROR is only possible if
+ *      the port implementation library is compiled without the
+ *      DISABLE_EXTRA_API macro.
  */
 void
 jerry_port_log (jerry_log_level_t level, /**< log level */
                 const char *format, /**< format string */
                 ...)  /**< parameters */
 {
-  if (level <= jerry_log_level)
+  if (level <= JERRY_PORT_DEFAULT_LOG_LEVEL)
   {
     va_list args;
     va_start (args, format);