Skip to content

Commit 5d6eeba

Browse files
dbatyairerobika
dbatyai
authored and
rerobika
committed
Add documentation for configuration options (#2977)
JerryScript-DCO-1.0-Signed-off-by: Dániel Bátyai dbatyai@inf.u-szeged.hu
1 parent 4a9e185 commit 5d6eeba

File tree

3 files changed

+256
-2
lines changed

3 files changed

+256
-2
lines changed

docs/01.GETTING-STARTED.md renamed to docs/00.GETTING-STARTED.md

File renamed without changes.

‎docs/01.CONFIGURATION.md‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
# Configuration
2+
3+
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.
4+
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.
5+
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.
6+
7+
8+
### All-in-one build
9+
10+
Enables the All-in-one build process, which aggregates the contents of each source file, and uses this combined file to compile the JerryScript library.
11+
This 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+
21+
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).
22+
The 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+
32+
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,
33+
that 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+
43+
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.
44+
The `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.
45+
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).
46+
47+
| Options | |
48+
|---------|----------------------------------------------|
49+
| C: | `<see description>` |
50+
| CMake: | `-DJERRY_PROFILE="path"` |
51+
| Python: | `--profile="path"` |
52+
53+
### External context
54+
55+
Enables external context support in the engine. By default, JerryScript uses a statically allocated context to store the current state of the engine internals.
56+
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.
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+
66+
This option can be used to enable snapshot execution in the engine.
67+
This 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+
77+
This option can be used to enable snapshot saving in the engine.
78+
This 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+
88+
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).
89+
This 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+
99+
This option can be used to display created bytecode in a human readable format. See [Internals](04.INTERNALS.md#byte-code) for more details.
100+
This 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+
110+
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.
111+
This 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+
121+
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.
122+
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.
123+
This 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+
133+
Enables error messages for thrown Error objects. By default, error messages are omitted to reduce memory usage.
134+
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.
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+
144+
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.
145+
This 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+
155+
This option enables the LCache, allowing faster access to object properties. The LCache usases a statically allocated hash-map, which increases memory consumption.
156+
See [Internals](04.INTERNALS.md#lcache) for further details.
157+
This 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+
167+
This option enables the creation of hashmaps for object properties, which allows faster property access, at the cost of increased memory consumption.
168+
See [Internals](04.INTERNALS.md#property-hashmap) for further details.
169+
This 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+
179+
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.
180+
The 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+
190+
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.
191+
The default value is 512.
192+
193+
| Options | |
194+
|---------|----------------------------------------------|
195+
| C: | `-DJERRY_GLOBAL_HEAP_SIZE=(int)` |
196+
| CMake: | `--DJERRY_GLOBAL_HEAP_SIZE=(int)` |
197+
| Python: | `--heap-size=(int)` |
198+
199+
### Stack limit
200+
201+
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.
202+
The default value is 0 (unlimited).
203+
204+
| Options | |
205+
|---------|----------------------------------------------|
206+
| C: | `-DJERRY_STACK_LIMIT=(int)` |
207+
| CMake: | `-DJERRY_STACK_LIMIT=(int)` |
208+
| Python: | `--stack-limit=(int)` |
209+
210+
### 32-bit compressed pointers
211+
212+
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.
213+
This option must be enabled when using the system allocator.
214+
215+
| Options | |
216+
|---------|----------------------------------------------|
217+
| C: | `-DJERRY_CPOINTER_32_BIT=0/1` |
218+
| CMake: | `-DJERRY_CPOINTER_32_BIT=ON/OFF` |
219+
| Python: | `--cpointer-32bit=ON/OFF` |
220+
221+
### System allocator
222+
223+
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.
224+
This option is disabled by default.
225+
226+
| Options | |
227+
|---------|----------------------------------------------|
228+
| C: | `-DJERRY_SYSTEM_ALLOCATOR=0/1` |
229+
| CMake: | `-DJERRY_SYSTEM_ALLOCATOR=ON/OFF` |
230+
| Python: | `--system-allocator=ON/OFF` |
231+
232+
### Valgrind support
233+
234+
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.
235+
This option is disabled by default.
236+
237+
| Options | |
238+
|---------|----------------------------------------------|
239+
| C: | `-DJERRY_VALGRIND=0/1` |
240+
| CMake: | `-DJERRY_VALGRIND=ON/OFF` |
241+
| Python: | `--valgrind=ON/OFF` |
242+
243+
### Memory stress test
244+
245+
This option can be used to stress test memory management, by running garbage collection before every allocation attempt.
246+
This option is disabled by default.
247+
248+
| Options | |
249+
|---------|----------------------------------------------|
250+
| C: | `-DJERRY_MEM_GC_BEFORE_EACH_ALLOC=0/1` |
251+
| CMake: | `-DJERRY_MEM_GC_BEFORE_EACH_ALLOC=ON/OFF` |
252+
| Python: | `--mem-stress-test=ON/OFF` |

‎tools/update-webpage.sh‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,8 @@ fi
2222
gh_pages_dir=$1
2323
docs_dir=`dirname $(readlink -f $0)`"/../docs"
2424

25-
GETTING_STARTED_MD="01.GETTING-STARTED.md"
25+
GETTING_STARTED_MD="00.GETTING-STARTED.md"
26+
CONFIGURATION_MD="01.CONFIGURATION.md"
2627
API_REFERENCE_MD="02.API-REFERENCE.md"
2728
API_EXAMPLES_MD="03.API-EXAMPLE.md"
2829
INTERNALS_MD="04.INTERNALS.md"
@@ -41,6 +42,7 @@ MODULE_SYSTEM_MD="15.MODULE-SYSTEM.md"
4142
declare -A titles
4243

4344
titles[$GETTING_STARTED_MD]="Getting Started"
45+
titles[$CONFIGURATION_MD]="Configuration"
4446
titles[$API_REFERENCE_MD]="API Reference"
4547
titles[$API_EXAMPLES_MD]="API Examples"
4648
titles[$INTERNALS_MD]="Internals"
@@ -63,7 +65,7 @@ for docfile in $docs_dir/*.md; do
6365
missing_title=`echo $permalink | tr '-' ' '`
6466

6567
# the first three documents belong to the navigation bar
66-
category=$([[ $docfile_base =~ ^0[1-3] ]] && echo "navbar" || echo "documents")
68+
category=$([[ $docfile_base =~ ^0[0-3] ]] && echo "navbar" || echo "documents")
6769

6870
# generate appropriate header for each *.md
6971
echo "---" > $gh_pages_dir/$docfile_base

0 commit comments

Comments
 (0)