JerryScript provides a large number of configuration options which can be used to enable or disable specific features, allowing users to fine tune the engine to best suit their needs.
A configuration option's value can be changed either by providing specific C preprocessor definitions, by adding CMake defininitions, or by using the arguments of the tools/build.py script.
This document lists the available configuration options, shows the configuration name for C, CMake, and python, and provides a brief description that explains the effect of the options.
Enables the amalgamated build process, which aggregates the contents of each source file per library (i.e., JerryScript's core, port, and math libraries), and uses these combined files to compile the project. This process can provide comparable results to link-time optimization, and can be useful when LTO is not available otherwise.
| Options | |
|---|---|
| C: | <none> |
| CMake: | -DENABLE_AMALGAM=ON/OFF |
| Python: | --amalgam=ON/OFF |
See also: Amalgamated sources
Enables debugger support in the engine, which can be used to debug running JavaScript code. For more information on using the debugger see Debugger. The debugger is disabled by default.
| Options | |
|---|---|
| C: | -DJERRY_DEBUGGER=0/1 |
| CMake: | -DJERRY_DEBUGGER=ON/OFF |
| Python: | --jerry-debugger=ON/OFF |
By default, all source code information is discarded after parsing is complete. This option can be used to augment the created bytecode to provide line information during runtime, that can be used by the debugger to identify the currently executed source context. See Debugger.
| Options | |
|---|---|
| C: | -DJERRY_LINE_INFO=0/1 |
| CMake: | -DJERRY_LINE_INFO=ON/OFF |
| Python: | --line-info=ON/OFF |
This option can be used to enable/disable available JavaScript language features by providing profile files. Profile files contain a list of C definitions that configure each individual feature.
The path value for CMake and Python arguments should be a file path to the profile file, or one of es.next, es5.1, or minimal, which are the pre-defined profiles.
To see how a profile file should be created, or what configuration options are available in C, see the profile README.
| Options | |
|---|---|
| C: | <see description> |
| CMake: | -DJERRY_PROFILE="path" |
| Python: | --profile="path" |
Enables Promise event notification support. This feature allows setting a user callback, which is called when certain Promise related events occur such as creating a new Promise, resolving a Promise with a value, etc.
| Options | |
|---|---|
| C: | -DJERRY_PROMISE_CALLBACK=0/1 |
| CMake: | -DJERRY_PROMISE_CALLBACK=ON/OFF |
| Python: | --promise-callback=ON/OFF |
Enables external context support in the engine. By default, JerryScript uses a statically allocated context to store the current state of the engine internals. When this option is enabled, an externally allocated memory region can be provided through the port API to the engine, to be used as the context.
| Options | |
|---|---|
| C: | -DJERRY_EXTERNAL_CONTEXT=0/1 |
| CMake: | -DJERRY_EXTERNAL_CONTEXT=ON/OFF |
| Python: | --external-context=ON/OFF |
This option can be used to enable snapshot execution in the engine. This option is disabled by default.
| Options | |
|---|---|
| C: | -DJERRY_SNAPSHOT_EXEC=0/1 |
| CMake: | -DJERRY_SNAPSHOT_EXEC=ON/OFF |
| Python: | --snapshot-exec=ON/OFF |
This option can be used to enable snapshot saving in the engine. This option is disabled by default.
| Options | |
|---|---|
| C: | -DJERRY_SNAPSHOT_SAVE=0/1 |
| CMake: | -DJERRY_SNAPSHOT_SAVE=ON/OFF |
| Python: | --snapshot-save=ON/OFF |
This option can be used to enable or disable the parser. When the parser is disabled all features that depend on source parsing are unavailable (eg. jerry_parse, eval, Function constructor).
This option can be useful in combination with the snapshot feature. The parser is enabled by default.
| Options | |
|---|---|
| C: | -DJERRY_PARSER=0/1 |
| CMake: | -DJERRY_PARSER=ON/OFF |
| Python: | --js-parser=ON/OFF |
This option can be used to display created bytecode in a human readable format. See Internals for more details. This option is disabled by default.
| Options | |
|---|---|
| C: | -DJERRY_PARSER_DUMP_BYTE_CODE=0/1 |
| CMake: | -DJERRY_PARSER_DUMP_BYTE_CODE=ON/OFF |
| Python: | --show-opcodes=ON/OFF |
This option can be used to display created RegExp bytecode in a human readable format. The RegExp bytecode is different from the bytecode used by the virtual machine. This option is disabled by default.
| Options | |
|---|---|
| C: | -DJERRY_REGEXP_DUMP_BYTE_CODE=0/1 |
| CMake: | -DJERRY_REGEXP_DUMP_BYTE_CODE=ON/OFF |
| Python: | --show-regexp-opcodes=ON/OFF |
This option can be used to enable strict RegExp mode. The standard RegExp syntax is a lot stricter than what is common in current JavaScript implementations. When enabled, this flag disables all of the non-standard, quality-of-life RegExp features, that are implemented to provide compatibility with other commonly used engines. This option is disabled by default.
| Options | |
|---|---|
| C: | -DJERRY_REGEXP_STRICT_MODE=0/1 |
| CMake: | -DJERRY_REGEXP_STRICT_MODE=ON/OFF |
| Python: | --regexp-strict-mode=ON/OFF |
Enables error messages for thrown Error objects. By default, error messages are omitted to reduce memory usage. Enabling this feature provides detailed error messages where available, like line information for Syntax errors, variable names for Reference errors, Type/Range error messages for built-in routines, etc.
| Options | |
|---|---|
| C: | -DJERRY_ERROR_MESSAGES=0/1 |
| CMake: | -DJERRY_ERROR_MESSAGES=ON/OFF |
| Python: | --error-messages=ON/OFF |
This option can be used to enable log messages during runtime. When enabled the engine will use the jerry_port_log port API function to print relevant log messages.
This feature is disabled by default.
| Options | |
|---|---|
| C: | -DJERRY_LOGGING=0/1 |
| CMake: | -DJERRY_LOGGING=ON/OFF |
| Python: | --logging=ON/OFF |
This option enables the LCache, allowing faster access to object properties. The LCache uses a statically allocated hash-map, which increases memory consumption. See Internals for further details. This option is enabled by default.
| Options | |
|---|---|
| C: | -DJERRY_LCACHE=0/1 |
| CMake: | <none> |
| Python: | <none> |
This option enables the creation of hashmaps for object properties, which allows faster property access, at the cost of increased memory consumption. See Internals for further details. This option is enabled by default.
| Options | |
|---|---|
| C: | -DJERRY_PROPRETY_HASHMAP=0/1 |
| CMake: | <none> |
| Python: | <none> |
This option can be used to provide memory usage statistics either upon engine termination, or during runtime using the jerry_get_memory_stats jerry API function.
The feature can create a significant performance overhead, and should only be used for measurement purposes. This option is disabled by default.
| Options | |
|---|---|
| C: | -DJERRY_MEM_STATS=0/1 |
| CMake: | -DJERRY_MEM_STATS=ON/OFF |
| Python: | --mem-stats=ON/OFF |
This option can be used to adjust the size of the internal heap, represented in kilobytes. The provided value should be an integer. Values larger than 512 require 32-bit compressed pointers to be enabled. The default value is 512.
| Options | |
|---|---|
| C: | -DJERRY_GLOBAL_HEAP_SIZE=(int) |
| CMake: | -DJERRY_GLOBAL_HEAP_SIZE=(int) |
| Python: | --mem-heap=(int) |
This option can be used to adjust the maximum allowed heap usage increase until triggering the next garbage collection, in bytes. When the total allocated memory size reaches the current gc limit, garbage collection will be triggered to try and reduce clutter from unreachable objects. If the total allocated memory can't be reduced below the current limit, then the limit will be increased by the amount specified via this option. Similarly, when the total allocated memory goes well below the current gc limit, the limit is reduced by this amount. The default value is 1/32 of the total heap size, but not greater than 8192 bytes. A value of 0 will use the default value.
| Options | |
|---|---|
| C: | -DJERRY_GC_LIMIT=(int) |
| CMake: | -DJERRY_GC_LIMIT=(int) |
| Python: | --gc-limit=(int) |
This option can be used to adjust the maximum recursion depth during the GC mark phase. The provided value should be an integer, which represents the allowed number of recursive calls. Increasing the depth of the recursion reduces the time of GC cycles, however increases stack usage. A value of 0 will prevent any recursive GC calls.
| Options | |
|---|---|
| C: | -DJERRY_GC_MARK_LIMIT=(int) |
| CMake: | -DJERRY_GC_MARK_LIMIT=(int) |
| Python: | --gc-mark-limit=(int) |
This option can be used to cap the stack usage of the engine, and prevent stack overflows due to recursion. The provided value should be an integer, which represents the allowed stack usage in kilobytes. The default value is 0 (unlimited).
| Options | |
|---|---|
| C: | -DJERRY_STACK_LIMIT=(int) |
| CMake: | -DJERRY_STACK_LIMIT=(int) |
| Python: | --stack-limit=(int) |
Enables 32-bit pointers instead of the default 16-bit compressed pointers. This allows the engine to use a much larger heap, but also comes with slightly increased memory usage, as objects can't be packed as tightly. This option must be enabled when using the system allocator.
| Options | |
|---|---|
| C: | -DJERRY_CPOINTER_32_BIT=0/1 |
| CMake: | -DJERRY_CPOINTER_32_BIT=ON/OFF |
| Python: | --cpointer-32bit=ON/OFF |
This option enables the use of malloc/free instead of the internal JerryScript allocator. This feature requires 32-bit compressed pointers, and is unsupported on 64-bit architectures. This option is disabled by default.
| Options | |
|---|---|
| C: | -DJERRY_SYSTEM_ALLOCATOR=0/1 |
| CMake: | -DJERRY_SYSTEM_ALLOCATOR=ON/OFF |
| Python: | --system-allocator=ON/OFF |
This option enables valgrind support for the internal allocator. When enabled, valgrind will be able to properly identify allocated memory regions, and report leaks or out-of-bounds memory accesses. This option is disabled by default.
| Options | |
|---|---|
| C: | -DJERRY_VALGRIND=0/1 |
| CMake: | -DJERRY_VALGRIND=ON/OFF |
| Python: | --valgrind=ON/OFF |
This option can be used to stress test memory management, by running garbage collection before every allocation attempt. This option is disabled by default.
| Options | |
|---|---|
| C: | -DJERRY_MEM_GC_BEFORE_EACH_ALLOC=0/1 |
| CMake: | -DJERRY_MEM_GC_BEFORE_EACH_ALLOC=ON/OFF |
| Python: | --mem-stress-test=ON/OFF |
The sources of JerryScript can be combined into a handful of files to allow their easy integration
in other projects. To achieve this, the following command can be executed to create a set of files
into the amalgam directory:
$ python tools/amalgam.py --output-dir amalgam --jerry-core --jerry-port-default --jerry-math(Note: In the example above, the command is executed from the project's root directory, but that is not mandatory.)
The command creates the following files in the amalgam dir:
jerryscript.cjerryscript.hjerryscript-config.hjerryscript-port-default.cjerryscript-port-default.hjerryscript-math.cmath.h
Important: the jerryscript-config.h contains the configurations mentioned above and
should be adapted to the required use-case. See the file contents for more details and for the
default configuration. (Note: This config file is created from the the jerry-core/config.h file.)
These files can be directly compiled with an application using the JerryScript API. E.g., using a command similar to the one below:
$ gcc -Wall -o demo_app demo_app.c amalgam/jerryscript.c amalgam/jerryscript-port-default.c amalgam/jerryscript-math.c -Iamalgam/(Note: The headers must be available on the include path.)
This approach is also under the hood of the amalgamated build process.
When building for Intel 32 bit architecture it is possible that GCC uses conservative options, thus assuming the most basic floating-point support (that is it does not generate SSE or others instructions). However this could lead to loss off precision and/or different results than what is required by the JavaScript standard in regards of floating-point values and arithmetic.
To resolve this precision problem it is advised to use at least SSE2.
To do this with GCC please provide the -mfpmath=sse -msse2 options during build.
These options can also be specified via the build.py script:
$ ./tools/build.py --compile-flag=-mfpmath=sse --compile-flag=-msse2 --compile-flag=-m32