--- /dev/null
+phantomjs-prebuilt
+==================
+
+An NPM installer for [PhantomJS](http://phantomjs.org/), headless webkit with JS API.
+
+[](https://travis-ci.org/Medium/phantomjs)
+
+Building and Installing
+-----------------------
+
+```shell
+npm install phantomjs-prebuilt
+```
+
+Or grab the source and
+
+```shell
+node ./install.js
+```
+
+What this installer is really doing is just grabbing a particular "blessed" (by
+this module) version of Phantom. As new versions of Phantom are released
+and vetted, this module will be updated accordingly.
+
+Running
+-------
+
+```shell
+bin/phantomjs [phantom arguments]
+```
+
+And npm will install a link to the binary in `node_modules/.bin` as
+it is wont to do.
+
+Running via node
+----------------
+
+The package exports a `path` string that contains the path to the
+phantomjs binary/executable.
+
+Below is an example of using this package via node.
+
+```javascript
+var path = require('path')
+var childProcess = require('child_process')
+var phantomjs = require('phantomjs-prebuilt')
+var binPath = phantomjs.path
+
+var childArgs = [
+ path.join(__dirname, 'phantomjs-script.js'),
+ 'some other argument (passed to phantomjs script)'
+]
+
+childProcess.execFile(binPath, childArgs, function(err, stdout, stderr) {
+ // handle results
+})
+
+```
+
+Or `exec()` method is also provided for convenience:
+
+```javascript
+var phantomjs = require('phantomjs-prebuilt')
+var program = phantomjs.exec('phantomjs-script.js', 'arg1', 'arg2')
+program.stdout.pipe(process.stdout)
+program.stderr.pipe(process.stderr)
+program.on('exit', code => {
+ // do something on end
+})
+```
+
+Note: [childProcess.spawn()](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) is called inside `exec()`.
+
+Running with WebDriver
+----------------------
+
+`run()` method detects when PhantomJS gets ready. It's handy to use with WebDriver (Selenium).
+
+```javascript
+var phantomjs = require('phantomjs-prebuilt')
+var webdriverio = require('webdriverio')
+var wdOpts = { desiredCapabilities: { browserName: 'phantomjs' } }
+
+phantomjs.run('--webdriver=4444').then(program => {
+ webdriverio.remote(wdOpts).init()
+ .url('https://developer.mozilla.org/en-US/')
+ .getTitle().then(title => {
+ console.log(title) // 'Mozilla Developer Network'
+ program.kill() // quits PhantomJS
+ })
+})
+```
+
+Versioning
+----------
+
+The major and minor number tracks the version of PhantomJS that will be
+installed. The patch number is incremented when there is either an installer
+update or a patch build of the phantom binary.
+
+Pre-2.0, this package was published to NPM as [phantomjs](https://www.npmjs.com/package/phantomjs).
+We changed the name to [phantomjs-prebuilt](https://www.npmjs.com/package/phantomjs-prebuilt) at
+the request of PhantomJS team.
+
+Continuous Integration
+----------------------
+
+Please **do not** download PhantomJS for every CI job because it can quickly
+overload our CDNs. Instead take advantage of CI caching.
+
+In [Travis-CI](https://travis-ci.org/) add the following to your `.travis.yml`
+to [enable caching](https://docs.travis-ci.com/user/caching/) & avoid repeated
+downloads of PhantomJS.
+
+#### .travis.yml
+```yml
+cache:
+ directories:
+ - travis_phantomjs
+
+before_install:
+ # Upgrade PhantomJS to v2.1.1.
+ - "export PHANTOMJS_VERSION=2.1.1"
+ - "export PATH=$PWD/travis_phantomjs/phantomjs-$PHANTOMJS_VERSION-linux-x86_64/bin:$PATH"
+ - "if [ $(phantomjs --version) != $PHANTOMJS_VERSION ]; then rm -rf $PWD/travis_phantomjs; mkdir -p $PWD/travis_phantomjs; fi"
+ - "if [ $(phantomjs --version) != $PHANTOMJS_VERSION ]; then wget https://github.com/Medium/phantomjs/releases/download/v$PHANTOMJS_VERSION/phantomjs-$PHANTOMJS_VERSION-linux-x86_64.tar.bz2 -O $PWD/travis_phantomjs/phantomjs-$PHANTOMJS_VERSION-linux-x86_64.tar.bz2; fi"
+ - "if [ $(phantomjs --version) != $PHANTOMJS_VERSION ]; then tar -xvf $PWD/travis_phantomjs/phantomjs-$PHANTOMJS_VERSION-linux-x86_64.tar.bz2 -C $PWD/travis_phantomjs; fi"
+ - "phantomjs --version"
+```
+
+Deciding Where To Get PhantomJS
+-------------------------------
+
+By default, this package will download phantomjs from our [releases](https://github.com/Medium/phantomjs/releases/).
+This should work fine for most people.
+
+##### Downloading from a custom URL
+
+If github is down, or the Great Firewall is blocking github, you may need to use
+a different download mirror. To set a mirror, set npm config property `phantomjs_cdnurl`.
+
+Alternatives include `https://bitbucket.org/ariya/phantomjs/downloads` (the official download site)
+and `http://cnpmjs.org/downloads`.
+
+```Shell
+npm install phantomjs-prebuilt --phantomjs_cdnurl=https://bitbucket.org/ariya/phantomjs/downloads
+```
+
+Or add property into your `.npmrc` file (https://www.npmjs.org/doc/files/npmrc.html)
+
+```
+phantomjs_cdnurl=https://bitbucket.org/ariya/phantomjs/downloads
+```
+
+Another option is to use PATH variable `PHANTOMJS_CDNURL`.
+```shell
+PHANTOMJS_CDNURL=https://bitbucket.org/ariya/phantomjs/downloads npm install phantomjs
+```
+
+##### Using PhantomJS from disk
+
+If you plan to install phantomjs many times on a single machine, you can
+install the `phantomjs` binary on PATH. The installer will automatically detect
+and use that for non-global installs.
+
+Cross-Platform Repositories
+---------------------------
+
+PhantomJS needs to be compiled separately for each platform. This installer
+finds a prebuilt binary for your operating system, and downloads it.
+
+If you check your dependencies into git, and work on a cross-platform
+team, then you need to tell NPM to rebuild any platform-specific dependencies. Run
+
+```shell
+npm rebuild
+```
+
+as part of your build process. This problem is not specific to PhantomJS, and this
+solution will work for any NodeJS package with native or platform-specific code.
+
+If you know in advance that you want to install PhantomJS for a specific architecture,
+you can set the environment variables: `PHANTOMJS_PLATFORM`
+(to set target platform) and `PHANTOMJS_ARCH` (to set target
+arch), where `platform` and `arch` are valid values for
+[process.platform and process.arch](https://nodejs.org/api/process.html).
+
+A Note on PhantomJS
+-------------------
+
+PhantomJS is not a library for NodeJS. It's a separate environment and code
+written for node is unlikely to be compatible. In particular PhantomJS does
+not expose a Common JS package loader.
+
+This is an _NPM wrapper_ and can be used to conveniently make Phantom available.
+It is not a Node JS wrapper.
+
+I have had reasonable experiences writing standalone Phantom scripts which I
+then drive from within a node program by spawning phantom in a child process.
+
+Read the PhantomJS FAQ for more details: http://phantomjs.org/faq.html
+
+### Linux Note
+
+An extra note on Linux usage, from the PhantomJS download page:
+
+ > There is no requirement to install Qt, WebKit, or any other libraries. It
+ > however still relies on Fontconfig (the package fontconfig or libfontconfig,
+ > depending on the distribution).
+
+Troubleshooting
+---------------
+
+##### Installation fails with `spawn ENOENT`
+
+This is NPM's way of telling you that it was not able to start a process. It usually means:
+
+- `node` is not on your PATH, or otherwise not correctly installed.
+- `tar` is not on your PATH. This package expects `tar` on your PATH on Linux-based platforms.
+- `bzip2` is not on your PATH.
+
+Check your specific error message for more information.
+
+##### Installation fails with `Error: EPERM` or `operation not permitted` or `permission denied`
+
+This error means that NPM was not able to install phantomjs to the file system. There are three
+major reasons why this could happen:
+
+- You don't have write access to the installation directory.
+- The permissions in the NPM cache got messed up, and you need to run `npm cache clean` to fix them.
+- You have over-zealous anti-virus software installed, and it's blocking file system writes.
+
+##### Installation fails with `Error: read ECONNRESET` or `Error: connect ETIMEDOUT`
+
+This error means that something went wrong with your internet connection, and the installer
+was not able to download the PhantomJS binary for your platform. Please try again.
+
+##### I tried again, but I get `ECONNRESET` or `ETIMEDOUT` consistently.
+
+Do you live in China, or a country with an authoritarian government? We've seen problems where
+the GFW or local ISP blocks github, preventing the installer from downloading the binary.
+
+Try visiting [the download page](https://bitbucket.org/ariya/phantomjs/downloads) manually.
+If that page is blocked, you can try using a different CDN with the `PHANTOMJS_CDNURL`
+env variable described above.
+
+##### I am behind a corporate proxy that uses self-signed SSL certificates to intercept encrypted traffic.
+
+You can tell NPM and the PhantomJS installer to skip validation of ssl keys with NPM's
+[strict-ssl](https://www.npmjs.org/doc/misc/npm-config.html#strict-ssl) setting:
+
+```
+npm set strict-ssl false
+```
+
+WARNING: Turning off `strict-ssl` leaves you vulnerable to attackers reading
+your encrypted traffic, so run this at your own risk!
+
+##### I tried everything, but my network is b0rked. What do I do?
+
+If you install PhantomJS manually, and put it on PATH, the installer will try to
+use the manually-installed binaries.
+
+##### I'm on Debian or Ubuntu, and the installer failed because it couldn't find `node`
+
+Some Linux distros tried to rename `node` to `nodejs` due to a package
+conflict. This is a non-portable change, and we do not try to support this. The
+[official documentation](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager#ubuntu-mint-elementary-os)
+recommends that you run `apt-get install nodejs-legacy` to symlink `node` to `nodejs`
+on those platforms, or many NodeJS programs won't work properly.
+
+##### I'm using an unsupported version of Linux or an ARM processor. I get errors about "Unexpected platform or architecture". What do I do?
+
+We only have binaries available for common OS / processor configurations. Sorry.
+
+You may be able to get a PhantomJS binary from your operating system's package
+manager. Or you can build your own from source. If you put that binary on PATH,
+this installer will use it (see "Deciding Where to Get PhantomJS" above).
+
+
+Contributing
+------------
+
+Questions, comments, bug reports, and pull requests are all welcome. Submit them at
+[the project on GitHub](https://github.com/Medium/phantomjs/). If you haven't contributed to an
+[Medium](http://github.com/Medium/) project before please head over to the
+[Open Source Project](https://github.com/Medium/open-source#note-to-external-contributors) and fill
+out an OCLA (it should be pretty painless).
+
+Bug reports that include steps-to-reproduce (including code) are the
+best. Even better, make them in the form of pull requests.
+
+Author
+------
+
+[Dan Pupius](https://github.com/dpup)
+([personal website](http://pupius.co.uk)) and
+[Nick Santos](https://github.com/nicks), supported by
+[A Medium Corporation](http://medium.com/).
+
+License
+-------
+
+Copyright 2012 [A Medium Corporation](http://medium.com/).
+
+Licensed under the Apache License, Version 2.0.
+See the top-level file `LICENSE.txt` and
+(http://www.apache.org/licenses/LICENSE-2.0).
projects / yaffs-website / blobdiff