lp-checker-js

This is a port of lp-checker library. The repository contains precompiled static and dynamic libraries of lp-checker that are then linked with the node-addon-api glue code that exports the API.

Install

$ npm install git+ssh://github.com/loudplay/lp-checker-js.git

It will build the library automatically, though you need to have visual studio or Xcode installed for this to work.

Use with electron

lp-checker-js uses N-API, an ABI that is compatible with any future version of node.js and that's independent of the node ABI. Supposedly, you don't need to recompile this binding for electron, only once for N-API. Package uses node-pre-gyp that downloads all headers and links to correct N-API version automatically.

If you see encounter strange behavior while using this binding, be sure to look at the relevant section in Troubleshooting.

Building process

Windows

Building on Windows requires at least Visual Studio Build Tools to be installed. Download 2019 edition here.

After this npm install should generate a VS project and build the binding just fine. The only dependency is libchecker_static.lib which is supplied by this repository.

Mac

Mac is much more trickier, because lp-checker leverages the native APIs available on Mac through Swift programming language to provide system-level information. Because lp-checker is written in C++, an additional dynamic library for the swift portion of lp-checker is generated. The resulting addon should then link not only against the static library, but a dynamic library as well.

There are 2 problems:

1. How will addon find the dynamic library it was linked against, and
2. How will the dynamic library link against its dynamic libraries?

The answer to the first question: through rpaths. Rpath stands for RuntimePATH and is used on linux and mac by the dynamic linker to search for .so and .dylib files respectively. Additionally, mac supports several rpaths to be defined within a library (or an executable). Aside from absolute paths, rpath may also contain special paths @executable_path and @loader_path. These two paths provide an ability for a library to be moved freely within the file system as long as the dependencies are moved too.

We are interested in @loader_path. During linking it will be substituted by a path to the binary that requests linking. So, if our addon requests dynamic linker to link against libchecker_swift.dylib, @loader_path will be resolved to the path where addon is located. This leads to the following approach: we can ensure that the addon is portable across file system locations and physical computers, if only we set all paths to external dynamic libraries to be relative to @loader_path. If addon will search for libchecker_swift.dylib in @loader_path, and if libchecker_swift.dylib will search for its dependencies in @loader_path, and these dependencies will also search in @loader_path and so on and so on, then we only need to ensure to pack .addon file and all neighbouring .dylib binaries together inside an application package for it to just work.

This bundling of dylibs is performed by tools/bundle_dylib_deps.sh script. This script is ran during compilation by gyp build system. It automates process of looking dependencies of a dylib, copying them to a folder, finding their dependencies, copying them also and fixing the paths inside the dependent libraries. The script requires Xcode to be installed.

Troubleshooting

Visual Studio edition not specified

If you get this error:

npm ERR! code 1
npm ERR! git dep preparation failed
npm ERR! > @loudplay/[email protected] install
npm ERR! > node-gyp configure && node-gyp build
npm ERR! npm WARN using --force Recommended protections disabled.
npm ERR! gyp info it worked if it ends with ok
npm ERR! gyp info using [email protected]
npm ERR! gyp info using [email protected] | win32 | ia32
npm ERR! gyp info find Python using Python version 3.9.6 found at "C:\Users\Isabelle\scoop\apps\python\current\python.exe"
npm ERR! gyp ERR! find VS
npm ERR! gyp ERR! find VS msvs_version was set from command line or npm config
npm ERR! gyp ERR! find VS - looking for Visual Studio version 2017
npm ERR! gyp ERR! find VS VCINSTALLDIR not set, not running in VS Command Prompt
npm ERR! gyp ERR! find VS checking VS2019 (16.10.31424.327) found at:
npm ERR! gyp ERR! find VS "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community"
npm ERR! gyp ERR! find VS - found "Visual Studio C++ core features"
npm ERR! gyp ERR! find VS - found VC++ toolset: v142
npm ERR! gyp ERR! find VS - found Windows SDK: 10.0.19041.0
npm ERR! gyp ERR! find VS - msvs_version does not match this version
npm ERR! gyp ERR! find VS could not find a version of Visual Studio 2017 or newer to use
npm ERR! gyp ERR! find VS looking for Visual Studio 2015
npm ERR! gyp ERR! find VS - not found
npm ERR! gyp ERR! find VS not looking for VS2013 as it is only supported up to Node.js 8
npm ERR! gyp ERR! find VS
npm ERR! gyp ERR! find VS valid versions for msvs_version:
npm ERR! gyp ERR! find VS - "2019"
npm ERR! gyp ERR! find VS - "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community"
npm ERR! gyp ERR! find VS
npm ERR! gyp ERR! find VS **************************************************************
npm ERR! gyp ERR! find VS You need to install the latest version of Visual Studio
npm ERR! gyp ERR! find VS including the "Desktop development with C++" workload.
npm ERR! gyp ERR! find VS For more information consult the documentation at:
npm ERR! gyp ERR! find VS https://github.com/nodejs/node-gyp#on-windows
npm ERR! gyp ERR! find VS **************************************************************
npm ERR! gyp ERR! find VS
...

Make sure to specify the edition of visual studio you have installed: 2015, 2017, or 2019.

$ npm config set msvs_version=2019

and install again.

Freezes, spurious crashes on Electron

NOTE: This solution is a speculation. As of writing this document, lp-checker-js is untested against Electron ABI. See if this helps.

Since electron uses different ABI than node.js, you may need to recompile it with electron ABI. Install electron-builder and execute it after every update to dependencies.

$ npm install electron-build
$ node_modules/.bin/electron-build

Or, if '.bin/electron-build' doesn't work, try electron-build.cmd executable.