arcanist_windows.diviner

@title Arcanist User Guide: Windows
@group userguide

Explains how to install Arcanist on Windows.

= Overview =

Arcanist runs on Windows, either in `cmd.exe` or the Git Bash environments.
However, it will take a little effort to get working. This document explains
what you need to do in order to get it running.

NOTE: Windows support is relatively new and incomplete, file bugs when you run
into issues.

= Required Components =

You need to install:

  - Arcanist itself, see @{article:Arcanist User Guide}.
  - PHP (see "Detailed PHP Install Instructions" below).
  - SVN, Git, or Mercurial.

Then, configure:

  - Your PATH environmental variable should include `arcanist/bin`, the `php`
    directory, and the directory where your VCS command lives. When you type
    `php`, `arc`, or (for example) `git` from the command line, they should all
    do something.
  - Your EDITOR environmental variable should point at some valid CLI editor,
    like the Git Bash `vim`. You can set this in `arc` if you prefer.
    See below for details.

You can set environmental variables somewhere in the `Advanced` tab of the
`System` control panel.

Now you should be able to run `arc` normally (either from `cmd.exe` or
Git Bash) and it should work more-or-less properly.

= Configuring an Editor =

NOTE: You **can not** use Notepad as your editor, because it does not have a
blocking mode. You can use GitPad instead.

Some arc workflows prompt you to edit large blocks of text using a text editor.
You can configure various programs for this purpose, depending on which text
editor you prefer. Some editors that will work are:

  - [[ http://notepad-plus-plus.org/ | Notepad++ ]], a good all-around editor.
  - **vim**, which comes with Git Bash.
  - [[ https://github.com/github/gitpad | GitPad ]], which allows you to use
    Notepad as your editor.

Other editors may also work, but they must have a blocking edit mode.

To configure an editor, either set the `EDITOR` environmental variable to point
at it, or run:

  $ arc set-config editor "\"C:\path\to\some\editor.exe\""

NOTE: Note the use of quotes. Paths with spaces in them must be quoted, and
these quotes must be escaped when passed to `arc set-config`, as in the examples
below.

Specifically, you can use this command for **Notepad++** (adjusting the path for
your machine):

  name=Notepad++
  $ arc set-config editor "\"C:\Program Files (x86)\Notepad++\notepad++.exe\" -multiInst -nosession"

And this command for Vim (you may need to adjust the path):

  name=vim
  $ arc set-config editor "\"C:\Program Files (x86)\Git\share\vim\vim73\vim.exe\""

And this for GitPad (you may need to adjust the path):

  name=GitPad
  $ arc set-config editor "\"C:\Users\yourusername\AppData\Roaming\GitPad\GitPad.exe\""

= Detailed PHP Install Instructions =

While multiple versions of PHP should work, you can follow these specific
instructions if you're having trouble.

  - Download the latest stable PHP binary release from:
    <http://windows.php.net/download/>. When this document was last
    updated, this was PHP 5.4.6, but newer versions should also work. The
    "VC9 x86 Non Thread Safe" build should work correctly. (Other versions newer
    than PHP 5.3 should work, and thread-safe versions should also work.)
  - Unzip the PHP directory.
  - Copy `php.ini-development` to `php.ini` in that same directory.
  - Open `php.ini` and locate the line `;extension=php_curl.dll`. Remove the
    `;` to activate this extension. Locate the line `; extension_dir = "ext"`
    and change it to `; extension_dir = "C:\PHP\ext"`, where `C:\PHP` is
    the directory where you installed PHP.
  - Verify that things work by running `php -i` from your commandline and
    looking for `curl` in the output.

= Next Steps =

Continue by:

  - returning to @{article:Arcanist User Guide}.