Skip to content

Commit bd8e25b

Browse files
joyeecheungmhdawson
authored andcommitted
src: disambiguate terms used to refer to builtins and addons
The term "native module" dates back to some of the oldest code in the code base. Within the context of Node.js core it usually refers to modules that are native to Node.js (e.g. fs, http), but it can cause confusion for people who don't work on this part of the code base, as "native module" can also refer to native addons - which is even the case in some of the API docs and error messages. This patch tries to make the usage of these terms more consistent. Now within the context of Node.js core: - JavaScript scripts that are built-in to Node.js are now referred to as "built-in(s)". If they are available as modules, they can also be referred to as "built-in module(s)". - Dynamically-linked shared objects that are loaded into the Node.js processes are referred to as "addons". We will try to avoid using the term "native modules" because it could be ambiguous. Changes in this patch: File names: - node_native_module.h -> node_builtins.h, - node_native_module.cc -> node_builtins.cc C++ binding names: - `native_module` -> `builtins` `node::Environment`: - `native_modules_without_cache` -> `builtins_without_cache` - `native_modules_with_cache` -> `builtins_with_cache` - `native_modules_in_snapshot` -> `builtins_in_cache` - `native_module_require` -> `builtin_module_require` `node::EnvSerializeInfo`: - `native_modules` -> `builtins `node::native_module::NativeModuleLoader`: - `native_module` namespace -> `builtins` namespace - `NativeModuleLoader` -> `BuiltinLoader` - `NativeModuleRecordMap` -> `BuiltinSourceMap` - `NativeModuleCacheMap` -> `BuiltinCodeCacheMap` - `ModuleIds` -> `BuiltinIds` - `ModuleCategories` -> `BuiltinCategories` - `LoadBuiltinModuleSource` -> `LoadBuiltinSource` `loader.js`: - `NativeModule` -> `BuiltinModule` (the `NativeModule` name used in `process.moduleLoadList` is kept for compatibility) And other clarifications in the documentation and comments. PR-URL: nodejs/node#44135 Fixes: nodejs/node#44036 Reviewed-By: Jacob Smith <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Richard Lau <[email protected]> Reviewed-By: Jiawen Geng <[email protected]> Reviewed-By: Chengzhong Wu <[email protected]> Reviewed-By: Mohammed Keyvanzadeh <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Jan Krems <[email protected]>
1 parent 891368c commit bd8e25b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+297
-295
lines changed

.github/CODEOWNERS

+1-1
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@
108108
/benchmark/misc/startup.js @nodejs/startup
109109
/src/node.cc @nodejs/startup
110110
/src/node_code_cache_stub.cc @nodejs/startup
111-
/src/node_native_module* @nodejs/startup
111+
/src/node_builtins* @nodejs/startup
112112
/src/node_snapshot* @nodejs/startup
113113
/lib/internal/bootstrap/* @nodejs/startup
114114
/tools/code_cache/* @nodejs/startup

doc/api/deprecations.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -2003,7 +2003,7 @@ changes:
20032003

20042004
Type: Compile-time
20052005

2006-
Certain versions of `node::MakeCallback` APIs available to native modules are
2006+
Certain versions of `node::MakeCallback` APIs available to native addons are
20072007
deprecated. Please use the versions of the API that accept an `async_context`
20082008
parameter.
20092009

@@ -2751,7 +2751,7 @@ changes:
27512751
Type: Documentation-only
27522752

27532753
The `node:repl` module exports a `_builtinLibs` property that contains an array
2754-
with native modules. It was incomplete so far and instead it's better to rely
2754+
of built-in modules. It was incomplete so far and instead it's better to rely
27552755
upon `require('node:module').builtinModules`.
27562756

27572757
### DEP0143: `Transform._transformState`

doc/api/modules.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -705,8 +705,8 @@ This does not apply to [native addons][], for which reloading will result in an
705705
error.
706706

707707
Adding or replacing entries is also possible. This cache is checked before
708-
native modules and if a name matching a native module is added to the cache,
709-
only `node:`-prefixed require calls are going to receive the native module.
708+
built-in modules and if a name matching a built-in module is added to the cache,
709+
only `node:`-prefixed require calls are going to receive the built-in module.
710710
Use with care!
711711

712712
<!-- eslint-disable node-core/no-duplicate-requires -->

doc/api/n-api.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -201,9 +201,9 @@ GitHub projects using CMake.js.
201201
#### prebuildify
202202

203203
[prebuildify][] is a tool based on node-gyp. The advantage of prebuildify is
204-
that the built binaries are bundled with the native module when it's
204+
that the built binaries are bundled with the native addon when it's
205205
uploaded to npm. The binaries are downloaded from npm and are immediately
206-
available to the module user when the native module is installed.
206+
available to the module user when the native addon is installed.
207207

208208
## Usage
209209

@@ -1381,7 +1381,7 @@ callback throws an exception with no way to recover.
13811381

13821382
### Fatal errors
13831383

1384-
In the event of an unrecoverable error in a native module, a fatal error can be
1384+
In the event of an unrecoverable error in a native addon, a fatal error can be
13851385
thrown to immediately terminate the process.
13861386

13871387
#### `napi_fatal_error`
@@ -5745,7 +5745,7 @@ Returns `napi_ok` if the API succeeded.
57455745

57465746
This function gives V8 an indication of the amount of externally allocated
57475747
memory that is kept alive by JavaScript objects (i.e. a JavaScript object
5748-
that points to its own memory allocated by a native module). Registering
5748+
that points to its own memory allocated by a native addon). Registering
57495749
externally allocated memory will trigger global garbage collections more
57505750
often than it would otherwise.
57515751

doc/contributing/adding-new-napi-api.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Contributing a new API to Node-API
22

3-
Node-API is the next-generation ABI-stable API for native modules.
3+
Node-API is the next-generation ABI-stable API for native addons.
44
While improving the API surface is encouraged and welcomed, the following are
55
a set of principles and guidelines to keep in mind while adding a new
66
Node-API.

lib/assert.js

+2-2
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ const { openSync, closeSync, readSync } = require('fs');
6565
const { inspect } = require('internal/util/inspect');
6666
const { isPromise, isRegExp } = require('internal/util/types');
6767
const { EOL } = require('internal/constants');
68-
const { NativeModule } = require('internal/bootstrap/loaders');
68+
const { BuiltinModule } = require('internal/bootstrap/loaders');
6969
const { isError } = require('internal/util');
7070

7171
const errorCache = new SafeMap();
@@ -303,7 +303,7 @@ function getErrMessage(message, fn) {
303303

304304
// Skip Node.js modules!
305305
if (StringPrototypeStartsWith(filename, 'node:') &&
306-
NativeModule.exists(StringPrototypeSlice(filename, 5))) {
306+
BuiltinModule.exists(StringPrototypeSlice(filename, 5))) {
307307
errorCache.set(identifier, undefined);
308308
return;
309309
}

lib/internal/bootstrap/loaders.js

+17-13
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
// and have their nm_flags set to NM_F_INTERNAL.
2525
//
2626
// Internal JavaScript module loader:
27-
// - NativeModule: a minimal module system used to load the JavaScript core
27+
// - BuiltinModule: a minimal module system used to load the JavaScript core
2828
// modules found in lib/**/*.js and deps/**/*.js. All core modules are
2929
// compiled into the node binary via node_javascript.cc generated by js2c.py,
3030
// so they can be loaded faster without the cost of I/O. This class makes the
@@ -180,9 +180,9 @@ let internalBinding;
180180

181181
const loaderId = 'internal/bootstrap/loaders';
182182
const {
183-
moduleIds,
183+
builtinIds,
184184
compileFunction
185-
} = internalBinding('native_module');
185+
} = internalBinding('builtins');
186186

187187
const getOwn = (target, property, receiver) => {
188188
return ObjectPrototypeHasOwnProperty(target, property) ?
@@ -195,13 +195,13 @@ const getOwn = (target, property, receiver) => {
195195
* Be careful not to expose this to user land unless --expose-internals is
196196
* used, in which case there is no compatibility guarantee about this class.
197197
*/
198-
class NativeModule {
198+
class BuiltinModule {
199199
/**
200200
* A map from the module IDs to the module instances.
201-
* @type {Map<string, NativeModule>}
201+
* @type {Map<string, BuiltinModule>}
202202
*/
203203
static map = new SafeMap(
204-
ArrayPrototypeMap(moduleIds, (id) => [id, new NativeModule(id)])
204+
ArrayPrototypeMap(builtinIds, (id) => [id, new BuiltinModule(id)])
205205
);
206206

207207
constructor(id) {
@@ -216,7 +216,7 @@ class NativeModule {
216216
this.loading = false;
217217

218218
// The following properties are used by the ESM implementation and only
219-
// initialized when the native module is loaded by users.
219+
// initialized when the built-in module is loaded by users.
220220
/**
221221
* The C++ ModuleWrap binding used to interface with the ESM implementation.
222222
* @type {ModuleWrap|undefined}
@@ -232,7 +232,7 @@ class NativeModule {
232232
// To be called during pre-execution when --expose-internals is on.
233233
// Enables the user-land module loader to access internal modules.
234234
static exposeInternals() {
235-
for (const { 0: id, 1: mod } of NativeModule.map) {
235+
for (const { 0: id, 1: mod } of BuiltinModule.map) {
236236
// Do not expose this to user land even with --expose-internals.
237237
if (id !== loaderId) {
238238
mod.canBeRequiredByUsers = true;
@@ -241,11 +241,11 @@ class NativeModule {
241241
}
242242

243243
static exists(id) {
244-
return NativeModule.map.has(id);
244+
return BuiltinModule.map.has(id);
245245
}
246246

247247
static canBeRequiredByUsers(id) {
248-
const mod = NativeModule.map.get(id);
248+
const mod = BuiltinModule.map.get(id);
249249
return mod && mod.canBeRequiredByUsers;
250250
}
251251

@@ -326,13 +326,17 @@ class NativeModule {
326326
requireWithFallbackInDeps : nativeModuleRequire;
327327

328328
const fn = compileFunction(id);
329+
// Arguments must match the parameters specified in
330+
// BuiltinLoader::LookupAndCompile().
329331
fn(this.exports, requireFn, this, process, internalBinding, primordials);
330332

331333
this.loaded = true;
332334
} finally {
333335
this.loading = false;
334336
}
335337

338+
// "NativeModule" is a legacy name of "BuiltinModule". We keep it
339+
// here to avoid breaking users who parse process.moduleLoadList.
336340
ArrayPrototypePush(moduleLoadList, `NativeModule ${id}`);
337341
return this.exports;
338342
}
@@ -342,7 +346,7 @@ class NativeModule {
342346
// written in CommonJS style.
343347
const loaderExports = {
344348
internalBinding,
345-
NativeModule,
349+
BuiltinModule,
346350
require: nativeModuleRequire
347351
};
348352

@@ -351,7 +355,7 @@ function nativeModuleRequire(id) {
351355
return loaderExports;
352356
}
353357

354-
const mod = NativeModule.map.get(id);
358+
const mod = BuiltinModule.map.get(id);
355359
// Can't load the internal errors module from here, have to use a raw error.
356360
// eslint-disable-next-line no-restricted-syntax
357361
if (!mod) throw new TypeError(`Missing internal module '${id}'`);
@@ -361,7 +365,7 @@ function nativeModuleRequire(id) {
361365
// Allow internal modules from dependencies to require
362366
// other modules from dependencies by providing fallbacks.
363367
function requireWithFallbackInDeps(request) {
364-
if (!NativeModule.map.has(request)) {
368+
if (!BuiltinModule.map.has(request)) {
365369
request = `internal/deps/${request}`;
366370
}
367371
return nativeModuleRequire(request);

lib/internal/bootstrap/node.js

+2-2
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434
// `MessagePort` implementation.
3535
// - `lib/internal/bootstrap/loaders.js`: this sets up internal binding and
3636
// module loaders, including `process.binding()`, `process._linkedBinding()`,
37-
// `internalBinding()` and `NativeModule`.
37+
// `internalBinding()` and `BuiltinModule`.
3838
//
3939
// The initialization done in this script is included in both the main thread
4040
// and the worker threads. After this, further initialization is done based
@@ -102,7 +102,7 @@ process.domain = null;
102102
process._exiting = false;
103103

104104
// process.config is serialized config.gypi
105-
const nativeModule = internalBinding('native_module');
105+
const nativeModule = internalBinding('builtins');
106106

107107
// TODO(@jasnell): Once this has gone through one full major
108108
// release cycle, remove the Proxy and setter and update the

lib/internal/bootstrap/pre_execution.js

+3-3
Original file line numberDiff line numberDiff line change
@@ -290,7 +290,7 @@ function initializeReport() {
290290
function setupDebugEnv() {
291291
require('internal/util/debuglog').initializeDebugEnv(process.env.NODE_DEBUG);
292292
if (getOptionValue('--expose-internals')) {
293-
require('internal/bootstrap/loaders').NativeModule.exposeInternals();
293+
require('internal/bootstrap/loaders').BuiltinModule.exposeInternals();
294294
}
295295
}
296296

@@ -512,8 +512,8 @@ function initializePolicy() {
512512
}
513513

514514
function initializeWASI() {
515-
const { NativeModule } = require('internal/bootstrap/loaders');
516-
const mod = NativeModule.map.get('wasi');
515+
const { BuiltinModule } = require('internal/bootstrap/loaders');
516+
const mod = BuiltinModule.map.get('wasi');
517517
mod.canBeRequiredByUsers =
518518
getOptionValue('--experimental-wasi-unstable-preview1');
519519
}

lib/internal/debugger/inspect_repl.js

+2-2
Original file line numberDiff line numberDiff line change
@@ -117,8 +117,8 @@ function extractFunctionName(description) {
117117
}
118118

119119
const {
120-
moduleIds: PUBLIC_BUILTINS,
121-
} = internalBinding('native_module');
120+
builtinIds: PUBLIC_BUILTINS,
121+
} = internalBinding('builtins');
122122
const NATIVES = internalBinding('natives');
123123
function isNativeUrl(url) {
124124
url = RegExpPrototypeSymbolReplace(/\.js$/, url, '');

lib/internal/main/mksnapshot.js

+2-2
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ const {
77
} = primordials;
88

99
const binding = internalBinding('mksnapshot');
10-
const { NativeModule } = require('internal/bootstrap/loaders');
10+
const { BuiltinModule } = require('internal/bootstrap/loaders');
1111
const {
1212
compileSerializeMain,
1313
} = binding;
@@ -92,7 +92,7 @@ function supportedInUserSnapshot(id) {
9292
}
9393

9494
function requireForUserSnapshot(id) {
95-
if (!NativeModule.canBeRequiredByUsers(id)) {
95+
if (!BuiltinModule.canBeRequiredByUsers(id)) {
9696
// eslint-disable-next-line no-restricted-syntax
9797
const err = new Error(
9898
`Cannot find module '${id}'. `

lib/internal/modules/cjs/helpers.js

+6-6
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ const {
1717
ERR_MANIFEST_DEPENDENCY_MISSING,
1818
ERR_UNKNOWN_BUILTIN_MODULE
1919
} = require('internal/errors').codes;
20-
const { NativeModule } = require('internal/bootstrap/loaders');
20+
const { BuiltinModule } = require('internal/bootstrap/loaders');
2121

2222
const { validateString } = require('internal/validators');
2323
const path = require('path');
@@ -42,10 +42,10 @@ const cjsConditions = new SafeSet([
4242
...userConditions,
4343
]);
4444

45-
function loadNativeModule(filename, request) {
46-
const mod = NativeModule.map.get(filename);
45+
function loadBuiltinModule(filename, request) {
46+
const mod = BuiltinModule.map.get(filename);
4747
if (mod?.canBeRequiredByUsers) {
48-
debug('load native module %s', request);
48+
debug('load built-in module %s', request);
4949
// compileForPublicLoader() throws if mod.canBeRequiredByUsers is false:
5050
mod.compileForPublicLoader();
5151
return mod;
@@ -73,7 +73,7 @@ function makeRequireFunction(mod, redirects) {
7373
const href = destination.href;
7474
if (destination.protocol === 'node:') {
7575
const specifier = destination.pathname;
76-
const mod = loadNativeModule(specifier, href);
76+
const mod = loadBuiltinModule(specifier, href);
7777
if (mod && mod.canBeRequiredByUsers) {
7878
return mod.exports;
7979
}
@@ -230,7 +230,7 @@ module.exports = {
230230
addBuiltinLibsToObject,
231231
cjsConditions,
232232
hasEsmSyntax,
233-
loadNativeModule,
233+
loadBuiltinModule,
234234
makeRequireFunction,
235235
normalizeReferrerURL,
236236
stripBOM,

0 commit comments

Comments
 (0)