1# Configuration 2 3JerryScript 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. 4A 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. 5This 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. 6 7 8### All-in-one build 9 10Enables the All-in-one build process, which aggregates the contents of each source file, and uses this combined file to compile the JerryScript library. 11This process can provide comparable results to link time optimization, and can be useful when LTO is not available otherwise. 12 13| Options | | 14|---------|----------------------------------------------| 15| C: | `<none>` | 16| CMake: | `-DENABLE_ALL_IN_ONE=ON/OFF` | 17| Python: | `--all-in-one=ON/OFF` | 18 19### Jerry debugger 20 21Enables 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). 22The debugger is disabled by default. 23 24| Options | | 25|---------|----------------------------------------------| 26| C: | `-DJERRY_DEBUGGER=0/1` | 27| CMake: | `-DJERRY_DEBUGGER=ON/OFF` | 28| Python: | `--jerry-debugger=ON/OFF` | 29 30### Line information 31 32By 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, 33that can be used by the debugger to identify the currently executed source context. See [Debugger](07.DEBUGGER.md). 34 35| Options | | 36|---------|----------------------------------------------| 37| C: | `-DJERRY_LINE_INFO=0/1` | 38| CMake: | `-DJERRY_LINE_INFO=ON/OFF` | 39| Python: | `--line-info=ON/OFF` | 40 41### Profiles 42 43This 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. 44The `path` value for CMake and Python arguments should be a file path to the profile file, or one of `es2015-subset`, `es5.1`, or `minimal`, which are the pre-defined profiles. 45To 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). 46 47| Options | | 48|---------|----------------------------------------------| 49| C: | `<see description>` | 50| CMake: | `-DJERRY_PROFILE="path"` | 51| Python: | `--profile="path"` | 52 53### External context 54 55Enables external context support in the engine. By default, JerryScript uses a statically allocated context to store the current state of the engine internals. 56When 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. 57 58| Options | | 59|---------|----------------------------------------------| 60| C: | `-DJERRY_EXTERNAL_CONTEXT=0/1` | 61| CMake: | `-DJERRY_EXTERNAL_CONTEXT=ON/OFF` | 62| Python: | `--external-context=ON/OFF` | 63 64### Snapshot execution 65 66This option can be used to enable snapshot execution in the engine. 67This option is disabled by default. 68 69| Options | | 70|---------|----------------------------------------------| 71| C: | `-DJERRY_SNAPSHOT_EXEC=0/1` | 72| CMake: | `-DJERRY_SNAPSHOT_EXEC=ON/OFF` | 73| Python: | `--snapshot-exec=ON/OFF` | 74 75### Snapshot saving 76 77This option can be used to enable snapshot saving in the engine. 78This option is disabled by default. 79 80| Options | | 81|---------|----------------------------------------------| 82| C: | `-DJERRY_SNAPSHOT_SAVE=0/1` | 83| CMake: | `-DJERRY_SNAPSHOT_SAVE=ON/OFF` | 84| Python: | `--snapshot-save=ON/OFF` | 85 86### Jerry parser 87 88This 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). 89This option can be useful in combination with the snapshot feature. The parser is enabled by default. 90 91| Options | | 92|---------|----------------------------------------------| 93| C: | `-DJERRY_PARSER=0/1` | 94| CMake: | `-DJERRY_PARSER=ON/OFF` | 95| Python: | `--js-parser=ON/OFF` | 96 97### Dump bytecode 98 99This option can be used to display created bytecode in a human readable format. See [Internals](04.INTERNALS.md#byte-code) for more details. 100This option is disabled by default. 101 102| Options | | 103|---------|----------------------------------------------| 104| C: | `-DJERRY_PARSER_DUMP_BYTE_CODE=0/1` | 105| CMake: | `-DJERRY_PARSER_DUMP_BYTE_CODE=ON/OFF` | 106| Python: | `--show-opcodes=ON/OFF` | 107 108### Dump RegExp bytecode 109 110This 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. 111This option is disabled by default. 112 113| Options | | 114|---------|----------------------------------------------| 115| C: | `-DJERRY_REGEXP_DUMP_BYTE_CODE=0/1` | 116| CMake: | `-DJERRY_REGEXP_DUMP_BYTE_CODE=ON/OFF` | 117| Python: | `--show-regexp-opcodes=ON/OFF` | 118 119### Strict RegExp 120 121This 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. 122When 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. 123This option is disabled by default. 124 125| Options | | 126|---------|----------------------------------------------| 127| C: | `-DJERRY_REGEXP_STRICT_MODE=0/1` | 128| CMake: | `-DJERRY_REGEXP_STRICT_MODE=ON/OFF` | 129| Python: | `--regexp-strict-mode=ON/OFF` | 130 131### Error messages 132 133Enables error messages for thrown Error objects. By default, error messages are omitted to reduce memory usage. 134Enabling 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. 135 136| Options | | 137|---------|----------------------------------------------| 138| C: | `-DJERRY_ERROR_MESSAGES=0/1` | 139| CMake: | `--DJERRY_ERROR_MESSAGES=ON/OFF` | 140| Python: | `--error-messages=ON/OFF` | 141 142### Logging 143 144This 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. 145This feature is disabled by default. 146 147| Options | | 148|---------|----------------------------------------------| 149| C: | `-DJERRY_LOGGING=0/1` | 150| CMake: | `-DJERRY_LOGGING=ON/OFF` | 151| Python: | `--logging=ON/OFF` | 152 153### LCache 154 155This option enables the LCache, allowing faster access to object properties. The LCache usases a statically allocated hash-map, which increases memory consumption. 156See [Internals](04.INTERNALS.md#lcache) for further details. 157This option is enabled by default. 158 159| Options | | 160|---------|----------------------------------------------| 161| C: | `-DJERRY_LCACHE=0/1` | 162| CMake: | `<none>` | 163| Python: | `<none>` | 164 165### Property hashmaps 166 167This option enables the creation of hashmaps for object properties, which allows faster property access, at the cost of increased memory consumption. 168See [Internals](04.INTERNALS.md#property-hashmap) for further details. 169This option is enabled by default. 170 171| Options | | 172|---------|----------------------------------------------| 173| C: | `-DJERRY_PROPRETY_HASHMAP=0/1` | 174| CMake: | `<none>` | 175| Python: | `<none>` | 176 177### Memory statistics 178 179This 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. 180The feature can create a significant performance overhead, and should only be used for measurement purposes. This option is disabled by default. 181 182| Options | | 183|---------|----------------------------------------------| 184| C: | `-DJERRY_MEM_STATS=0/1` | 185| CMake: | `-DJERRY_MEM_STATS=ON/OFF` | 186| Python: | `--mem-stats=ON/OFF` | 187 188### Heap size 189 190This 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. 191The default value is 512. 192 193| Options | | 194|---------|----------------------------------------------| 195| C: | `-DJERRY_GLOBAL_HEAP_SIZE=(int)` | 196| CMake: | `--DJERRY_GLOBAL_HEAP_SIZE=(int)` | 197| Python: | `--mem-heap=(int)` | 198 199### Garbage collection limit 200 201This option can be used to adjust the maximum allowed heap usage increase until triggering the next garbage collection, in bytes. 202When the total allocated memory size reaches the current gc limit, garbage collection will be triggered to try and reduce clutter from unreachable objects. 203If 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. 204Similarly, when the total allocated memory goes well below the current gc limit, the limit is reduced by this amount. 205The default value is 1/32 of the total heap size, but not greater than 8192 bytes. 206A value of 0 will use the default value. 207 208| Options | | 209|---------|----------------------------------------------| 210| C: | `-DJERRY_GC_LIMIT=(int)` | 211| CMake: | `-DJERRY_GC_LIMIT=(int)` | 212| Python: | `--gc-limit=(int)` | 213 214### GC mark recursion limit 215 216This 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. 217A value of 0 will prevent any recursive GC calls. 218 219| Options | | 220|---------|---------------------------------------------------| 221| C: | `-DJERRY_GC_MARK_LIMIT=(int)` | 222| CMake: | `-DJERRY_GC_MARK_LIMIT=(int)` | 223| Python: | `--gc-mark-limit=(int)` | 224 225### Stack limit 226 227This 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. 228The default value is 0 (unlimited). 229 230| Options | | 231|---------|----------------------------------------------| 232| C: | `-DJERRY_STACK_LIMIT=(int)` | 233| CMake: | `-DJERRY_STACK_LIMIT=(int)` | 234| Python: | `--stack-limit=(int)` | 235 236### 32-bit compressed pointers 237 238Enables 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. 239This option must be enabled when using the system allocator. 240 241| Options | | 242|---------|----------------------------------------------| 243| C: | `-DJERRY_CPOINTER_32_BIT=0/1` | 244| CMake: | `-DJERRY_CPOINTER_32_BIT=ON/OFF` | 245| Python: | `--cpointer-32bit=ON/OFF` | 246 247### System allocator 248 249This 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. 250This option is disabled by default. 251 252| Options | | 253|---------|----------------------------------------------| 254| C: | `-DJERRY_SYSTEM_ALLOCATOR=0/1` | 255| CMake: | `-DJERRY_SYSTEM_ALLOCATOR=ON/OFF` | 256| Python: | `--system-allocator=ON/OFF` | 257 258### Valgrind support 259 260This 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. 261This option is disabled by default. 262 263| Options | | 264|---------|----------------------------------------------| 265| C: | `-DJERRY_VALGRIND=0/1` | 266| CMake: | `-DJERRY_VALGRIND=ON/OFF` | 267| Python: | `--valgrind=ON/OFF` | 268 269### Memory stress test 270 271This option can be used to stress test memory management, by running garbage collection before every allocation attempt. 272This option is disabled by default. 273 274| Options | | 275|---------|----------------------------------------------| 276| C: | `-DJERRY_MEM_GC_BEFORE_EACH_ALLOC=0/1` | 277| CMake: | `-DJERRY_MEM_GC_BEFORE_EACH_ALLOC=ON/OFF` | 278| Python: | `--mem-stress-test=ON/OFF` | 279 280 281# Single source build mode 282 283There is a special mode to use/"build" JerryScript. That is generating a single C file which can be 284included into projects quickly. To achive this the following command can be executed to create 285a set of files into the `gen_src` directory (Note that the command is executed in the jerryscript root directory 286but can be adapted to run outside of the project root dir): 287 288```sh 289$ python tools/srcgenerator.py --output-dir gen_src --jerry-core --jerry-port-default --jerry-libm 290``` 291 292The command creates the following files in the `gen_src` dir: 293 294* `jerryscript.c` 295* `jerryscript.h` 296* `jerryscript-config.h` 297* `jerryscript-port-default.c` 298* `jerryscript-port-default.h` 299* `jerryscript-libm.c` 300* `math.h` 301 302**Important**: the `jerryscript-config.h` contains the configurations mentioned above and 303should be adapted to the required use-case. See the file contents for more details and for the 304default configuration. (Note: This config file is created from the the `jerry-core/config.h` file.) 305 306These files can be directly compiled with an application using the JerryScript API. 307For example with the following command: 308 309```sh 310$ gcc -Wall -o demo_app demo_app.c gen_src/jerryscript.c gen_src/jerryscript-port-default.c jerryscript-libm.c -Igen_src/ 311``` 312 313Please note that the headers must be available on the include path. 314 315In addition there is a `-DENABLE_ALL_IN_ONE_SOURCE=ON` CMake option to use this kind of sources during the build. 316 317# Target specific information 318 319## x86 with GCC 320 321When building for Intel 32 bit architecture it is possible that GCC uses conservative options, thus assuming the most 322basic floating-point support (that is it does not generate SSE or others instructions). 323However this could lead to loss off precision and/or different results than what is required by the JavaScript standard 324in regards of floating-point values and arithmetic. 325 326To resolve this precision problem it is advised to use at least SSE2. 327To do this with GCC please provide the `-mfpmath=sse -msse2` options during build. 328 329These options can also be specified via the `build.py` script: 330 331```sh 332$ ./tools/build.py --compile-flag=-mfpmath=sse --compile-flag=-msse2 --compile-flag=-m32 333``` 334