Merge branch 'master' into load-db

README.md

@@ -28,7 +28,7 @@ $> composer require palantirnet/the-build
 Install the default `build.xml` to your project:
 
 ```sh
-$> vendor/bin/phing -f vendor/palantirnet/the-build/tasks/install.xml
+$> vendor/bin/the-build-installer
 ```
 
 This will trigger an interactive prompt to configure your basic build properties, adding the following boilerplate files:
@@ -41,3 +41,6 @@ Manually review these files, then check them in to your project. At this point,
 ```sh
 $> vendor/bin/phing build install migrate
 ```
+
+----
+Copyright 2016 Palantir.net, Inc.

bin/the-build-installer

@@ -0,0 +1,20 @@
+#!/bin/sh
+#
+# Wrapper for our install command; at least this way it's somewhat discoverable.
+# Previously:
+#   vendor/bin/phing -f vendor/palantirnet/the-build/tasks/install.xml
+
+# Relative path to this script.
+SCRIPT=$(readlink "$0")
+
+# Absolute path to this script's parent directory.
+SCRIPTPATH=$(cd `dirname $0` && cd `dirname $SCRIPT` && pwd)
+
+REPOPATH=$(cd `dirname $SCRIPTPATH` && cd ../../../ && pwd)
+
+if [ "$REPOPATH" = `pwd` ]; then
+  # Run our install task.
+  $SCRIPTPATH/../../../bin/phing -f $SCRIPTPATH/../tasks/install.xml
+else
+  echo "Please run this command from your project root."
+fi

composer.json

@@ -1,19 +1,28 @@
 {
     "name": "palantirnet/the-build",
-    "description": "Drupal build tasks for our projects.",
-    "license": "proprietary",
+    "description": "Phing build tasks for Drupal projects.",
+    "license": "GPL-2.0+",
+    "copyright": "Copyright 2016 Palantir.net, Inc.",
     "authors": [
         {
             "name": "Palantir.net",
             "email": "[email protected]"
         }
     ],
+    "bin": [
+        "bin/the-build-installer"
+    ],
     "require": {
         "phing/phing": "^2.14",
         "continuousphp/phing-drush-task": "dev-master",
         "drupal/coder": "^8.2",
         "phpmd/phpmd" : "^2.4",
         "nilportugues/php_todo": "^1.0",
         "pear/versioncontrol_git": "@dev"
+    },
+    "autoload": {
+        "psr-0": {
+            "TheBuild\\": "src/"
+        }
     }
 }

docs/code_review.md

@@ -51,3 +51,6 @@ Sets a threshold for the number of "to do" comments allowable in a codebase. The
 ```
 phptodo.config=conf/php_todo_finder.yml
 ```
+
+----
+Copyright 2016 Palantir.net, Inc.

docs/properties.md

@@ -34,6 +34,8 @@ Cool! This phing-ism is what powers our environment-specific property layering a
 |---|---|---|
 | `build.artifact_mode` | `symlink` | Whether to `symlink` or `copy` assets like CSS, JS, and other code during the build. |
 | `build.test_output` | `/dev/null` | Where to output reports from tests. On Circle, try `${env.CIRCLE_TEST_REPORTS}`. |
+| `build.drupal.settings` | `conf/drupal/settings.php` | Source template for Drupal's `settings.php` file. |
+| `build.drupal.services` | `conf/drupal/services.yml` | Source template for Drupal's `services.yml` file. |
 
 
 ### Drupal
@@ -53,6 +55,8 @@ Cool! This phing-ism is what powers our environment-specific property layering a
 | `drupal.uri` | `http://drupal.local` | Your site's URI; the default may be the URI of your local development environment. |
 | `drupal.hash_salt` | `temporary` | Salt for Drupal's password hashing. A unique salt is generated when you install `the-build`. |
 | `drupal.root` | `web` | Relative path to the Drupal web root. This is co-dependent with the composer installer configuration in your `composer.json`. Changing this will probably cause problems. |
+| `drupal.sites_subdir` | `default` | Name of the sites subdirectory where the `settings.php` file should live. |
+| `drupal.admin_user` | `admin` | Drupal admin username, if you feel inclined to change it. |
 
 [More info](../tasks/drupal.xml#L16-L38)
 
@@ -99,3 +103,6 @@ Example usage:
 ```
 
 [More info](../tasks/lib/db.xml)
+
+----
+Copyright 2016 Palantir.net, Inc.

docs/tasks.md

@@ -0,0 +1,23 @@
+# Custom Tasks
+
+## IncludeResourceTask [🔗](../src/TheBuild/IncludeResourceTask.php)
+
+Copies or symlinks a file or directory within your project.
+
+### Attributes
+
+| Name | Type | Description | Default | Required |
+|---|---|---|---|---|
+| mode | string | Either `copy` or `symlink`. Inherited from `build.artifact_mode` if available. | `symlink` | No |
+| source | string | Path to the resource. | n/a | Yes |
+| dest | string | Path where the resource should be included in your build. | n/a | Yes |
+
+### Examples
+
+```xml
+<!-- Copy generated CSS into your theme. -->
+<includeresource mode="copy" source="styleguide/src/content/assets/css" dest="web/themes/custom/my_theme/css" />
+
+<!-- Use build properties to include a JS library in your Drupal libraries directory -->
+<includeresource mode="${build.artifact_mode}" source="vendor/foo/somelibrary" dest="${drupal.root}/libraries/somelibrary" />
+```

src/TheBuild/IncludeResourceTask.php

@@ -0,0 +1,121 @@
+<?php
+/**
+ * @file IncludeResourceTask.php
+ *
+ * @copyright 2016 Palantir.net, Inc.
+ */
+
+namespace TheBuild;
+
+use PhingFile;
+use BuildException;
+use FileSystem;
+
+
+class IncludeResourceTask extends \Task {
+
+  /**
+   * @var string
+   * Either 'symlink' or 'copy'.
+   */
+  protected $mode = 'symlink';
+
+  /**
+   * @var PhingFile
+   * The source file or directory to include.
+   */
+  protected $source;
+
+  /**
+   * @var PhingFile
+   * The location to link the file to.
+   */
+  protected $dest = NULL;
+
+
+  /**
+   * Init tasks.
+   *
+   * Inherits the mode from the project's build.artifact_mode property. This
+   * can be overridden by setting the "mode" attribute.
+   */
+  public function init() {
+    $this->setMode($this->getProject()->getProperty('build.artifact_mode'));
+  }
+
+
+  /**
+   * Copy or link the resource.
+   */
+  public function main() {
+    $this->validate();
+
+    // Remove existing destination first.
+    if ($this->dest->exists()) {
+      $this->log("Replacing existing resource '" . $this->dest->getPath() . "'");
+
+      if ($this->dest->delete(TRUE) === FALSE) {
+        throw new BuildException("Failed to delete existing destination '$this->dest'");
+      }
+    }
+
+    // Link or copy the source artifact.
+    if ($this->mode == 'copy') {
+      $this->log(sprintf("Copying '%s' to '%s'", $this->source->getPath(), $this->dest->getPath()));
+      $this->source->copyTo($this->dest);
+    }
+    else {
+      $this->log(sprintf("Linking '%s' to '%s'", $this->source->getPath(), $this->dest->getPath()));
+      FileSystem::getFileSystem()->symlink($this->source->getPath(), $this->dest->getPath());
+    }
+  }
+
+
+  /**
+   * Verify that the required attributes are set.
+   */
+  public function validate() {
+    if (empty($this->source) || empty($this->dest)) {
+      throw new BuildException("Both the 'source' and 'dest' attributes are required.");
+    }
+  }
+
+
+  /**
+   * Set the artifact mode.
+   *
+   * @param $mode
+   * Use 'symlink' to link resources, and 'copy' to copy them.
+   */
+  public function setMode($mode) {
+    if (!in_array($mode, ['symlink', 'copy'])) {
+      throw new BuildException("mode attribute must be either 'symlink' or 'copy'", $this->location);
+    }
+
+    $this->mode = $mode;
+  }
+
+
+  /**
+   * Set the source of the resource to include.
+   *
+   * @param \PhingFile $source
+   */
+  public function setSource(PhingFile $source) {
+    if (!$source->exists()) {
+      throw new BuildException("resource '$source' is not available'");
+    }
+
+    $this->source = $source;
+  }
+
+
+  /**
+   * Set the destination for the resource.
+   * @param PhingFile $dest
+   */
+  public function setDest(PhingFile $dest) {
+    $this->dest = $dest;
+  }
+
+}

tasks/acquia.xml

@@ -1,3 +1,12 @@
+<?xml version="1.0"?>
+
+<!--
+  @file acquia.xml
+  Targets for building and deploying a code artifact for Acquia.
+
+  Copyright 2016 Palantir.net, Inc.
+  -->
+
 <project name="acquia" default="acquia-status">
     <!--
         Include this file in your build.xml with:

tasks/boilerplate.xml

@@ -1,9 +1,20 @@
+<?xml version="1.0"?>
+
+<!--
+  @file boilerplate.xml
+  the-build's environment-specific property loading, plus other core targets.
+
+  Copyright 2016 Palantir.net, Inc.
+  -->
+
 <project name="boilerplate" default="status">
     <!--
       Include this file in your build.xml with:
         <import file="vendor/palantirnet/the-build/tasks/boilerplate.xml" />
       -->
 
+    <taskdef name="includeresource" classname="TheBuild\IncludeResourceTask" />
+
     <!-- Uses the project directory name as the projectname -->
     <property name="build.dir" value="${application.startdir}" />
     <basename property="projectname" file="${build.dir}" suffix="local" />

tasks/code_review/drupal_code_sniffer.xml

@@ -1,4 +1,12 @@
 <?xml version="1.0"?>
+
+<!--
+  @file drupal_code_sniffer.xml
+  Target for running the Drupal code sniffer standard.
+
+  Copyright 2016 Palantir.net, Inc.
+  -->
+
 <project name="drupal_code_sniffer" default="test-run-code-sniffer">
 
     <property name="drupal_code_sniffer.standard" value="vendor/drupal/coder/coder_sniffer/Drupal/ruleset.xml" />

tasks/code_review/phplint.xml

@@ -1,4 +1,12 @@
 <?xml version="1.0"?>
+
+<!--
+  @file phplint.xml
+  Target for running phplint.
+
+  Copyright 2016 Palantir.net, Inc.
+  -->
+
 <project name="phplint" default="test-run-phplint">
 
 

tasks/code_review/phpmd.xml

@@ -1,4 +1,12 @@
 <?xml version="1.0"?>
+
+<!--
+  @file phpmd.xml
+  Target for running phpmd.
+
+  Copyright 2016 Palantir.net, Inc.
+  -->
+
 <project name="phpmd" default="test-run-phpmd">
 
     <property name="phpmd.rulesets" value="vendor/palantirnet/the-build/conf/phpmd.xml" />

tasks/code_review/phptodo.xml

@@ -1,4 +1,12 @@
 <?xml version="1.0"?>
+
+<!--
+  @file phptodo.xml
+  Target for running phptodo.
+
+  Copyright 2016 Palantir.net, Inc.
+  -->
+
 <project name="phptodo" default="test-run-phptodo">
 
     <property name="phptodo.config" value="vendor/palantirnet/the-build/conf/php_todo_finder.yml" />

tasks/configure.xml

@@ -1,4 +1,12 @@
 <?xml version="1.0"?>
+
+<!--
+  @file configure.xml
+  Interactive configuration for the-build.
+
+  Copyright 2016 Palantir.net, Inc.
+  -->
+
 <project name="configure" default="configure">
     <!--
         This can be used to configure the build properties for a project.