This blog post describes various ways to install PhantomJS, the scriptable headless WebKit, on Mac OS X system (Snow Leopard and Lion), sorted from the most recommended way to the least recommended way.
While the documentation wiki contains a clear explanation on how to start using PhantomJS on Mac OS X, I understand temptation to skip reading something and start doing real stuff. This post thus serves as another safety net for such cases. It also helps to clarify some misunderstanding.
Note that these instructions apply to PhantomJS 1.4 (Glory of the Snow). Future versions may or may not require different steps.
Install the binary package
This is the fastest and easiest way. Go to the download page, find the ZIP file for Mac OS X, then download it. The size is usually around 9 MB so it should be pretty fast. Once it is downloaded, unzip the file (e.g. click on Finder) and that’s it!
It’s recommended to store the executable somewhere in your PATH. Also, the special file Info.plist is needed to avoid the Dock icon from flashing.
Note that the ZIP package is self-contained. You do not need to install Qt beforehand. I repeat: there is no need to install or prepare anything. In other words, the steps mentioned above would work on a fresh (clean) install of Mac OS X.
Always stick to this binary package approach unless there is a strong reason not to do so. It saves you a lot of time.
Compile statically
Building everything manually takes time and effort. Fortunately a convenient build script is included. From the download page, find the source tarball, get it and then extract it. After that:
cd deploy && ./build-mac.sh
What does the script do? It will download Qt 4.8 source code from Nokia web site, extract the tarball, apply some patches, run configure, build Qt statically, and then finally build PhantomJS.
As with the previous approach, the build script has zero dependency. You do not need to compile Qt manually. In fact, run the build script on any Mac OS X system and it should work (of course, you need to have Xcode installed for the compilers, SDK, etc). The download might take a while (since Qt tarball is huge, around 230 MB), thus make sure you are not on a slow Internet connection.
Some patches are applied because of the urgent need, e.g. to prevent QUrl crash, to avoid library confusion, or to allow file upload. There are also others important requirements, see the release notes for details.
The entire build is carried out with 4 (four) simultaneous compile jobs under the assumption that everyone uses a Mac machine with at least hyperthreaded dual-core CPU. On a typical modern machine, the build step lasts for about 30 minutes. Fast hard drive is recommended, but it is not mandatory.
If UPX is detected on the system, the final executable will be compressed. This should significantly reduce the size from 26 MB to just about 10 MB.
Once you are finished with these steps, what you have is a statically built PhantomJS with no external dependency (you should be able to copy it to another machine if needed). In fact, this is exactly what you got as if you follow the first approach (using the binary package).
Use MacPorts or Homebrew
This approach only makes sense if you already have Qt installed, possibly because it is needed by some other applications. Otherwise, running
port install phantomjs
or
brew install phantomjs
will potentially keep your machine busy for hours because it will build the entire Qt library first. With Homebrew, it’s not so bad because Bottle likely save the time.
While the end result might look the same, there are two important differences compared to the second approach. First, the convenient static build script build-mac.sh only compiles the necessary parts of Qt needed for PhantomJS. For example, it skips building the examples, demos, tools, etc. This cuts the overall time. Second, since MacPorts and Homebrew builds the vanilla Qt, some problems which are solved by patching (see the second approach) might arise.
Keep the above differences into account to avoid future headache.
Update: PhantomJS Homebrew formula has been updated so it will install the same exact binary like in the first two approaches. If you already have Homebrew, this is easy and fast, so go ahead and brew install phantomjs and enjoy!