Bug 1526946 - provide clearer O/S specific install instructions r=sma…

…cleod

Differential Revision: https://phabricator.services.mozilla.com/D20158

.gitignore

@@ -1 +1,2 @@
 _build
+venv

arcanist-linux.rst

@@ -0,0 +1,84 @@
+#################################
+Linux Arcanist Installation Guide
+#################################
+
+Arcanist and moz-phab can be installed into any location on your system, as
+long as the ``arc`` and ``moz-phab`` commands work from your command line.
+
+In this guide we'll be installing arc and moz-phab into ``~/.mozbuild``,
+however they can be installed into any reasonable location.
+
+Ensure PHP and git are installed
+--------------------------------
+
+Verify that both php and git are installed and working when run from the
+command line:
+
+.. code-block:: bash
+
+    $ git --version
+    git version 2.20.1
+    $ php --version
+    PHP 7.1.23 (cli) (built: Nov  7 2018 18:20:35) ( NTS )
+
+The versions you have do not need match the above.
+
+If either are missing use your distro's package manager to install.  For example
+if you use Ubuntu:
+
+.. code-block:: bash
+
+    sudo apt-get install php php-curl git
+
+Note Arcanist requires the ``ext-curl`` PHP extension, which is provied by
+the ``php-curl`` package on Ubuntu.
+
+
+Install Arcanist
+----------------
+
+#. Create a ``~/.mozbuild`` directory if it doesn't already exist and clone the
+   arcanist and phabricator library repositories:
+
+.. code-block:: bash
+
+    mkdir -p ~/.mozbuild
+    cd ~/.mozbuild
+    git clone https://github.com/phacility/arcanist.git
+    git clone https://github.com/phacility/libphutil.git
+
+
+Install moz-phab
+----------------
+
+#. Create a ``~/.mozbuild/moz-phab`` directory and download the latest version of
+   ``moz-phab``:
+
+.. code-block:: bash
+
+    mkdir -p ~/.mozbuild/moz-phab
+    cd ~/.mozbuild/moz-phab
+    curl -O https://raw.githubusercontent.com/mozilla-conduit/review/$(basename $(curl -sLo /dev/null -w '%{url_effective}' https://github.com/mozilla-conduit/review/releases/latest))/moz-phab
+    chmod +x moz-phab
+
+Add arc and moz-phab to your PATH
+---------------------------------
+
+Both `arc` and `moz-phab` need to be on the PATH in order for the scripts to
+work. Be aware the profile file varies between distros and shells
+(eg. ``~/.bashrc`` instead of ``~/.profile``)
+
+1. Update your ``PATH`` to include arcanist and moz-phab:
+
+.. code-block:: bash
+
+    echo 'export PATH="$HOME/.mozbuild/arcanist/bin:$HOME/.mozbuild/moz-phab:$PATH"' >> ~/.profile
+
+2. Close and reopen your terminal program
+
+3. Ensure running `arc` and `moz-phab` both work:
+
+.. code-block:: bash
+
+    arc -h
+    moz-phab -h

arcanist-macos.rst

@@ -0,0 +1,59 @@
+#################################
+macOS Arcanist Installation Guide
+#################################
+
+Arcanist and moz-phab can be installed into any location on your system, as
+long as the ``arc`` and ``moz-phab`` commands work from your command line.
+
+These steps require both git and php, which happily are preinstalled on macOS.
+
+In this guide we'll be installing arc and moz-phab into ``~/.mozbuild``,
+however they can be installed into any reasonable location.
+
+Install Arcanist
+----------------
+
+#. Create a ``~/.mozbuild`` directory if it doesn't already exist and clone the
+   arcanist and phabricator library repositories:
+
+.. code-block:: bash
+
+    mkdir -p ~/.mozbuild
+    cd ~/.mozbuild
+    git clone https://github.com/phacility/arcanist.git
+    git clone https://github.com/phacility/libphutil.git
+
+
+Install moz-phab
+----------------
+
+#. Create a ``~/.mozbuild/moz-phab`` directory and download the latest version of
+   ``moz-phab``:
+
+.. code-block:: bash
+
+    mkdir -p ~/.mozbuild/moz-phab
+    cd ~/.mozbuild/moz-phab
+    curl -O https://raw.githubusercontent.com/mozilla-conduit/review/$(basename $(curl -sLo /dev/null -w '%{url_effective}' https://github.com/mozilla-conduit/review/releases/latest))/moz-phab
+    chmod +x moz-phab
+
+Add arc and moz-phab to your PATH
+---------------------------------
+
+Both `arc` and `moz-phab` need to be on the PATH in order for the scripts to
+work.
+
+1. Update your ``PATH`` to include arcanist and moz-phab:
+
+.. code-block:: bash
+
+    echo 'export PATH="$HOME/.mozbuild/arcanist/bin:$HOME/.mozbuild/moz-phab:$PATH"' >> ~/.bashrc
+
+2. Close and reopen your terminal program
+
+3. Ensure running `arc` and `moz-phab` both work:
+
+.. code-block:: bash
+
+    arc -h
+    moz-phab -h

arcanist-windows.rst

@@ -1,6 +1,6 @@
-###################################
-Windows Arcanist Installation Guide
-###################################
+######################################
+Windows 10 Arcanist Installation Guide
+######################################
 
 The `official Windows installation guide
 <https://secure.phabricator.com/book/phabricator/article/arcanist_windows/>`_

index.rst

@@ -28,6 +28,8 @@ Table of Contents
    lando-user
    walkthrough
    arcanist-windows
+   arcanist-linux
+   arcanist-macos
    arcanist-user
    mozreview-migration-guide
    contributing

phabricator-user.rst

@@ -12,9 +12,8 @@ stock Phabricator, much of `Phabricator's user documentation
 applicable.  Several sections are of particular interest.
 
 **Arcanist** is the command-line interface to Phabricator, mainly used
-to submit patches for review.  There is an `Arcanist Quick Start guide
-<https://phabricator.services.mozilla.com/book/phabricator/article/arcanist_quick_start/>`_,
-a larger `Arcanist User Guide
+to submit patches for review.  After `setting up Arcanist`_ you can
+read the `Arcanist User Guide
 <https://phabricator.services.mozilla.com/book/phabricator/article/arcanist/>`_,
 and a specific `guide to "arc diff"
 <https://phabricator.services.mozilla.com/book/phabricator/article/arcanist_diff/>`_
@@ -112,9 +111,13 @@ our custom command-line tool, `moz-phab
 official tool, Arcanist.  ``moz-phab`` currently requires Arcanist, so you
 will likely need to install it to use Phabricator.
 
-Installing the tool depends on your operating system.  For Windows 10,
-we have our own :doc:`installation guide </arcanist-windows>`.  For
-other OSes, see the official `Arcanist Quick Start guide
+Installing the tool depends on your operating system:
+
+* :doc:`Windows 10 Arcanist Installation Guide </arcanist-windows>`
+* :doc:`Linux Arcanist Installation Guide </arcanist-linux>`
+* :doc:`macOS Arcanist Installation Guide </arcanist-macos>`
+
+You can also read see the official `Arcanist Quick Start guide
 <https://phabricator.services.mozilla.com/book/phabricator/article/arcanist_quick_start/>`_.
 Note that in Windows 10, you can use the Linux-based instructions if
 you are running the `Windows Subsystem for Linux
@@ -125,20 +128,6 @@ you will need to use our `fork of Arcanist <https://github.com/mozilla-conduit/a
 which maps SHAs from Git to Mercurial so that patches can be correctly
 applied locally regardless of the VCS from which they were submitted.
 
-On Ubuntu, you will need PHP and an extension installed: ``sudo apt
-install php php-curl``.  Then clone the Arcanist repos as described in
-the Quick Start guide linked above, and add the ``arcanist/bin/``
-directory to your path.  Note that you can also install the Arcanist
-apt package, but you may not get recent fixes and improvements.
-
-If your project does not currently have a ``.arcconfig`` checked into
-the its repository, you can create one locally, which should look like
-this::
-
-    {
-      "phabricator.uri" : "https://phabricator.services.mozilla.com/"
-    }
-
 The next step is to authenticate Arcanist with our Phabricator
 installation.  From within your project's repository, run the
 following command::