Grunt, or 'The Joys of Node Under Ubuntu'

If you want to install Grunt, you'll need node.js and npm (the Node Package Manager). Your path diverges rather impressively depending on your platform.

Mac

brew install node (as a user with admin privileges ... and obviously you need Homebrew) - this installs node and npm, and you're done. Although it wouldn't be a bad idea to run npm update -g npm to do a global update (ie. not just in your account) of npm itself.

Debian

apt-get update; apt-get install nodejs. You should be done, but you're not. The binary installed on Debian is /usr/bin/nodejs, and there's no link or anything under the node name, which is bad because everything (and I mean EVERYTHING) you'll install that's associated with Node.js expects the binary to be called node.

There turns out to be a reason for this, but the choice of resolution implemented by the Debian team is kind of along the lines of "foot - gun - aim ..." There's another Debian package:

Amateur Packet Radio Node program

The node program accepts TCP/IP and packet radio network connections and
presents users with an interface that allows them to make gateway connections
to remote hosts using a variety of amateur radio protocols.

They had a binary called "node" too. So Debian's solution (https://lists.debian.org/debian-devel-announce/2012/07/msg00002.html , https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=614907 ) was "nobody gets to have a binary called 'node,' even if only one of the packages is installed." Brilliant! So the solution, which is totally not clear without doing at least some of the reading I've just pointed out and apparently undescribed by Debian, is to create a soft-link to the /usr/bin/nodejs binary the package provides with the expected name of /usr/bin/node. The whole point of using the package management system is to have system packages managed by the package manager, but we're forced to do modify the system ourselves in an unexpected way and that link will live on even if we uninstall the "nodejs" package. So Debian's "solution" ensures that the two packages don't conflict ... and that neither works as expected.

Ubuntu

(this is for Ubuntu 14.04)

apt-get update; apt-get install nodejs npm - on most platforms, npm is packaged and installed with node.js. But while they've changed the nodejs package from Debian's default behaviour, they haven't fixed the lack of a link to node, so (just like Debian) you have to run ln -s /usr/bin/nodejs /usr/bin/node. Read the very ugly explanation above.

Installing Grunt

I had better luck doing this in two steps (as root on a Linux system, or an account with admin privileges on a Mac): npm install -g grunt-cli followed by npm install -g grunt. On a Linux system, that installs about 19M of dependencies under /usr/local/lib/node_modules/.

Typing grunt at the command line should produce the following:

$ grunt
A valid Gruntfile could not be found. Please see the getting started guide for
more information on how to configure grunt: http://gruntjs.com/getting-started
Fatal error: Unable to find Gruntfile.

If instead you see this:

$ grunt
grunt-cli: The grunt command line interface (v1.2.0)

Fatal error: Unable to find local grunt.

If you're seeing this message, grunt hasn't been installed locally to
your project. For more information about installing and configuring grunt,
please see the Getting Started guide:

http://gruntjs.com/getting-started

It would appear to indicate that grunt-cli is installed, but unable to find the grunt package. On most systems, npm install -g grunt should be sufficient, but the command is still failing on Ubuntu.

The Grunt "Getting Started" page says this:

Note that installing grunt-cli does not install the Grunt task runner! The
job of the Grunt CLI is simple: run the version of Grunt which has been
installed next to a Gruntfile. This allows multiple versions of Grunt to be
installed on the same machine simultaneously.

A Passel of Problems with Ubuntu

With both the Mac and Debian OS, everything got configured as expected and grunt appears to be working at the command line. Under Ubuntu 14.04, running npm install -g grunt and then npm install -g grunt-cli as root installed a lot of stuff in /usr/local/lib/node_modules/, and it linked the grunt executable under /usr/local/bin/grunt, but nothing else is linked and running npm list shows that npm has no awareness that it's installed anything. I'm still sorting this out: I'll try to update this later.

Running npm install grunt-cli ; npm install grunt as a user (note the lack of -g) seems to have solved the problem. I now have a 19M ~/node_modules/ folder in my home directory, but grunt seems to be behaving and npm knows about the packages that the user installed. I suspect user package installation is supposed to be done on a per-project-folder basis, but this is a start.

Bibliography