Merge pull request #666 from totten/master-civibuild

civibuild.md - Add documentation about CIVIBUILD_PATH and custom-types

docs/tools/civibuild.md

@@ -13,7 +13,7 @@ The *civibuild* command automates this process. It includes different build-type
 
 Note: There are a number of build tools on the market which can, e.g., create a Drupal web site (like [drush](http://drush.ws/)) or WordPress web site (like [wp-cli](http://wp-cli.org/)).  Civibuild does not aim to replace these.  Unfortunately, such tools generally require extra work for a Civi developer environment.  Civibuild works with these tools and and fills in missing parts.
 
-## Build Types
+## Build types
 
 `civibuild` includes a small library of build scripts for different configurations.
 
@@ -76,7 +76,32 @@ The `--civi-ver` argument will accept any branch or version tag.  *Note: the 4.7
 
 You can also specify `--patch` with a pull request URL to apply those changes on top of your CiviCRM version.
 
-## Build Aliases
+### Custom build types
+
+By default, `civibuild` looks for build types in `buildkit/app/config/`.
+You may define new build types by creating similar folders.  For example,
+these steps would make personal folder (`$HOME/src/extra_site_configs`)
+and register a custom build type `snazzy` (based on the `wp-demo` type).
+
+```bash
+## Make your custom folder
+$ mkdir "$HOME/src/extra_site_configs"
+
+## Copy an example build-type. Edit to taste.
+$ cp -r buildkit/app/config/wp-demo "$HOME/src/extra_site_configs/snazzy"
+$ vi "$HOME/src/extra_site_configs/snazzy/download.sh"
+$ vi "$HOME/src/extra_site_configs/snazzy/install.sh"
+
+## Build the site
+$ export CIVIBUILD_PATH="$HOME/src/extra_site_configs:$CIVIBUILD_PATH"
+$ civibuild create snazzy
+```
+
+!!! tip "Put `CIVIBUILD_PATH` in `civibuild.conf`"
+    You may set `CIVIBUILD_PATH` explicitly. However, it will be easier to use
+    if you make the change persistent. See: [Settings: civibuild.conf](#settings-civibuild)
+
+## Build aliases
 
 For developers who work with several CMSs and several versions of Civi, it's useful to have a naming convention and shorthand for the most common configurations.  Civibuild includes aliases (in `src/civibuild.aliases.sh`) like "d44" and "wpmaster":