Skip to content

Commit 9188967

Browse files
kraenhansenkraenhansen
committed
Cleaning up the porting docs
1 parent 2e9d32f commit 9188967

File tree

1 file changed

+75
-73
lines changed

1 file changed

+75
-73
lines changed

‎PORTING.md‎

Lines changed: 75 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -5,87 +5,88 @@ The source directories are [`test/js-native-api`](https://github.com/nodejs/node
55
and [`test/node-api`](https://github.com/nodejs/node/tree/main/test/node-api) in the Node.js repository.
66

77
Difficulty is assessed on two axes:
8+
89
- **Size/complexity** — total lines of C/C++ and JS across all source files
910
- **Runtime-API dependence** — pure `js_native_api.h` is cheapest; Node.js extensions and direct
1011
libuv calls require harness work or Node-only scoping
1112

12-
| Rating | Meaning |
13-
|---|---|
14-
| Easy | Small test, pure `js_native_api.h` or trivial runtime API, straightforward 1:1 port |
15-
| Medium | Moderate size or uses a Node.js extension API that the harness will need to abstract |
16-
| Hard | Large test and/or deep libuv/worker/SEA dependency; may need new harness primitives or Node-only scoping |
13+
| Rating | Meaning |
14+
| ------ | -------------------------------------------------------------------------------------------------------- |
15+
| Easy | Small test, pure `js_native_api.h` or trivial runtime API, straightforward 1:1 port |
16+
| Medium | Moderate size or uses a Node.js extension API that the harness will need to abstract |
17+
| Hard | Large test and/or deep libuv/worker/SEA dependency; may need new harness primitives or Node-only scoping |
1718

1819
## Engine-specific (`js-native-api`)
1920

2021
Tests covering the engine-specific part of Node-API, defined in `js_native_api.h`.
2122

22-
| Directory | Status | Difficulty |
23-
|---|---|---|
24-
| `2_function_arguments` | Ported | — |
25-
| `3_callbacks` | Ported | Easy |
26-
| `4_object_factory` | Ported | Easy |
27-
| `5_function_factory` | Ported | Easy |
28-
| `6_object_wrap` | Not ported | Medium |
29-
| `7_factory_wrap` | Ported | Easy |
30-
| `8_passing_wrapped` | Ported | Easy |
31-
| `test_array` | Ported | Easy |
32-
| `test_bigint` | Ported | Easy |
33-
| `test_cannot_run_js` | Not ported | Medium |
34-
| `test_constructor` | Not ported | Medium |
35-
| `test_conversions` | Not ported | Medium |
36-
| `test_dataview` | Partial | Easy |
37-
| `test_date` | Ported | Easy |
38-
| `test_error` | Not ported | Medium |
39-
| `test_exception` | Not ported | Medium |
40-
| `test_finalizer` | Not ported | Medium |
41-
| `test_function` | Not ported | Medium |
42-
| `test_general` | Not ported | Hard |
43-
| `test_handle_scope` | Ported | Easy |
44-
| `test_instance_data` | Ported | Easy |
45-
| `test_new_target` | Ported | Easy |
46-
| `test_number` | Ported | Easy |
47-
| `test_object` | Not ported | Hard |
48-
| `test_promise` | Ported | Easy |
49-
| `test_properties` | Ported | Easy |
50-
| `test_reference` | Not ported | Medium |
51-
| `test_reference_double_free` | Ported | Easy |
52-
| `test_sharedarraybuffer` | Not ported | Medium |
53-
| `test_string` | Not ported | Medium |
54-
| `test_symbol` | Ported | Easy |
55-
| `test_typedarray` | Not ported | Medium |
23+
| Directory | Status | Difficulty |
24+
| ---------------------------- | ---------- | ---------- |
25+
| `2_function_arguments` | Ported ✅ | — |
26+
| `3_callbacks` | Ported ✅ | Easy |
27+
| `4_object_factory` | Ported ✅ | Easy |
28+
| `5_function_factory` | Ported ✅ | Easy |
29+
| `6_object_wrap` | Not ported | Medium |
30+
| `7_factory_wrap` | Ported ✅ | Easy |
31+
| `8_passing_wrapped` | Ported ✅ | Easy |
32+
| `test_array` | Ported ✅ | Easy |
33+
| `test_bigint` | Ported ✅ | Easy |
34+
| `test_cannot_run_js` | Not ported | Medium |
35+
| `test_constructor` | Not ported | Medium |
36+
| `test_conversions` | Not ported | Medium |
37+
| `test_dataview` | Partial | Easy |
38+
| `test_date` | Ported ✅ | Easy |
39+
| `test_error` | Not ported | Medium |
40+
| `test_exception` | Not ported | Medium |
41+
| `test_finalizer` | Not ported | Medium |
42+
| `test_function` | Not ported | Medium |
43+
| `test_general` | Not ported | Hard |
44+
| `test_handle_scope` | Ported ✅ | Easy |
45+
| `test_instance_data` | Ported ✅ | Easy |
46+
| `test_new_target` | Ported ✅ | Easy |
47+
| `test_number` | Ported ✅ | Easy |
48+
| `test_object` | Not ported | Hard |
49+
| `test_promise` | Ported ✅ | Easy |
50+
| `test_properties` | Ported ✅ | Easy |
51+
| `test_reference` | Not ported | Medium |
52+
| `test_reference_double_free` | Ported ✅ | Easy |
53+
| `test_sharedarraybuffer` | Not ported | Medium |
54+
| `test_string` | Not ported | Medium |
55+
| `test_symbol` | Ported ✅ | Easy |
56+
| `test_typedarray` | Not ported | Medium |
5657

5758
## Runtime-specific (`node-api`)
5859

5960
Tests covering the runtime-specific part of Node-API, defined in `node_api.h`.
6061

61-
| Directory | Status | Difficulty |
62-
|---|---|---|
63-
| `1_hello_world` | Not ported | Easy |
64-
| `test_async` | Not ported | Hard |
65-
| `test_async_cleanup_hook` | Not ported | Hard |
66-
| `test_async_context` | Not ported | Hard |
67-
| `test_buffer` | Not ported | Medium |
68-
| `test_callback_scope` | Not ported | Hard |
69-
| `test_cleanup_hook` | Not ported | Medium |
70-
| `test_env_teardown_gc` | Not ported | Easy |
71-
| `test_exception` | Not ported | Easy |
72-
| `test_fatal` | Not ported | Hard |
73-
| `test_fatal_exception` | Not ported | Easy |
74-
| `test_general` | Not ported | Medium |
75-
| `test_init_order` | Not ported | Medium |
76-
| `test_instance_data` | Not ported | Hard |
77-
| `test_make_callback` | Not ported | Hard |
78-
| `test_make_callback_recurse` | Not ported | Hard |
79-
| `test_null_init` | Not ported | Medium |
80-
| `test_reference_by_node_api_version` | Not ported | Medium |
81-
| `test_sea_addon` | Not ported | Hard |
82-
| `test_threadsafe_function` | Not ported | Hard |
83-
| `test_threadsafe_function_shutdown` | Not ported | Hard |
84-
| `test_uv_loop` | Not ported | Hard |
85-
| `test_uv_threadpool_size` | Not ported | Hard |
86-
| `test_worker_buffer_callback` | Not ported | Hard |
87-
| `test_worker_terminate` | Not ported | Hard |
88-
| `test_worker_terminate_finalization` | Not ported | Hard |
62+
| Directory | Status | Difficulty |
63+
| ------------------------------------ | ---------- | ---------- |
64+
| `1_hello_world` | Not ported | Easy |
65+
| `test_async` | Not ported | Hard |
66+
| `test_async_cleanup_hook` | Not ported | Hard |
67+
| `test_async_context` | Not ported | Hard |
68+
| `test_buffer` | Not ported | Medium |
69+
| `test_callback_scope` | Not ported | Hard |
70+
| `test_cleanup_hook` | Not ported | Medium |
71+
| `test_env_teardown_gc` | Not ported | Easy |
72+
| `test_exception` | Not ported | Easy |
73+
| `test_fatal` | Not ported | Hard |
74+
| `test_fatal_exception` | Not ported | Easy |
75+
| `test_general` | Not ported | Medium |
76+
| `test_init_order` | Not ported | Medium |
77+
| `test_instance_data` | Not ported | Hard |
78+
| `test_make_callback` | Not ported | Hard |
79+
| `test_make_callback_recurse` | Not ported | Hard |
80+
| `test_null_init` | Not ported | Medium |
81+
| `test_reference_by_node_api_version` | Not ported | Medium |
82+
| `test_sea_addon` | Not ported | Hard |
83+
| `test_threadsafe_function` | Not ported | Hard |
84+
| `test_threadsafe_function_shutdown` | Not ported | Hard |
85+
| `test_uv_loop` | Not ported | Hard |
86+
| `test_uv_threadpool_size` | Not ported | Hard |
87+
| `test_worker_buffer_callback` | Not ported | Hard |
88+
| `test_worker_terminate` | Not ported | Hard |
89+
| `test_worker_terminate_finalization` | Not ported | Hard |
8990

9091
## Experimental Node-API Features
9192

@@ -97,12 +98,12 @@ When `NAPI_EXPERIMENTAL` is defined in Node.js, `NAPI_VERSION` is set to
9798
`NAPI_VERSION_EXPERIMENTAL (2147483647)`. The `NAPI_MODULE` macro exports this version, and the
9899
runtime uses it to decide whether to enable experimental behavior for that addon.
99100

100-
| Feature macro | APIs | Used by |
101-
|---|---|---|
102-
| `NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER` | `node_api_is_sharedarraybuffer`, `node_api_create_sharedarraybuffer` | `test_dataview`, `test_sharedarraybuffer` |
103-
| `NODE_API_EXPERIMENTAL_HAS_CREATE_OBJECT_WITH_PROPERTIES` | `node_api_create_object_with_properties` | `test_object` |
104-
| `NODE_API_EXPERIMENTAL_HAS_SET_PROTOTYPE` | `node_api_set_prototype` | `test_general` |
105-
| `NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER` | `node_api_post_finalizer` | `test_general`, `test_finalizer`, `6_object_wrap` |
101+
| Feature macro | APIs | Used by |
102+
| --------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------- |
103+
| `NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER` | `node_api_is_sharedarraybuffer`, `node_api_create_sharedarraybuffer` | `test_dataview`, `test_sharedarraybuffer` |
104+
| `NODE_API_EXPERIMENTAL_HAS_CREATE_OBJECT_WITH_PROPERTIES` | `node_api_create_object_with_properties` | `test_object` |
105+
| `NODE_API_EXPERIMENTAL_HAS_SET_PROTOTYPE` | `node_api_set_prototype` | `test_general` |
106+
| `NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER` | `node_api_post_finalizer` | `test_general`, `test_finalizer`, `6_object_wrap` |
106107

107108
Tests that depend on these APIs are currently ported without the experimental test cases (marked
108109
as "Partial" in the status column) or not ported at all. To fully support them, the CTS will need:
@@ -150,6 +151,7 @@ The following tests call into libuv directly — `napi_get_uv_event_loop`, `uv_t
150151
- `test_uv_loop`, `test_uv_threadpool_size`
151152

152153
Porting options:
154+
153155
1. **Node-only scope** — mark these tests as Node.js-only and skip on other runtimes.
154156
2. **Harness abstraction** — introduce a minimal platform-agnostic threading/async API in the
155157
harness (e.g., `cts_thread_create`, `cts_async_schedule`) that implementors back with their

0 commit comments

Comments
 (0)