docs: add note about win_delay_load_hook (#15766)

This commit is contained in:
Jeremy Apthorp 2018-11-19 16:13:50 -08:00 committed by GitHub
parent 90795c4fa4
commit 08b56b7675
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 21 additions and 0 deletions

View file

@ -57,6 +57,14 @@ app.getGPUInfo('complete')
app.getGPUInfo('basic')
```
## `win_delay_load_hook`
When building native modules for windows, the `win_delay_load_hook` variable in
the module's `binding.gyp` must be true (which is the default). If this hook is
not present, then the native module will fail to load on Windows, with an error
message like `Cannot find module`. See the [native module
guide](/docs/tutorial/using-native-node-modules.md) for more.
# Breaking API Changes (3.0)

View file

@ -83,9 +83,22 @@ If you installed a native module and found it was not working, you need to check
following things:
* The architecture of the module has to match Electron's architecture (ia32 or x64).
* `win_delay_load_hook` is not set to `false` in the module's `binding.gyp`.
* After you upgrade Electron, you usually need to rebuild the modules.
* When in doubt, run `electron-rebuild` first.
### A note about `win_delay_load_hook`
On Windows, by default, node-gyp links native modules against `node.dll`.
However, in Electron 4.x and higher, the symbols needed by native modules are
exported by `electron.exe`, and there is no `node.dll` in Electron 4.x. In
order to load native modules on Windows, node-gyp installs a [delay-load
hook](https://msdn.microsoft.com/en-us/library/z9h1h6ty.aspx) that triggers
when the native module is loaded, and redirects the `node.dll` reference to use
the loading executable instead of looking for `node.dll` in the library search
path (which would turn up nothing). As such, on Electron 4.x and higher,
`'win_delay_load_hook': 'true'` is required to load native modules.
## Modules that rely on `prebuild`
[`prebuild`](https://github.com/mafintosh/prebuild) provides a way to