Allow arcanist to search for libphutil in externals/includes/

Summary:
In some cases (notably, homebrew) an installer may not control where arcanist/ and libphutil/ live and may not be able to control 'include_path'.

Allow libphutil/ to be symlinked into arcanist/externals/includes/ if all else fails.

Test Plan:
  - Moved `libphutil` to `libphutilx`. Ran "arc" and got a failure.
  - Symlinked it into externals/includes/, ran `arc`, got success.
  - Moved it back to `libphutil`, ran `arc`, success.

Reviewers: vrana, btrahan

Reviewed By: vrana

CC: aran, tfmeusburger

Differential Revision: https://secure.phabricator.com/D3243

.gitignore

@@ -3,3 +3,4 @@
 /src/.phutil_module_cache
 /docs/
 /.divinercache/
+/externals/includes/*

externals/includes/README

@@ -0,0 +1,3 @@
+This directory is added to the PHP include path. You can symlink things here
+if you have control over directory setup but not over PHP configuration (for
+instance, in Homebrew).

scripts/__init_script__.php

@@ -16,15 +16,51 @@
  * limitations under the License.
  */
 
-$include_path = ini_get('include_path');
+/**
+ * Adjust 'include_path' to add locations where we'll search for libphutil.
+ * We look in these places:
+ *
+ *  - Next to 'arcanist/'.
+ *  - Anywhere in the normal PHP 'include_path'.
+ *  - Inside 'arcanist/externals/includes/'.
+ *
+ * When looking in these places, we expect to find a 'libphutil/' directory.
+ */
+function arcanist_adjust_php_include_path() {
 
-$parent_dir = dirname(dirname(dirname(__FILE__)));
+  // The 'arcanist/' directory.
+  $arcanist_dir = dirname(dirname(__FILE__));
+
+  // The parent directory of 'arcanist/'.
+  $parent_dir = dirname($arcanist_dir);
+
+  // The 'arcanist/externals/includes/' directory.
+  $include_dir = implode(
+    DIRECTORY_SEPARATOR,
+    array(
+      $arcanist_dir,
+      'externals',
+      'includes',
+    ));
+
+  $php_include_path = ini_get('include_path');
+  $php_include_path = implode(
+    PATH_SEPARATOR,
+    array(
+      $parent_dir,
+      $php_include_path,
+      $include_dir,
+    ));
+
+  ini_set('include_path', $php_include_path);
+}
+arcanist_adjust_php_include_path();
 
-ini_set('include_path', $parent_dir.PATH_SEPARATOR.$include_path);
 @include_once 'libphutil/scripts/__init_script__.php';
 if (!@constant('__LIBPHUTIL__')) {
-  echo "ERROR: Unable to load libphutil. Update your PHP 'include_path' to ".
+  echo "ERROR: Unable to load libphutil. Put libphutil/ next to arcanist/, or ".
-       "include the parent directory of libphutil/.\n";
+       "update your PHP 'include_path' to include the parent directory of ".
+       "libphutil/, or symlink libphutil/ into arcanist/externals/includes/.\n";
   exit(1);
 }