From b8372f20a033f9de2722b46a9303cd4d027cdb9c Mon Sep 17 00:00:00 2001 From: Erick Zhao Date: Fri, 3 Sep 2021 13:46:53 -0700 Subject: [PATCH] docs: move module creation guide to /development (#30826) --- .../{tutorial => development}/creating-api.md | 52 +++++++++---------- 1 file changed, 24 insertions(+), 28 deletions(-) rename docs/{tutorial => development}/creating-api.md (68%) diff --git a/docs/tutorial/creating-api.md b/docs/development/creating-api.md similarity index 68% rename from docs/tutorial/creating-api.md rename to docs/development/creating-api.md index 4edc198f9c10..836a2f9601ee 100644 --- a/docs/tutorial/creating-api.md +++ b/docs/development/creating-api.md @@ -1,16 +1,16 @@ -# Creating an Electron Browser Module API +# Creating a New Electron Browser Module -Welcome to the Electron API guide! If you are unfamiliar with creating electron APIs within the `browser` module, this guide serves as a checklist for some of the necessary steps that you will need to implement. +Welcome to the Electron API guide! If you are unfamiliar with creating a new Electron API module within the [`browser`](https://github.com/electron/electron/tree/main/shell/browser) directory, this guide serves as a checklist for some of the necessary steps that you will need to implement. This is not a comprehensive end-all guide to creating an Electron Browser API, rather an outline documenting some of the more unintuitive steps. -## Adding Your Files To Electron's Project Configuration +## Add your files to Electron's project configuration -Electron uses [GN](https://gn.googlesource.com/gn) as a meta build system to generate files for its compiler, [Ninja](https://ninja-build.org/). This means that in order to tell Electron to compile your code, we have to add your API's code and header file names into [`filenames.gni`](https://github.com/electron/electron/blob/main/filenames.gni). +Electron uses [GN](https://gn.googlesource.com/gn) as a meta build system to generate files for its compiler, [Ninja](https://ninja-build.org/). This means that in order to tell Electron to compile your code, we have to add your API's code and header file names into [`filenames.gni`](https://github.com/electron/electron/blob/main/filenames.gni). -You will need to append your api file names alphabetically into the appropriate files like so: +You will need to append your API file names alphabetically into the appropriate files like so: -```cpp +```cpp title='filenames.gni' lib_sources = [ "path/to/api/api_name.cc", "path/to/api/api_name.h", @@ -32,13 +32,13 @@ lib_sources_linux = [ ] ``` -Note that the Windows, MacOS and Linux array additions are optional and should only be added if your API has specific platform implementations. +Note that the Windows, macOS and Linux array additions are optional and should only be added if your API has specific platform implementations. -## Create API Documentation +## Create API documentation -Type definitions are generated by Electron using [`docs-parser`](https://github.com/electron/docs-parser) and [`typescript-definitions`](https://github.com/electron/typescript-definitions). This step is necessary to ensure consistency across Electron's API documentation. This means that for your API type definition to appear in the `electron.d.ts` file, we must create a `.md` file. Examples can be found in [this folder](https://github.com/electron/electron/tree/main/docs/api). +Type definitions are generated by Electron using [`@electron/docs-parser`](https://github.com/electron/docs-parser) and [`@electron/typescript-definitions`](https://github.com/electron/typescript-definitions). This step is necessary to ensure consistency across Electron's API documentation. This means that for your API type definition to appear in the `electron.d.ts` file, we must create a `.md` file. Examples can be found in [this folder](https://github.com/electron/electron/tree/main/docs/api). -## Setting Up `ObjectTemplateBuilder` and `Wrappable` +## Set up `ObjectTemplateBuilder` and `Wrappable` Electron constructs its modules using [`object_template_builder`](https://www.electronjs.org/blog/from-native-to-js#mateobjecttemplatebuilder). @@ -48,7 +48,7 @@ Here is a basic example of code that you may need to add, in order to incorporat In your `api_name.h` file: -```cpp +```cpp title='api_name.h' #ifndef SHELL_BROWSER_API_ELECTRON_API_{API_NAME}_H_ #define SHELL_BROWSER_API_ELECTRON_API_{API_NAME}_H_ @@ -75,7 +75,7 @@ class ApiName : public gin::Wrappable { In your `api_name.cc` file: -```cpp +```cpp title='api_name.cc' #include "shell/browser/api/electron_api_safe_storage.h" #include "shell/browser/browser.h" @@ -125,15 +125,11 @@ void Initialize(v8::Local exports, } // namespace ``` -## Link Your Electron API With Node +## Link your Electron API with Node -To learn about how Electron links with Node, [click here.](https://www.electronjs.org/blog/electron-internals-using-node-as-a-library#link-node-with-electron) +In the [`typings/internal-ambient.d.ts`](https://github.com/electron/electron/blob/main/typings/internal-ambient.d.ts) file, we need to append a new property onto the `Process` interface like so: -In the [`internal-ambient.d.ts`](https://github.com/electron/electron/blob/main/typings/internal-ambient.d.ts) file: - -We need to append a new property onto the `Process` interface found in this file like so: - -```ts +```ts title='typings/internal-ambient.d.ts' interface Process { _linkedBinding(name: 'electron_browser_{api_name}', Electron.ApiName); } @@ -141,22 +137,22 @@ interface Process { At the very bottom of your `api_name.cc` file: -```cpp +```cpp title='api_name.cc' NODE_LINKED_MODULE_CONTEXT_AWARE(electron_browser_{api_name},Initialize) ``` -In your [`shell/common/node_bindings.cc`](https://github.com/electron/electron/blob/main/shell/common/node_bindings.cc) file: +In your [`shell/common/node_bindings.cc`](https://github.com/electron/electron/blob/main/shell/common/node_bindings.cc) file, add your node binding name to Electron's built-in modules. -Add your node binding name to Electron's built-in modules. - -```cpp +```cpp title='shell/common/node_bindings.cc' #define ELECTRON_BUILTIN_MODULES(V) \ V(electron_browser_{api_name}) ``` -## Expose Your API to TypeScript +> Note: More technical details on how Node links with Electron can be found on [our blog](https://www.electronjs.org/blog/electron-internals-using-node-as-a-library#link-node-with-electron). -### Export Your API as a module +## Expose your API to TypeScript + +### Export your API as a module We will need to create a new TypeScript file in the path that follows: @@ -164,11 +160,11 @@ We will need to create a new TypeScript file in the path that follows: An example of the contents of this file can be found [here](https://github.com/electron/electron/blob/main/lib/browser/api/native-image.ts). -### Expose Your module to TypeScript +### Expose your module to TypeScript Add your module to the module list found at `"lib/browser/api/module-list.ts"` like so: -```typescript +```typescript title='lib/browser/api/module-list.ts' export const browserModuleList: ElectronInternal.ModuleEntry[] = [ { name: 'apiName', loader: () => require('./api-name') }, ];