From 968273445908edae07e5bf24fee22ea4e65ac3cb Mon Sep 17 00:00:00 2001 From: epriestley Date: Thu, 22 Mar 2012 12:06:46 -0700 Subject: [PATCH] Improve arcanist install documentation Summary: See , . - Provide more detailed install instructions. - Provide advice on managing team installs. - Provide information on libphutil path resolution. - Provide OSX-specific documentation. - Update some of the documentation to reflect evolution of the tools. Test Plan: Generated and read documentation. Reviewers: btrahan Reviewed By: btrahan CC: jmhsieh, aran, epriestley Differential Revision: https://secure.phabricator.com/D1990 --- src/docs/userguide/arcanist.diviner | 75 ++++++++++++++++--- src/docs/userguide/arcanist_mac_os_x.diviner | 26 +++++++ .../userguide/arcanist_new_project.diviner | 49 ++++++++++++ 3 files changed, 139 insertions(+), 11 deletions(-) create mode 100644 src/docs/userguide/arcanist_mac_os_x.diviner diff --git a/src/docs/userguide/arcanist.diviner b/src/docs/userguide/arcanist.diviner index bef76eb7e2..a73c6440b3 100644 --- a/src/docs/userguide/arcanist.diviner +++ b/src/docs/userguide/arcanist.diviner @@ -1,11 +1,12 @@ @title Arcanist User Guide @group userguide -Guide to Arcanist, a command-line tool for code review and revision management. +Guide to Arcanist, a command-line interface to Phabricator. -Arcanists glues together several other tools, like Differential and lint. It -also serves as the CLI to Phabricator, and is used to get changesets into -Differential for review. +Arcanists provides command-line access to many Phabricator tools (like +Differential, Files, and Paste), integrates with static analysis ("lint") and +unit tests, and manages common workflows like getting changes into Differential +for review. A detailed command reference is available by running ##arc help##. This document provides a high level overview of common workflows. @@ -30,7 +31,7 @@ Arcanist allows you to do things like: - download a patch from Differential with ##arc export## - update Git commit messages after review with ##arc amend## - commit SVN changes with ##arc commit## - - merge Git and Mercurial changes with ##arc merge## + - push Git changes with ##arc land## - view enhanced information about Git branches with ##arc branch## Once you've configured lint and unit test integration, you can also: @@ -38,6 +39,11 @@ Once you've configured lint and unit test integration, you can also: - check your code for syntax and style errors with ##arc lint## - run unit tests that cover your changes with ##arc unit## +Arcanist integrates with other tools: + + - upload and download files with ##arc upload## and ##arc download## + - create and view pastes with ##arc paste## + Arcanist has some advanced features as well, you can: - execute Conduit method calls with ##arc call-conduit## @@ -53,14 +59,61 @@ SVN repositories. = Installing Arcanist = -Arcanist is meant to be installed on your local machine or development server, -i.e. whatever machine you're editing code on. It runs on Linux and Mac OS X; -To install it, clone it and libphutil off github: +Arcanist is meant to be installed on your local machine or development server -- +whatever machine you're editing code on. It runs on Linux, Mac OS X, and +Windows (see @{article:Arcanist User Guide: Windows}). - somewhere/ $ git clone git://github.com/facebook/libphutil.git - somewhere/ $ git clone git://github.com/facebook/arcanist.git +Arcanist is written in PHP, so you need to install the PHP CLI first if you +don't already have it. Arcanist should run on PHP 5.2 and newer. If you don't +have PHP installed, you can download it from . -Now add ##somewhere/arcanist/bin/arc## to your path. +To install Arcanist, pick an install directory and clone the code from GitHub: + + some_install_path/ $ git clone git://github.com/facebook/libphutil.git + some_install_path/ $ git clone git://github.com/facebook/arcanist.git + +This should leave you with a directory structure like this + + some_install_path/ # Wherever you chose to install it. + arcanist/ # Arcanist-specific code and libraries. + libphutil/ # A shared library Arcanist depends upon. + +Now add ##some_install_path/arcanist/bin/## to your PATH environment variable. +When you type "arc", you should see something like this: + + Usage Exception: No command provided. Try 'arc help'. + +If you get that far, you've done things correctly. If you get an error or have +trouble getting this far, see these detailed guides: + + - On Windows: @{Arcanist User Guide: Windows} + - On Mac OS X: @{Arcanist User Guide: Mac OS X} + +The code changes quickly, so remember to update regularly, by running +`git pull` on the two directories: + + some_install_path/arcanist/ $ git pull + some_install_path/libphutil/ $ git pull + +== Installing Arcanist for a Team == + +Arcanist changes quickly and doesn't currently have an auto-update mechanism, +so it can be something of a headache to get it installed and keep people up to +date. Here are some approaches you might be able to use: + + - Facebook does most development on development servers, which have a standard + environment and NFS mounts. Arcanist and libphutil themselves live on an + NFS mount, and the default `.bashrc` adds them to the PATH. Updating the + mount source updates everyone's versions, and new employees have a working + `arc` when they first log in. + - Another common approach is to write an install script as an action into + existing build scripts, so users can run `make install-arc` or + `ant install-arc` or similar. + - In general, if this sucks and is causing you pain, let us know (see + @{article:Give Feedback! Get Support!}). We're planning to improve this at + some point, but it's somewhat complicated to get right. While it can take a + little time to set up, we aren't getting feedback that it's a persistent + pain point, so it hasn't been a priority. == Installing Tab Completion == diff --git a/src/docs/userguide/arcanist_mac_os_x.diviner b/src/docs/userguide/arcanist_mac_os_x.diviner new file mode 100644 index 0000000000..b8c2fdcc7e --- /dev/null +++ b/src/docs/userguide/arcanist_mac_os_x.diviner @@ -0,0 +1,26 @@ +@title Arcanist User Guide: Mac OS X +@group userguide + +Explains how to install Arcanist on Mac OS X. + += Required Components = + +You need to install: + + - PHP, which should be installed by default. + - Arcanist itself, see @{article:Arcanist User Guide}. + - SVN, Git, or Mercurial. + +Then, configure: + + - Your PATH environmental variable should include `arcanist/bin`, and + `php` and your VCS command (`svn`, `hg`, `git`) should be in PATH. 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 `nano`, which is the best editor. + +You can edit your `~/.profile` to permanently configure environmental variables. + +Now you should be able to run `arc` like a normal command. + diff --git a/src/docs/userguide/arcanist_new_project.diviner b/src/docs/userguide/arcanist_new_project.diviner index 43a1b53c33..11c4c9594a 100644 --- a/src/docs/userguide/arcanist_new_project.diviner +++ b/src/docs/userguide/arcanist_new_project.diviner @@ -50,3 +50,52 @@ Other options include: - **copyright_holder**: used by @{class@arcanist:ArcanistLicenseLinter} to apply license notices to source files. - **phutil_libraries**: map of additional Phutil libraries to load at startup. + See below for details about path resolution, or see + @{article:libphutil Libraries User Guide} for a general introduction to + libphutil libraries. + += How Libraries Are Located = + +If you specify an external library to load, like 'examplelib', and use a +relative path like this: + + { + ... + "load_libraries": { + "examplelib" : "examplelib/src" + }, + ... + } + +...arc looks for it by trying these paths: + + - `path/to/root/examplelib/src/` First, arc looks in the project's root + directory (where the .arcconfig lives) to see if the library is part of + the project. This makes it easy to just put project-specific code in a + project. + - `path/to/root/../examplelib/src/` Next, arc looks //next to// the project's + root directory to see if the library is in a sibling directory. If you + work with several repositories, this makes it easy to put all the `arc` + code in one repository and just check it out in the same directory as + everything else. + - `php/include/path/examplelib/src` Finally, arc falls back to PHP, which + will look in paths described in the `include_path` php.ini setting. This + allows you to install libraries in some global location if you prefer. + +You can alternately supply an absolute path, like `/var/arc/examplelib/src`, but +then everyone will need to install the library at that exact location. + +NOTE: Specify the path to the directory which includes +`__phutil_library_init__.php`. For example, if your init file is in +`examplelib/src/__phutil_library_init__.php`, specify `examplelib/src`, +not just `examplelib/`. + +The general intent here is: + + - Put project-specific code in some directory in the project, like + `support/arc/src/`. + - Put shared code (e.g., which enforces general coding standards or hooks + up to unit tests or whatever) in a separate repository and check it out + next to other repositories. + - Or put everything in some standard location and add it to `include_path`. +