node-api: minimal C node_embedding_api function

Co-authored-by: vmoroz <vmorozov@microsoft.com>

Updated embedding.md to include docs for C embedder API

linting

Author: alshdavid

doc/api/embedding.md

@@ -167,8 +167,51 @@ int RunNodeInstance(MultiIsolatePlatform* platform,
 }
 ```
 
+# C embedder API
+
+<!--introduced_in=REPLACEME-->
+
+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`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> 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

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',

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

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_