Why I hate node-gyp

Today I had to install a node module of mine in a sandboxed environment (i.e. isolated from the system directories) and due to node-gyp what usually is just a matter of time turned into a nightmare.


 Prove me wrong, I hate node-gyp because:

• It is poorly documented  

Where is the documentation for the binding.gyp? Seriously, just few examples ?...

What I would be pleased to see is a node-gyp binding.gyp how-to for _make_ users. Other people would like to see the same kind of one to one mapping for other tools like Xcode, cmake, whatever...

• Counter intuitive from a Unix user point of view. 

 It's more or less the continuation of my first point. Where do the linker flags go ? where do the include paths go ? It's all a nightmare to find out what is the exact JSON option and also it's key path within the whole hash's organization.

• Inexistant help 

 Go ahead and type 'node-gyp' alone in a shell. It outputs this usage message:

$ node-gyp

  Usage: node-gyp <command> [options]

  where  is one of:
    - build - Invokes `make` and builds the module
    - clean - Removes any generated build files and the "out" dir
    - configure - Generates a Makefile for the current module
    - rebuild - Runs "clean", "configure" and "build" all at once
    - install - Install node development files for the specified node version.
    - list - Prints a listing of the currently installed node development files
    - remove - Removes the node development files for the specified version

  for specific command usage and options try:
    $ node-gyp <command> --help

ok now, go ahead and try to get some specific help on build or configure commands:

$ node-gyp configure --help
gyp info it worked if it ends with ok
gyp info using node-gyp@0.8.5
gyp info using node@0.8.21 | darwin | x64
gyp info spawn python
...

No help! I told you... Not to say that it is very unpleasant to see it doing a work we didn't order.

So why did I even bother to criticize this tool if I don't like it. Well first of all, I'm using node.js a lot these days and find it rather pleasing. And since this tool is kind of mandatory when it comes to deal with compiled modules I'm thinking it could be useful to yell a bit at it as it will be more and more widely used. Don't get me wrong I'm not criticizing for criticizing I'm doing it because I may be wrong so prove me wrong else I hope the developers will do the necessary changes in code and documentation so that it catches up the coolness of node.js.

By the way, the versions I was using are: node-gyp@0.8.5 and node@0.8.21

Cheers.