Skip to content

Commit dbc0960

Browse files
author
Istvan Miklos
committed
[WIP] Migration Guide
In this guide we collected informations for you to update the JerryScript from 1.0 to 2.0. JerryScript-DCO-1.0-Signed-off-by: Istvan Miklos [email protected]
1 parent 0c6b5ea commit dbc0960

File tree

1 file changed

+372
-0
lines changed

1 file changed

+372
-0
lines changed

‎docs/00.MIGRATION-GUIDE.md

Lines changed: 372 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,372 @@
1+
# Migration guide
2+
3+
In this guide we gather all the information for you to update the JerryScript from 1.0 to 2.0.
4+
5+
We have changed API functions and removed some legacy macros/headers.
6+
Changes are all documented below you can see them in the before and after code snippets.
7+
If you are looking for something that has been deleted we have a list further down.
8+
As for the new functions we have a list of them, for more information please checkout the [API reference](02.API-REFERENCE.md).
9+
10+
## Error manipulating functions
11+
12+
These functions have been reworked in most cases. Every function got a second argument which can call a `jerry_release_value` for the input API value.
13+
14+
### jerry_value_set_abort_flag
15+
16+
This function was replaced with [`jerry_create_abort_from_value`](02.API-REFERENCE.md#jerry_create_abort_from_value).
17+
18+
**Before**
19+
20+
```c
21+
{
22+
jerry_value_t value;
23+
... // create or acquire value
24+
25+
jerry_value_set_abort_flag (&value);
26+
jerry_release_value (value);
27+
}
28+
```
29+
30+
**After**
31+
32+
```c
33+
{
34+
jerry_value_t value;
35+
... // create or acquire value
36+
37+
jerry_value_t abort = jerry_create_abort_from_value (value, true);
38+
// using the 'value' variable after release is invalid
39+
40+
jerry_release_value (abort);
41+
}
42+
```
43+
44+
- OR
45+
46+
```c
47+
{
48+
jerry_value_t value;
49+
... // create or acquire value
50+
51+
jerry_value_t abort = jerry_create_abort_from_value (value, false);
52+
// both 'abort' and 'value' can be used and must be released when they are no longer needed
53+
54+
jerry_release_value (abort);
55+
jerry_release_value (value);
56+
}
57+
```
58+
59+
### jerry_value_has_abort_flag
60+
61+
This function was renamed to [`jerry_value_is_abort`](02.API-REFERENCE.md#jerry_value_is_abort).
62+
63+
**Before**
64+
65+
```c
66+
{
67+
jerry_value_t value;
68+
... // create or acquire value
69+
70+
jerry_value_set_abort_flag (&value);
71+
if (jerry_value_has_abort_flag (value))
72+
{
73+
...
74+
}
75+
jerry_release_value (value);
76+
}
77+
```
78+
79+
**After**
80+
81+
```c
82+
{
83+
jerry_value_t value;
84+
... // create or acquire value
85+
86+
jerry_value_t abort = jerry_create_abort_from_value (value, true);
87+
if (jerry_value_is_abort (abort))
88+
{
89+
...
90+
}
91+
jerry_release_value (abort);
92+
}
93+
```
94+
95+
### jerry_value_set_error_flag
96+
97+
This function was replaced with [`jerry_create_error_from_value`](02.API-REFERENCE.md#jerry_create_error_from_value).
98+
99+
**Before**
100+
101+
```c
102+
{
103+
jerry_value_t value;
104+
... // create or acquire value
105+
106+
jerry_value_set_error_flag (&value);
107+
jerry_release_value (value);
108+
}
109+
```
110+
111+
**After**
112+
113+
```c
114+
{
115+
jerry_value_t value;
116+
... // create or acquire value
117+
118+
jerry_value_t error = jerry_create_error_from_value (value, true);
119+
// using the 'value' variable after release is invalid
120+
121+
jerry_release_value (error);
122+
}
123+
```
124+
125+
- OR
126+
127+
```c
128+
{
129+
jerry_value_t value;
130+
... // create or acquire value
131+
132+
jerry_value_t error = jerry_create_error_from_value (value, false);
133+
// both 'error' and 'value' can be used and must be released when they are no longer needed
134+
135+
jerry_release_value (error);
136+
jerry_release_value (value);
137+
}
138+
```
139+
140+
### jerry_value_has_error_flag
141+
142+
This function was renamed to [`jerry_value_is_error`](02.API-REFERENCE.md#jerry_value_is_error).
143+
144+
**Before**
145+
146+
```c
147+
{
148+
jerry_value_t value;
149+
... // create or acquire value
150+
151+
jerry_value_set_error_flag (&value);
152+
if (jerry_value_has_error_flag (value))
153+
{
154+
...
155+
}
156+
jerry_release_value (value);
157+
}
158+
```
159+
160+
**After**
161+
162+
```c
163+
{
164+
jerry_value_t value;
165+
... // create or acquire value
166+
167+
jerry_value_t error = jerry_create_error_from_value (value, true);
168+
if (jerry_value_is_error (error))
169+
{
170+
...
171+
}
172+
jerry_release_value (error);
173+
}
174+
```
175+
176+
### jerry_value_clear_error_flag AND jerry_get_value_without_error_flag
177+
178+
These functions was merged into [`jerry_get_value_from_error`](02.API-REFERENCE.md#jerry_get_value_from_error).
179+
180+
**Before**
181+
182+
```c
183+
{
184+
jerry_value_t value;
185+
... // create or acquire value
186+
187+
jerry_value_set_error_flag (&value);
188+
jerry_value_clear_error_flag (&value);
189+
// or
190+
jerry_value_t real_value = jerry_get_value_without_error_flag (value);
191+
192+
jerry_release_value (value);
193+
jerry_release_value (real_value);
194+
}
195+
```
196+
197+
**After**
198+
199+
```c
200+
{
201+
jerry_value_t value;
202+
... // create or acquire value
203+
204+
jerry_value_t error = jerry_create_error_from_value (value, true);
205+
jerry_value_t real_value = jerry_get_value_from_error (error, true);
206+
207+
jerry_release_value (real_value);
208+
}
209+
```
210+
211+
## Snapshot generating API
212+
213+
### jerry_parse_and_save_snapshot
214+
215+
This function was replaced with [`jerry_generate_snapshot`](02.API-REFERENCE.md#jerry_generate_snapshot).
216+
217+
**Before**
218+
219+
```c
220+
{
221+
static uint32_t global_mode_snapshot_buffer[256];
222+
const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
223+
224+
size_t global_mode_snapshot_size =
225+
jerry_parse_and_save_snapshot (code_to_snapshot_p,
226+
strlen ((const char *) code_to_snapshot_p),
227+
true,
228+
false,
229+
global_mode_snapshot_buffer,
230+
sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
231+
jerry_cleanup ();
232+
}
233+
```
234+
235+
**After**
236+
237+
```c
238+
{
239+
static uint32_t global_mode_snapshot_buffer[256];
240+
const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
241+
242+
jerry_value_t generate_result;
243+
generate_result = jerry_generate_snapshot (NULL,
244+
0,
245+
code_to_snapshot_p,
246+
strlen ((const char *) code_to_snapshot_p),
247+
global_mode_snapshot_buffer,
248+
sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
249+
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
250+
jerry_release_value (generate_result);
251+
jerry_cleanup ();
252+
}
253+
```
254+
255+
### jerry_parse_and_save_function_snapshot
256+
257+
This function was replaced with [`jerry_generate_function_snapshot`](02.API-REFERENCE.md#jerry_parse_and_save_function_snapshot).
258+
259+
**Before**
260+
261+
```c
262+
{
263+
const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
264+
const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";
265+
266+
size_t func_snapshot_size =
267+
jerry_parse_and_save_function_snapshot (src_p,
268+
strlen ((const char *) src_p),
269+
args_p,
270+
strlen ((const char *) args_p),
271+
false,
272+
func_snapshot_buffer,
273+
sizeof (func_snapshot_buffer) / sizeof (uint32_t));
274+
275+
jerry_cleanup ();
276+
}
277+
```
278+
279+
**After**
280+
281+
```c
282+
{
283+
const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
284+
const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";
285+
286+
jerry_value_t generate_result;
287+
generate_result = jerry_generate_function_snapshot (NULL,
288+
0,
289+
src_p,
290+
strlen ((const char *) src_p),
291+
args_p,
292+
strlen ((const char *) args_p),
293+
0,
294+
func_snapshot_buffer,
295+
sizeof (func_snapshot_buffer) / sizeof (uint32_t));
296+
297+
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
298+
jerry_release_value (generate_result)
299+
jerry_cleanup ();
300+
}
301+
```
302+
303+
## Removed/renamed
304+
305+
***Removed legacy headers***
306+
307+
- `jerry-api.h`
308+
- `jerry-port.h`
309+
- `jerry-internal.h`
310+
311+
***Renamed headers***
312+
313+
- `jerry-port.h` to `jerrysctipt-port.h`
314+
315+
***Removed API functions***
316+
317+
- `jerry_get_memory_limits`
318+
319+
***Removed unused configuration macros***
320+
321+
- `CONFIG_MEM_DATA_LIMIT_MINUS_HEAP_SIZE`
322+
- `CONFIG_MEM_STACK_LIMIT`
323+
- `CONFIG_VM_STACK_FRAME_INLINED_VALUES_NUMBER`
324+
- `CONFIG_ECMA_GLOBAL_ENVIRONMENT_DECLARATIVE`
325+
326+
# New API functions
327+
328+
In this section we are introducing new API functions.
329+
330+
***Feature***
331+
332+
- [`jerry_is_feature_enabled`](02.API-REFERENCE.md#jerry_is_feature_enabled)
333+
334+
***Parse***
335+
336+
- [`jerry_parse_and_save_literals`](02.API-REFERENCE.md#jerry_parse_and_save_literals)
337+
338+
***Promise***
339+
340+
- [`jerry_run_all_enqueued_jobs`](02.API-REFERENCE.md#jerry_run_all_enqueued_jobs)
341+
342+
***String***
343+
344+
- [`jerry_substring_to_utf8_char_buffer`](02.API-REFERENCE.md#jerry_substring_to_utf8_char_buffer)
345+
- [`jerry_get_utf8_string_size`](02.API-REFERENCE.md#jerry_get_utf8_string_size)
346+
- [`jerry_get_utf8_string_length`](02.API-REFERENCE.md#jerry_get_utf8_string_length)
347+
- [`jerry_create_string_from_utf8`](02.API-REFERENCE.md#jerry_create_string_from_utf8)
348+
- [`jerry_create_string_sz_from_utf8`](02.API-REFERENCE.md#jerry_create_string_sz_from_utf8)
349+
350+
***Number***
351+
352+
- [`jerry_create_number_infinity`](02.API-REFERENCE.md#jerry_create_number_infinity)
353+
- [`jerry_create_number_nan`](02.API-REFERENCE.md#jerry_create_number_nan)
354+
355+
***Error manipulating***
356+
357+
- [`jerry_get_error_type`](02.API-REFERENCE.md#jerry_get_error_type)
358+
359+
***TypedArray***
360+
361+
- [`jerry_create_typedarray`](02.API-REFERENCE.md#jerry_create_typedarray)
362+
- [`jerry_create_typedarray_for_arraybuffer`](02.API-REFERENCE.md#jerry_create_typedarray_for_arraybuffer)
363+
- [`jerry_create_typedarray_for_arraybuffer_sz`](02.API-REFERENCE.md#jerry_create_typedarray_for_arraybuffer_sz)
364+
- [`jerry_get_typedarray_type`](02.API-REFERENCE.md#jerry_get_typedarray_type)
365+
- [`jerry_get_typedarray_length`](02.API-REFERENCE.md#jerry_get_typedarray_length)
366+
- [`jerry_get_typedarray_buffer`](02.API-REFERENCE.md#jerry_get_typedarray_buffer)
367+
- [`jerry_value_is_typedarray`](02.API-REFERENCE.md#jerry_value_is_typedarray)
368+
369+
***ArrayBuffer***
370+
371+
- [`jerry_create_arraybuffer_external`](02.API-REFERENCE.md#jerry_create_arraybuffer_external)
372+
- [`jerry_get_arraybuffer_pointer`](02.API-REFERENCE.md#jerry_get_arraybuffer_pointer)

0 commit comments

Comments
 (0)