16.MIGRATION-GUIDE.md

Migration guide

This guide intends to describe the major changes between the JerryScript 1.0 and 2.0 versions. In addition it is designed to provide a guide on how to modify the 1.0 version code to a 2.0 compliant code.

During the development it was important to minimize the changes in the API functions and types. Each API method removal or change is described below providing a before and after code example. For more information on the current API methods please check the API reference document.

Short list of removed/renamed headers, types, functions, and macros

Removed legacy headers

• jerry-internal.h

Renamed headers

• jerry-api.h to jerryscript.h
• jerry-port.h to jerryscript-port.h

Removed API types

• jerry_char_ptr_t usage replaced with jerry_char_t *
• jerry_object_free_callback_t replaced by jerry_object_native_free_callback_t

Removed API methods

• jerry_get_memory_limits
• jerry_get_object_native_handle replaced by jerry_get_object_native_pointer
• jerry_set_object_native_handle replaced by jerry_set_object_native_pointer
• jerry_value_set_abort_flag replaced by jerry_create_abort_from_value
• jerry_value_has_abort_flag replaced by jerry_value_is_abort
• jerry_value_set_error_flag replaced by jerry_create_error_from_value
• jerry_value_has_error_flag replaced by jerry_value_is_error
• jerry_value_clear_error_flag replaced by jerry_get_value_from_error
• jerry_get_value_without_error_flag replaced by jerry_get_value_from_error
• jerry_parse_and_save_snapshot replaced by jerry_generate_snapshot
• jerry_parse_and_save_function_snapshot replaced by jerry_generate_function_snapshot

Removed unused configuration macros

• CONFIG_MEM_DATA_LIMIT_MINUS_HEAP_SIZE
• CONFIG_MEM_STACK_LIMIT
• CONFIG_VM_STACK_FRAME_INLINED_VALUES_NUMBER
• CONFIG_ECMA_GLOBAL_ENVIRONMENT_DECLARATIVE
• All CONFIG_.. macros have been renamed to use the JERRY_ prefix format.

Modified API functions

Error manipulating functions

The most important changes in the API are related to error handling and manipulation.

jerry_value_set_abort_flag

This function was replaced with jerry_create_abort_from_value. Take note of the second argument of the new jerry_create_abort_from_value function which controls if the first argument should be usable after the call or not.

Before

{
  jerry_value_t value;
  // create or acquire value
  // ...

  jerry_value_set_abort_flag (&value);

  jerry_release_value (value);
}

After

{
  jerry_value_t value;
  // create or acquire value
  // ...

  jerry_value_t abort = jerry_create_abort_from_value (value, true);
  // using the 'value' variable after release is invalid

  jerry_release_value (abort);
}

• OR

{
  jerry_value_t value;
  ... // create or acquire value

  jerry_value_t abort = jerry_create_abort_from_value (value, false);
  // both 'abort' and 'value' can be used and must be released when they are no longer needed

  jerry_release_value (abort);
  jerry_release_value (value);
}

jerry_value_has_abort_flag

This function was renamed to jerry_value_is_abort.

Before

{
  jerry_value_t value;
  // create or acquire value
  // ...

  if (jerry_value_has_abort_flag (value))
  {
    // ...
  }

  jerry_release_value (value);
}

After

{
  jerry_value_t value;
  // create or acquire value
  // ...

  if (jerry_value_is_abort (value))
  {
    // ...
  }

  jerry_release_value (value);
}

jerry_value_set_error_flag

This function was replaced with jerry_create_error_from_value. Take note of the second argument of the new jerry_create_error_from_value function which controls if the first argument should be usable after the call or not.

Before

{
  jerry_value_t value;
  // create or acquire value
  // ...

  jerry_value_set_error_flag (&value);

  jerry_release_value (value);
}

After

{
  jerry_value_t value;
  // create or acquire value
  // ...

  jerry_value_t error = jerry_create_error_from_value (value, true);
  // using the 'value' variable after release is invalid

  jerry_release_value (error);
}

• OR

{
  jerry_value_t value;
  // create or acquire value
  // ...

  jerry_value_t error = jerry_create_error_from_value (value, false);
  // both 'error' and 'value' can be used and must be released when they are no longer needed

  jerry_release_value (error);
  jerry_release_value (value);
}

jerry_value_has_error_flag

This function was renamed to jerry_value_is_error.

Before

{
  jerry_value_t value;
  // create or acquire value
  // ...

  if (jerry_value_has_error_flag (value))
  {
    // ...
  }

  jerry_release_value (value);
}

After

{
  jerry_value_t value;
  // create or acquire value
  // ...

  if (jerry_value_is_error (value))
  {
    // ...
  }

  jerry_release_value (value);
}

jerry_value_clear_error_flag AND jerry_get_value_without_error_flag

These functions were merged into jerry_get_value_from_error. Please note the second argument of the new function which controls if the first argument passed should be released or not.

Before

{
  jerry_value_t value;
  // create or acquire value
  // ...

  jerry_value_set_error_flag (&value);
  jerry_value_clear_error_flag (&value);
  // or
  jerry_value_t real_value = jerry_get_value_without_error_flag (value);

  jerry_release_value (value);
  jerry_release_value (real_value);
}

After

{
  jerry_value_t value;
  // create or acquire value
  // ...

  jerry_value_t error = jerry_create_error_from_value (value, true);

  jerry_value_t real_value = jerry_get_value_from_error (error, true);

  jerry_release_value (real_value);
}

Other functions changed

jerry_register_magic_strings

In case of the jerry_register_magic_strings function the change is that the first argument's base type jerry_char_ptr_t was changed to jerry_char_t*. For more details see: jerry_register_magic_strings.

In the following code parts please take note of the type used for the magic_string_items array.

Before

{
  // must be static, because 'jerry_register_magic_strings' does not copy
  // the items must be sorted by size at first, then lexicographically
  static const jerry_char_ptr_t magic_string_items[] = {
                                                          (const jerry_char_ptr_t) "magicstring1",
                                                          (const jerry_char_ptr_t) "magicstring2",
                                                          (const jerry_char_ptr_t) "magicstring3"
                                                        };
  uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_ptr_t));

  // must be static, because 'jerry_register_magic_strings' does not copy
  static const jerry_length_t magic_string_lengths[] = { 12, 12, 12 };
  jerry_register_magic_strings (magic_string_items, num_magic_string_items, magic_string_lengths);
}

After

{
  // must be static, because 'jerry_register_magic_strings' does not copy
  // the items must be sorted by size at first, then lexicographically
  static const jerry_char_t *magic_string_items[] = {
                                                      (const jerry_char_t *) "magicstring1",
                                                      (const jerry_char_t *) "magicstring2",
                                                      (const jerry_char_t *) "magicstring3"
                                                    };
  uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_t *));

  // must be static, because 'jerry_register_magic_strings' does not copy
  static const jerry_length_t magic_string_lengths[] = { 12, 12, 12 };
  jerry_register_magic_strings (magic_string_items, num_magic_string_items, magic_string_lengths);
}

Snapshot generating API

jerry_parse_and_save_snapshot

This function was replaced with jerry_generate_snapshot. The function returns an error object if there was any problem during snapshot generation and if there was no problem the return value is a number value containing the snapshot size in bytes.

Before

{
  static uint32_t global_mode_snapshot_buffer[256];
  const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";

  size_t global_mode_snapshot_size =
    jerry_parse_and_save_snapshot (code_to_snapshot_p,
                                   strlen ((const char *) code_to_snapshot_p),
                                   true,
                                   false,
                                   global_mode_snapshot_buffer,
                                   sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
  // use "global_mode_snapshot_buffer"
}

After

{
  static uint32_t global_mode_snapshot_buffer[256];
  const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";

  jerry_value_t generate_result;
  generate_result = jerry_generate_snapshot (NULL,
                                             0,
                                             code_to_snapshot_p,
                                             strlen ((const char *) code_to_snapshot_p),
                                             global_mode_snapshot_buffer,
                                             sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
  if (jerry_value_is_error (generate_result))
  {
    // There was a problem during snapshot generation, for example there is a SyntaxError.
    // Use the "generate_result" to check the error.
  }
  else
  {
    size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
    // use "global_mode_snapshot_buffer"
  }
  jerry_release_value (generate_result);
}

jerry_parse_and_save_function_snapshot

This function was replaced with jerry_generate_function_snapshot. The function returns an error object if there was any problem during snapshot generation and if there was no problem the return value is a number value containing the snapshot size in bytes.

Before

{
  static uint32_t func_snapshot_buffer[1024];

  const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
  const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";

  size_t func_snapshot_size =
  jerry_parse_and_save_function_snapshot (src_p,
                                          strlen ((const char *) src_p),
                                          args_p,
                                          strlen ((const char *) args_p),
                                          false,
                                          func_snapshot_buffer,
                                          sizeof (func_snapshot_buffer) / sizeof (uint32_t));
  // check "function_snapshot_size" and use "func_snapshot_buffer"
}

After

{
  static uint32_t func_snapshot_buffer[1024];

  const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
  const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";

  jerry_value_t generate_result;
  generate_result = jerry_generate_function_snapshot (NULL,
                                                      0,
                                                      src_p,
                                                      strlen ((const char *) src_p),
                                                      args_p,
                                                      strlen ((const char *) args_p),
                                                      0,
                                                      func_snapshot_buffer,
                                                      sizeof (func_snapshot_buffer) / sizeof (uint32_t));
  if (jerry_value_is_error (generate_result))
  {
    // There was a problem during snapshot generation, for example there is a SyntaxError.
    // Use the "generate_result" to check the error.
  }
  else
  {
    size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
    // use "func_snapshot_buffer"
  }

  jerry_release_value (generate_result)
}

Garbage collection

jerry_gc

The jerry_gc function was modified to handle an argument which represents the pressure for the garbage collector. For more information checkout the jerry_gc_mode_t reference.

Before

{
  jerry_gc ();
}

After

{
  jerry_gc (JERRY_GC_PRESSURE_LOW);
}

jerry_eval

The third argument of jerry_eval has been changed from bool to jerry_parse_opts_t.

Before

const jerry_char_t *str_to_eval = (const jerry_char_t *) "1 + 1";
jerry_value_t ret_val = jerry_eval (str_to_eval,
                                    strlen ((const char *) str_to_eval),
                                    false);

After

const jerry_char_t *str_to_eval = (const jerry_char_t *) "1 + 1";
jerry_value_t ret_val = jerry_eval (str_to_eval,
                                    strlen ((const char *) str_to_eval),
                                    JERRY_PARSE_NO_OPTS);

Port API

jerry_port_get_time_zone

The port API of handling timezones has been changed. The previous interface did not allow timezones to be handled correctly, even if the host system was up to the task. Check the related issue for more details.

The new port API function name is [jerry_port_get_local_time_zone_adjustment](05.PORT-API.md#date-1].

Below is the default implementations for both versions:

Before

bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p)
{
  struct timeval tv;
  struct timezone tz;

  /* gettimeofday may not fill tz, so zero-initializing */
  tz.tz_minuteswest = 0;
  tz.tz_dsttime = 0;

  if (gettimeofday (&tv, &tz) != 0)
  {
    return false;
  }

  tz_p->offset = tz.tz_minuteswest;
  tz_p->daylight_saving_time = tz.tz_dsttime > 0 ? 1 : 0;

  return true;
} /* jerry_port_get_time_zone */

After

double jerry_port_get_local_time_zone_adjustment (double unix_ms,
                                                  bool is_utc)
{
  struct tm tm;
  time_t now = (time_t) (unix_ms / 1000);
  localtime_r (&now, &tm);
  if (!is_utc)
  {
    now -= tm.tm_gmtoff;
    localtime_r (&now, &tm);
  }
  return ((double) tm.tm_gmtoff) * 1000;
} /* jerry_port_get_local_time_zone_adjustment */

Native pointers

The assignment of native pointers (previously called handles) have been changed since v1.0. In the previous version only one native pointer could be assigned to a jerry_value_t. Now it is allowed to register multiple native infos, which can be accessed with the corresponding jerry_object_native_info_t. The old functions were removed and replaced by new ones.

• jerry_object_free_callback_t callback type is replaced by jerry_object_native_info_t
• jerry_get_object_native_handle is replaced by jerry_get_object_native_pointer
• jerry_set_object_native_handle is replaced by jerry_set_object_native_pointer

Before

struct
{
  int data;
} my_info;

static void
handler_construct_freecb (uintptr_t native_p)
{
  // Invoked when the JS object is released and the
  // native data should be freed.

  struct my_info *info = (struct my_info *) native_p;
  free (info);
}

void
demo (void)
{
  jerry_value_t this_val;
  // create or acquire this_val
  // ...

  struct my_info *info = (struct my_info *) malloc (sizeof (struct my_info));
  info->data = 11;

  // setting the native handle
  jerry_set_object_native_handle (this_val,
                                  (uintptr_t) info,
                                  handler_construct_freecb);
  // ...
  // reading back the native handle
  uintptr_t ptr = (uintptr_t) NULL;
  bool is_ok = jerry_get_object_native_handle (this_val, &ptr);
  if (is_ok)
  {
    struct my_info *obj_info = (struct my_info *) ptr;
    // use "obj_info"
  }
}

After

struct
{
  int data;
} my_info;

static void
handler_construct_freecb (void *native_p)
{
  // Invoked when the JS object is released and the
  // native data should be freed.

  struct my_info *info = (struct my_info *) native_p;
  free (info);
}

static const jerry_object_native_info_t my_info_type_info =
{
  .free_cb = handler_construct_freecb
};

void
demo (void)
{
  jerry_value_t this_val;
  // create or acquire this_val
  // ...

  struct my_info *info = (struct my_info *) malloc (sizeof (struct my_info));
  info->data = 11;

  // setting the native handle
  jerry_set_object_native_pointer (this_val,
                                   info,
                                   &my_info_type_info);
  // ...
  // reading back the native handle pointed by the "my_info_type_info" variable
  void *ptr = NULL;
  bool has_p = jerry_get_object_native_pointer (this_val, &ptr, &my_info_type_info);
  if (has_p)
  {
    struct my_info *obj_info = (struct my_info *) ptr;
    // use "obj_info"
  }
}

New API functions

In this section the new API functions are listed.

Built-in objects

ArrayBuffer

• jerry_create_arraybuffer
• jerry_create_arraybuffer_external
• jerry_get_arraybuffer_pointer

DataView

• jerry_create_dataview
• jerry_value_is_dataview
• jerry_get_dataview_buffer

JSON

• jerry_json_parse
• jerry_json_stringify

Number

• jerry_create_number_infinity
• jerry_create_number_nan

Promise

• jerry_run_all_enqueued_jobs
• jerry_create_promise
• jerry_resolve_or_reject_promise
• jerry_value_is_promise

RegExp

• jerry_create_regexp
• jerry_create_regexp_sz

String

• jerry_substring_to_utf8_char_buffer
• jerry_get_utf8_string_size
• jerry_get_utf8_string_length
• jerry_create_string_from_utf8
• jerry_create_string_sz_from_utf8

Symbol

• jerry_create_symbol
• jerry_get_symbol_descriptive_string
• jerry_value_is_symbol

TypedArray

• jerry_create_typedarray
• jerry_create_typedarray_for_arraybuffer
• jerry_create_typedarray_for_arraybuffer_sz
• jerry_get_typedarray_type
• jerry_get_typedarray_length
• jerry_get_typedarray_buffer
• jerry_value_is_typedarray

Instances and memory management

JerryScript instances

• jerry_create_context
• jerry_get_context_data

Memory management

• jerry_heap_alloc
• jerry_heap_free

Operations with JavaScript values

Binary operations

• jerry_binary_operation

Error manipulating

• jerry_get_error_type
• jerry_get_backtrace

Native pointers

• jerry_delete_object_native_pointer
• jerry_objects_foreach_by_native_info

Property

• jerry_delete_property_by_index
• jerry_objects_foreach

Debugger

• jerry_debugger_is_connected
• jerry_debugger_stop
• jerry_debugger_continue
• jerry_debugger_stop_at_breakpoint
• jerry_debugger_wait_for_client_source
• jerry_debugger_send_output
• jerry_debugger_send_log

Other

• jerry_is_feature_enabled
• jerry_parse_and_save_literals
• jerry_set_vm_exec_stop_callback

Port API functions

• jerry_port_normalize_path
• jerry_port_read_source
• jerry_port_release_source
• jerry_port_print_char
• jerry_port_get_current_context
• jerry_port_fatal
• jerry_port_sleep
• jerry_port_print_byte

Migrating from 2.x to 3.x

The most significant change in JerryScript 3.0 was the API rework. Most of the API functions had been renamed in this version. There are notes for every such function in the API Reference to help you to migrate from an older version. For example:

Renamed in version 3.0, it was previously known as jerry_get_global_object in earlier versions.