From b7d8234a86b52d760f17ff7561560645de862b30 Mon Sep 17 00:00:00 2001 From: Jeremy Apthorp Date: Wed, 6 Feb 2019 08:29:58 -0800 Subject: [PATCH] docs: add some troubleshooting info related to win_delay_load_hook (#16764) * docs: add some troubleshooting info related to win_delay_load_hook * appease lint --- docs/tutorial/using-native-node-modules.md | 28 ++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/tutorial/using-native-node-modules.md b/docs/tutorial/using-native-node-modules.md index 5bf7a0c33011..bc93909c362b 100644 --- a/docs/tutorial/using-native-node-modules.md +++ b/docs/tutorial/using-native-node-modules.md @@ -99,6 +99,34 @@ 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. + +If you get an error like `Module did not self-register`, or `The specified +procedure could not be found`, it may mean that the module you're trying to use +did not correctly include the delay-load hook. If the module is built with +node-gyp, ensure that the `win_delay_load_hook` variable is set to `true` in +the `binding.gyp` file, and isn't getting overridden anywhere. If the module +is built with another system, you'll need to ensure that you build with a +delay-load hook installed in the main `.node` file. Your `link.exe` invocation +should look like this: + +```text + link.exe /OUT:"foo.node" "...\node.lib" delayimp.lib /DELAYLOAD:node.exe /DLL + "my_addon.obj" "win_delay_load_hook.obj" +``` + +In particular, it's important that: + +- you link against `node.lib` from _Electron_ and not Node. If you link against + the wrong `node.lib` you will get load-time errors when you require the + module in Electron. +- you include the flag `/DELAYLOAD:node.exe`. If the `node.exe` link is not + delayed, then the delay-load hook won't get a chance to fire and the node + symbols won't be correctly resolved. +- `win_delay_load_hook.obj` is linked directly into the final DLL. If the hook + is set up in a dependent DLL, it won't fire at the right time. + +See [node-gyp](https://github.com/nodejs/node-gyp/blob/e2401e1395bef1d3c8acec268b42dc5fb71c4a38/src/win_delay_load_hook.cc) for an example delay-load hook if you're implementing your own. + ## Modules that rely on `prebuild` [`prebuild`](https://github.com/mafintosh/prebuild) provides a way to