Fix up .bldr.toml doc
@@ -12,22 +12,25 @@ To enable this functionality, do the following:
2. Open it and add an entry for each component package that you want to build.
- The `.bldr.toml` file is in TOML format, so create a TOML table specifying the `$pkg_name` value for that plan and then add a `path` field specifying Unix-style path globs to files or directories within your project. File or directory changes made in these path locations determine which packages will be rebuilt.
+ The `.bldr.toml` file is in TOML format, so create a TOML table specifying the `$pkg_name` value for that plan and then add a `plan_path` field specifying the path to your `plan.sh` file (you do not need to include plan.sh explicitly in the path). If all the files related to the plan are under the plan path, then you are done. Otherwise, you will need an addition 'path' field specifying Unix-style path globs to files that are associated with the plan you specified in the 'plan_path'. File or directory changes made in these path locations determine which packages will be rebuilt. Basically, when a file is committed, Builder will check to see whether it falls underneath the `plan_path` hierarchy, or matches one of the globs in the `path` field if it was specified - if the answer is yes, then Builder will issue a build for that commit.
- For example, in the Habitat repository itself, this TOML states that the `hab-launcher`, `hab-studio`, and `hab-sup` packages will be rebuilt if there are any changes in any of the specified `components` sub-directories:
+ For example, in the Habitat repository itself, this TOML states that the `hab-launcher`, `hab-studio`, and `hab-sup` packages will be rebuilt if there are any changes in any of the specified `components` sub-directories. Note that `hab-studio` does not need to specify a `path` because all of it's files are within the `plan_path` hierarchy, but that is not the case for the other projects.
```toml
# .bldr.toml
[hab-launcher]
+ plan_path = "components/launcher/habitat"
paths = [
"components/launcher/*",
"components/launcher-protocol/*",
+ "support/ci/builder-base-plan.sh",
]
[hab-studio]
- paths = ["components/studio/*"]
+ plan_path = "components/studio"
[hab-sup]
+ plan_path = "components/sup"
paths = [
"components/sup/*",
"components/eventsrv-client/*",
@@ -47,3 +50,9 @@ You can also specify a list of additional channels that packages should automati
[hab-launcher]
channels = [stable"]
```
+
+## Special case where `.bldr.toml` does not exist
+
+In the default case, where the `.bldr.toml` does not exist, there is one other condition that can impact builds. If the `plan.sh` file is not at the root (e.g., it is located in a `habitat` folder), then Builder infers that the plan files are all underneath the `habitat` folder, and will not kick off a build if files are committed that are outside of that folder.
+
+In order to have automated builds kick off in this case, either move your `plan.sh` file to the root of the repo, or add a `.bldr.toml` file to specify the paths more explicitly.
