archive-gh-me/jerryscript
1
0
Fork 0
mirror of https://github.com/jerryscript-project/jerryscript.git synced 2025-12-15 16:29:21 +00:00
Code Issues Projects Releases Wiki Activity
jerryscript/docs/01.CONFIGURATION.md
Dániel Bátyai ac1c48eeff
Update jerry-port and jerry-ext (#4907) 
Notable changes:
  - Updated and the port API interface, new functions have been added
    and some have been changed. The port library is now cleaned up to
    not have any dependency on jerry-core, as it should be. The port library
    is now strictly a collection of functions that implement
    embedding/platform specific behavior.
  - The default port implementation has been split for windows and unix.
    Implemented port functions have been categorized and reorganized,
    and marked with attribute((weak)) for better reusability.
  - External context allocation has been moved to the port API instead
    of a core API callback. The iterface has also been extended with a
    function to free the allocated context. When external context is
    enabled, jerry_init now automatically calls the port implementation
    to allocate the context and jerry_cleanup automatically calls the port
    to free the context.
  - jerry_port_log has been changed to no longer require formatting to
    be implemented by the port. The reason beind this is that it was vague what
    format specifiers were used by the engine, and in what manner. The port
    function now takes a zero-terminated string, and should only implement
    how the string should be logged.
  - Logging and log message formatting is now handled by the core jerry library
    where it can be implemented as necessary. Logging can be done through a new
    core API function, which uses the port to output the final log message.
  - Log level has been moved into jerry-core, and an API function has
    been added to set the log level. It should be the library that
    filters log messages based on the requested log level, instead of
    logging everything and requiring the user to do so.
  - Module resolving logic has been moved into jerry-core. There's no
    reason to have it in the port library and requiring embedders to
    duplicate the code. It also added an unnecessary dependency on
    jerry-core to the port. Platform specific behavior is still used through
    the port API, like resolving module specifiers, and reading source file
    contents. If necessary, the resolving logic can still be overridden as
    previously.
  - The jerry-ext library has also been cleaned up, and many utility
    functions have been added that previously were implemented in
    jerry-main. This allows easier reusability for some common operations,
    like printing unhandled exceptions or providing a repl console.
  - Debugger interaction with logged/printed messages has been fixed, so
    that it's no longer the port implementations responsibility to send
    the output to the debugger, as the port should have no notion of what a
    debugger is.  The printing and logging functions will now pass the
    result message to the debugger, if connected.
  - Cleaned up TZA handling in the date port implementation, and simplified
    the API function prototype.
  - Moved property access helper functions that use ASCII strings as
    keys from jerry-ext to the core API.

JerryScript-DCO-1.0-Signed-off-by: Dániel Bátyai dbatyai@inf.u-szeged.hu
2022-01-20 13:53:47 +01:00

349 lines
17 KiB
Markdown
Raw Blame History

# Configuration
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 definitions, 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.
### Amalgamated build
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](#amalgamated-sources)
### Jerry debugger
Enables debugger support in the engine, which can be used to debug running JavaScript code. For more information on using the debugger see [Debugger](07.DEBUGGER.md).
The debugger is disabled by default.
| Options | |
|---------|----------------------------------------------|
| C: | `-DJERRY_DEBUGGER=0/1` |
| CMake: | `-DJERRY_DEBUGGER=ON/OFF` |
| Python: | `--jerry-debugger=ON/OFF` |
### Line information
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](07.DEBUGGER.md).
| Options | |
|---------|----------------------------------------------|
| C: | `-DJERRY_LINE_INFO=0/1` |
| CMake: | `-DJERRY_LINE_INFO=ON/OFF` |
| Python: | `--line-info=ON/OFF` |
### Profiles
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](https://github.com/jerryscript-project/jerryscript/blob/master/jerry-core/profiles/README.md).
| Options | |
|---------|----------------------------------------------|
| C: | `<see description>` |
| CMake: | `-DJERRY_PROFILE="path"` |
| Python: | `--profile="path"` |
### Promise callback
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` |
### External context
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` |
### Snapshot execution
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` |
### Snapshot saving
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` |
### Jerry parser
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` |
### Dump bytecode
This option can be used to display created bytecode in a human readable format. See [Internals](04.INTERNALS.md#byte-code) 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` |
### Dump RegExp bytecode
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` |
### Strict RegExp
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` |
### Error messages
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` |
### Logging
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` |
### LCache
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](04.INTERNALS.md#lcache) for further details.
This option is enabled by default.
| Options | |
|---------|----------------------------------------------|
| C: | `-DJERRY_LCACHE=0/1` |
| CMake: | `<none>` |
| Python: | `<none>` |
### Property hashmaps
This option enables the creation of hashmaps for object properties, which allows faster property access, at the cost of increased memory consumption.
See [Internals](04.INTERNALS.md#property-hashmap) for further details.
This option is enabled by default.
| Options | |
|---------|----------------------------------------------|
| C: | `-DJERRY_PROPERTY_HASHMAP=0/1` |
| CMake: | `<none>` |
| Python: | `<none>` |
### Memory statistics
This option can be used to provide memory usage statistics either upon engine termination, or during runtime using the `jerry_heap_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` |
### Heap size
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)` |
### Garbage collection limit
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)` |
### GC mark recursion limit
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)` |
### Stack limit
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)` |
### 32-bit compressed pointers
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` |
### System allocator
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` |
### Valgrind support
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` |
### Memory stress test
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` |
# Amalgamated sources
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:
```sh
$ python tools/amalgam.py --output-dir amalgam --jerry-core --jerry-port --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.c`
* `jerryscript.h`
* `jerryscript-config.h`
* `jerryscript-port.c`
* `jerryscript-math.c`
* `math.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:
```sh
$ gcc -Wall -o demo_app demo_app.c amalgam/jerryscript.c amalgam/jerryscript-port.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](#amalgamated-build) process.
# Target specific information
## x86 with GCC
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:
```sh
$ ./tools/build.py --compile-flag=-mfpmath=sse --compile-flag=-msse2 --compile-flag=-m32
```
Reference in New Issue View Git Blame Copy Permalink