[question] Naive npm installation from scratch yields a cryptic error to beginners

[Thesephi]

[label = question]

Hi all,

I've been using unit-http in my projects for a few years now. Usually I follow the official installation guide, where I install all system packages first, then I do npm install unit-http successfully.

Today was the 1st time I did npm install unit-http first on a brand new host machine. And so (understandably) I ended up with a failed npm installation, like so:

npm i -g unit-http
npm ERR! code 1
npm ERR! path /opt/nodejs/16.14.2/lib/node_modules/unit-http
npm ERR! command failed
npm ERR! command sh -c node-gyp configure build
npm ERR! make: Entering directory '/opt/nodejs/16.14.2/lib/node_modules/unit-http/build'
npm ERR!   CXX(target) Release/obj.target/unit-http/unit.o
npm ERR! make: Leaving directory '/opt/nodejs/16.14.2/lib/node_modules/unit-http/build'
npm ERR! gyp info it worked if it ends with ok
npm ERR! gyp info using node-gyp@8.4.1
npm ERR! gyp info using node@16.14.2 | linux | x64
npm ERR! gyp info find Python using Python version 3.10.4 found at "/home/codespace/.python/current/bin/python3"
npm ERR! gyp info spawn /home/codespace/.python/current/bin/python3
npm ERR! gyp info spawn args [
npm ERR! gyp info spawn args   '/opt/nodejs/16.14.2/lib/node_modules/npm/node_modules/node-gyp/gyp/gyp_main.py',
npm ERR! gyp info spawn args   'binding.gyp',
npm ERR! gyp info spawn args   '-f',
npm ERR! gyp info spawn args   'make',
npm ERR! gyp info spawn args   '-I',
npm ERR! gyp info spawn args   '/opt/nodejs/16.14.2/lib/node_modules/unit-http/build/config.gypi',
npm ERR! gyp info spawn args   '-I',
npm ERR! gyp info spawn args   '/opt/nodejs/16.14.2/lib/node_modules/npm/node_modules/node-gyp/addon.gypi',
npm ERR! gyp info spawn args   '-I',
npm ERR! gyp info spawn args   '/home/codespace/.cache/node-gyp/16.14.2/include/node/common.gypi',
npm ERR! gyp info spawn args   '-Dlibrary=shared_library',
npm ERR! gyp info spawn args   '-Dvisibility=default',
npm ERR! gyp info spawn args   '-Dnode_root_dir=/home/codespace/.cache/node-gyp/16.14.2',
npm ERR! gyp info spawn args   '-Dnode_gyp_dir=/opt/nodejs/16.14.2/lib/node_modules/npm/node_modules/node-gyp',
npm ERR! gyp info spawn args   '-Dnode_lib_file=/home/codespace/.cache/node-gyp/16.14.2/<(target_arch)/node.lib',
npm ERR! gyp info spawn args   '-Dmodule_root_dir=/opt/nodejs/16.14.2/lib/node_modules/unit-http',
npm ERR! gyp info spawn args   '-Dnode_engine=v8',
npm ERR! gyp info spawn args   '--depth=.',
npm ERR! gyp info spawn args   '--no-parallel',
npm ERR! gyp info spawn args   '--generator-output',
npm ERR! gyp info spawn args   'build',
npm ERR! gyp info spawn args   '-Goutput_dir=.'
npm ERR! gyp info spawn args ]
npm ERR! gyp info spawn make
npm ERR! gyp info spawn args [ 'BUILDTYPE=Release', '-C', 'build' ]
npm ERR! In file included from ../unit.h:9,
npm ERR!                  from ../unit.cpp:6:
npm ERR! ../nxt_napi.h:17:10: fatal error: nxt_unit.h: No such file or directory
npm ERR!    17 | #include <nxt_unit.h>
npm ERR!       |          ^~~~~~~~~~~~
npm ERR! compilation terminated.
npm ERR! make: *** [unit-http.target.mk:110: Release/obj.target/unit-http/unit.o] Error 1
npm ERR! gyp ERR! build error 
npm ERR! gyp ERR! stack Error: `make` failed with exit code: 2
npm ERR! gyp ERR! stack     at ChildProcess.onExit (/opt/nodejs/16.14.2/lib/node_modules/npm/node_modules/node-gyp/lib/build.js:194:23)
npm ERR! gyp ERR! stack     at ChildProcess.emit (node:events:526:28)
npm ERR! gyp ERR! stack     at Process.ChildProcess._handle.onexit (node:internal/child_process:291:12)
npm ERR! gyp ERR! System Linux 5.4.0-1074-azure
npm ERR! gyp ERR! command "/opt/nodejs/16.14.2/bin/node" "/opt/nodejs/16.14.2/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "configure" "build"
npm ERR! gyp ERR! cwd /opt/nodejs/16.14.2/lib/node_modules/unit-http
npm ERR! gyp ERR! node -v v16.14.2
npm ERR! gyp ERR! node-gyp -v v8.4.1
npm ERR! gyp ERR! not ok

Since I'm pretty familiar with unit-http, I knew what I needed was the unit-dev package. So, doing (e.g.) apt install unit-dev then npm install unit-http (again) did the trick.

However, I'm wondering if the journey would be that "pleasant" for people new to unit-http? Even maybe they are just users of some other library that has unit-http as a "compulsory peer dependency" (bad setup, I know, still...), and they just need to install unit-http successfully to proceed with their business?

Therefore, I'd wonder if it's possible to slightly improve the DX here a bit? Some proposals poppin' up in my mind are:

1. (somehow) log an instruction so the user knows what to do should this exact error happen. Example: "Cannot install unit-http due to missing dependency, please read more at https://unit.nginx.org/installation/"
2. (somehow) do a system check, and bail out early with a user-friendly error message, so that the user cannot even reach the error state (as seen above)

Or maybe there're other ideas / solutions that we can discuss?

Lastly: I'm happy to help with implementation, too, should this topic come up as a good idea to the community 🙂

Thank you all for your insights & feedback!

[thresheek]

Looking at https://gyp.gsrc.io/docs/UserDocumentation.md I don't really see a way to provide a nicer user message if something fails. Maybe there are some ways that arent immediately cleear though...