diff --git a/doc/api/embedding.md b/doc/api/embedding.md index 114f1128af0a42..6a9038a4b67a48 100644 --- a/doc/api/embedding.md +++ b/doc/api/embedding.md @@ -167,8 +167,51 @@ int RunNodeInstance(MultiIsolatePlatform* platform, } ``` +# C embedder API + + + +While Node.js provides an extensive C++ embedding API that can be used from C++ +applications, the C-based API is useful when Node.js is embedded as a shared +libnode library into C++ or non-C++ applications. + +## API design overview + +One of the goals for the C based embedder API is to be ABI stable. It means that +applications must be able to use newer libnode versions without recompilation. +The following design principles are targeting to achieve that goal. + +- Follow the best practices for the [node-api][] design and build on top of + the [node-api][]. + +## API reference + +#### Functions + +##### `node_embedding_main` + + + +> Stability: 1 - Experimental + +Runs Node.js runtime instance. + +```c +int32_t NAPI_CDECL node_embedding_main( + int32_t argc, + char* argv[]); +``` + +- `[in] argc`: Number of items in the `argv` array. +- `[in] argv`: CLI arguments as an array of zero terminated strings. + +Returns `int32_t` with instance exit code. + [CLI options]: cli.md [`process.memoryUsage()`]: process.md#processmemoryusage [deprecation policy]: deprecations.md [embedtest.cc]: https://github.com/nodejs/node/blob/HEAD/test/embedding/embedtest.cc +[node-api]: n-api.md [src/node.h]: https://github.com/nodejs/node/blob/HEAD/src/node.h diff --git a/node.gyp b/node.gyp index 0496f75fea5637..d4b1c52930d78b 100644 --- a/node.gyp +++ b/node.gyp @@ -113,6 +113,8 @@ 'src/node_dir.cc', 'src/node_dotenv.cc', 'src/node_env_var.cc', + 'src/node_embedding_api.cc', + 'src/node_embedding_api.h', 'src/node_errors.cc', 'src/node_external_reference.cc', 'src/node_file.cc', diff --git a/src/node_embedding_api.cc b/src/node_embedding_api.cc new file mode 100644 index 00000000000000..20abfc61567fa9 --- /dev/null +++ b/src/node_embedding_api.cc @@ -0,0 +1,25 @@ +// +// Description: C-based API for embedding Node.js. +// +// !!! WARNING !!! WARNING !!! WARNING !!! +// This is a new API and is subject to change. +// While it is C-based, it is not ABI safe yet. +// Consider all functions and data structures as experimental. +// !!! WARNING !!! WARNING !!! WARNING !!! +// +// This file contains the C-based API for embedding Node.js in a host +// application. The API is designed to be used by applications that want to +// embed Node.js as a shared library (.so or .dll) and can interop with +// C-based API. +// + +#include "node_embedding_api.h" +#include "node.h" + +EXTERN_C_START + +int32_t NAPI_CDECL node_embedding_main(int32_t argc, char* argv[]) { + return node::Start(argc, argv); +} + +EXTERN_C_END diff --git a/src/node_embedding_api.h b/src/node_embedding_api.h new file mode 100644 index 00000000000000..d012a525b48735 --- /dev/null +++ b/src/node_embedding_api.h @@ -0,0 +1,30 @@ +// +// Description: C-based API for embedding Node.js. +// +// !!! WARNING !!! WARNING !!! WARNING !!! +// This is a new API and is subject to change. +// While it is C-based, it is not ABI safe yet. +// Consider all functions and data structures as experimental. +// !!! WARNING !!! WARNING !!! WARNING !!! +// +// This file contains the C-based API for embedding Node.js in a host +// application. The API is designed to be used by applications that want to +// embed Node.js as a shared library (.so or .dll) and can interop with +// C-based API. +// + +#ifndef SRC_NODE_EMBEDDING_API_H_ +#define SRC_NODE_EMBEDDING_API_H_ + +#include "node_api.h" + +#define NODE_EMBEDDING_VERSION 1 + +EXTERN_C_START + +// Runs Node.js main function. It is the same as running Node.js from CLI. +NAPI_EXTERN int32_t NAPI_CDECL node_embedding_main(int32_t argc, char* argv[]); + +EXTERN_C_END + +#endif // SRC_NODE_EMBEDDING_API_H_