Document project.toml

content/docs/app-developer-guide/environment-variables.md

@@ -6,7 +6,7 @@ summary="Environment variables are a common way to configure various buildpacks
 
 Environment variables are a common way to configure various buildpacks at build-time.
 
-Here are a few ways you can do so.
+Below are a few ways you can do so. All of them will use our [samples][samples] repo for simplicity.
 
 ### Using CLI arguments (`--env`)
 
@@ -16,9 +16,6 @@ The `--env` parameter must be one of the following:
 - `VARIABLE`, where the value of `VARIABLE` will be taken from the local environment
 
 ##### Example:
-
-For this example we will use our [samples][samples] repo for simplicity.
-
 ```bash
 # clone the repo
 git clone https://github.com/buildpacks/samples
@@ -47,17 +44,14 @@ The following environment variables were set and available to buildpacks at buil
 | `FOO`   | `BAR`   | _current environment_      |
 
 
-### Using files (`--env-file`)
+### Using env files (`--env-file`)
 
 The `--env-file` parameter must be a path to a file where each line is one of the following:
 
 - `VARIABLE=VALUE`
 - `VARIABLE`, where the value of `VARIABLE` will be taken from the current environment
 
 ##### Example:
-
-For this example we will use our [samples][samples] repo for simplicity.
-
 ```bash
 # clone the repo
 git clone https://github.com/buildpacks/samples
@@ -91,4 +85,45 @@ The following environment variables were set and available to buildpacks at buil
 
 > **NOTE:** Variables defined using `--env` take precedence over variables defined in `--env-file`.
 
+### Using Project Descriptor
+The `--descriptor` parameter must be a path to a file which follows the project.toml [schema][descriptor-schema].
+You can define environment variables in an `env` table in the file, and pass those into the application.
+
+##### Example:
+```bash
+# clone the repo
+git clone https://github.com/buildpacks/samples
+
+# Add an environment variable to the project.toml
+cat >> samples/apps/bash-script/project.toml <<EOL
+[[build.env]]
+name="HELLO"
+value="WORLD"
+EOL
+
+# build the app
+pack build sample-app \
+    --builder cnbs/sample-builder:bionic \
+    --buildpack  samples/buildpacks/hello-world/ \
+    --buildpack samples/apps/bash-script/bash-script-buildpack/ \
+    --path  samples/apps/bash-script/
+
+# run the app
+docker run sample-app
+```
+
+The following environment variables were set and available to buildpacks at build-time:
+
+| Name    | Value   |  _Source_                  |
+|---------|---------|----------------------------|
+| `HELLO` | `WORLD` | _hard-coded value in file_ |
+
+<p class="spacer"></p>
+
+> **NOTE:** Variables defined using `--env` or `--env-file` take precedence over variables defined in the `project.toml`.
+
+> **NOTE:** `project.toml` can't detect environment variables (so, for instance, if one ran `export FOO=BAR` and added
+>`name=FOO` to the `project.toml`, it wouldn't detect any value set for `FOO`).
+
+[descriptor-schema]: /docs/reference/project-descriptor/
 [samples]: https://github.com/buildpacks/samples

content/docs/app-developer-guide/using-project-descriptor.md

@@ -0,0 +1,105 @@
++++
+title="Using project.toml"
+weight=3
+summary="Learn how to use a project.toml file to simplify configuring pack."
++++
+
+A `project descriptor` (alternatively referred to as a `project.toml` file) allows users to detail configuration for a
+repository. Users can, for instance, specify which buildpacks should be used when building the repository, what files
+should be included/excluded in the build, and [set environment variables at build time][descriptor-envs].
+
+### Example
+We will use our [samples][samples] repo to demonstrate how to use a `project.toml` file.
+
+In the below example (`samples/apps/bash-script/project.toml`), we define project information (in this case, the `id`
+and human-readable `name` of the application we are building, and a `version`), and specify build information to pack.
+
+```toml
+[project]
+id = "io.buildpacks.bash-script"
+name = "Bash Script"
+version = "1.0.0"
+
+[build]
+exclude = [
+    "README.md",
+    "bash-script-buildpack"
+]
+
+[[build.buildpacks]]
+uri = "bash-script-buildpack/"
+```
+
+To use a `project.toml` file, simply:
+```shell script
+# build the app
+pack build sample-app \
+    --builder cnbs/sample-builder:bionic \
+    --path  samples/apps/bash-script/
+
+# run the app
+docker run sample-app
+```
+
+If the descriptor is named `project.toml`, it will be read by `pack` automatically. Otherwise, you can run:
+```shell script
+pack build sample-app \
+    --builder cnbs/sample-builder:bionic \
+    --path  samples/apps/bash-script/ \
+    --descriptor  samples/apps/bash-script/<project-descriptor-file.toml>
+```
+to specify an alternatively named `project descriptor`.
+
+### Specify Buildpacks and Envs
+As with other methods of [specifying buildpacks][specify-buildpacks], the only ones used are those that are specifically
+requested. Therefore, if we'd want to include another buildpack in our build (like a `hello-world` buildpack, to help us
+understand the environment), we would want to add it to our `project.toml`.
+
+> **Note:** Flags passed directly into `pack` have precedence over anything in the `project.toml`. Therefore, if we wanted
+> to use different buildpacks in the above case, we could also call `pack build ... --buildpack ...`
+
+Below is an expanded `project.toml`, with an additional buildpack and environment variable included.
+
+```toml
+[project]
+id = "io.buildpacks.bash-script"
+name = "Bash Script"
+version = "1.0.0"
+
+[build]
+exclude = [
+    "README.md",
+    "bash-script-buildpack"
+]
+[[build.buildpacks]]
+uri = "../../buildpacks/hello-world/"
+
+
+[[build.buildpacks]]
+uri = "bash-script-buildpack/"
+
+[[build.env]]
+name='HELLO'
+value='WORLD'
+```
+
+Paste the above `toml` as `new-project.toml` in the `samples/apps/bash-script/` directory, and simply:
+```shell script
+# build the app
+pack build sample-app \
+    --builder cnbs/sample-builder:bionic \
+    --path  samples/apps/bash-script/ \
+    --descriptor samples/apps/bash-script/new-project.toml
+
+# run the app
+docker run sample-app
+```
+
+### Further Reading
+For more about project descriptors, look at the [schema][descriptor-schema], as well as the [specification][spec].
+
+[specify-buildpacks]: /docs/app-developer-guide/specific-buildpacks/
+[descriptor-envs]: /docs/app-developer-guide/environment-variables/#using-project-descriptor
+[descriptor-schema]: /docs/reference/project-descriptor/
+[samples]: https://github.com/buildpacks/samples
+[spec]: https://github.com/buildpacks/spec/blob/main/extensions/project-descriptor.md

content/docs/reference/config/project-descriptor.md

@@ -0,0 +1,120 @@
++++
+title="project.toml"
+summary="Schema of the project descriptor file."
+aliases=["/docs/reference/project-descriptor/"]
++++
+
+A project descriptor allows users to detail configuration for apps, services, functions and buildpacks. It should, by
+default, be named `project.toml`, though users can name it differently, and pass the filename to `pack` by calling
+```shell script
+$ pack build --descriptor <project-descriptor path>
+```
+
+The schema for the `project descriptor` is:
+
+- #### `project` _(table, optional)_
+  A configuration table for a project.
+
+  - **`id`** _(string, optional)_\
+    A machine readable identifier for the `project`. For example, `com.example.myservice`.
+
+  - **`name`** _(string, optional)_\
+    A human readable identifier for the `project`. For example, `My Example Service`.
+
+  - **`version`** _(string, optional)_\
+    The version of the `project`.
+
+   - **`authors`** _(string list, optional)_\
+    The names and/or email addresses of the `project` authors.
+
+  - **`documentation-url`** _(string, optional)_\
+    A link to the documentation for the `project`.
+
+  - **`source-url`** _(string, optional)_\
+    A link to the source code of the `project`.
+
+   - **`licenses`** _(list, optional)_\
+    A list of project licenses. Each must contain **at least one** of the following fields:
+
+      - **`type`** _(string, optional)_\
+        The type of license.
+
+      - **`uri`** _(string, optional)_\
+        If the project uses a nonstandard license, you may use `uri` to point to the license.
+
+- #### `build` _(table, optional)_
+  A list of specifications for build-time configuration of the project.
+
+   - **`env`** _(list, optional)_
+    You can set environment variables at build time, by defining each with the following fields:
+
+      - **`name`** _(string, optional)_\
+        The name of the environment variable
+
+      - **`value`** _(string, optional, default: latest)_\
+        The assigned version of the environment variable
+
+   - **`include`** _(string list, optional)_\
+    A list of files to include in the build, while excluding everything else.
+
+        OR
+
+   - **`exclude`** _(string list, optional)_\
+    A list of files to exclude from the build, while including everything else.
+
+    > If `include` and `exclude` are both present, the lifecycle will error out.
+
+   - **`buildpacks`** _(list, optional)_
+    A list of buildpacks, each with the following fields:
+
+      - **`id`** _(string, optional)_\
+        An identifier for the buildpack. Must match ID specified in buildpack's `buildpack.toml` file.
+
+      - **`version`** _(string, optional, default: latest)_\
+        The version of the buildpack. Must match version specified in buildpack's `buildpack.toml` file.
+
+      - **`uri`** _(string, default=`urn:buildpack:<id>`)_\
+        A URL or path to an [archive][supported-archives], a packaged buildpack (saved as a `.cnb` file), or a directory. If path is relative, it must be relative to the `project.toml`.
+
+- #### `metadata` _(table, optional)_
+  Buildpacks and specific platforms are free to define additional arbitrary key-value pairs in the `metadata` table.
+
+## Example
+An example `project.toml` is:
+```toml
+[project]
+id = "io.buildpacks.my-app"
+version = "0.1"
+
+[build]
+include = [
+    "cmd/",
+    "go.mod",
+    "go.sum",
+    "*.go"
+]
+
+[[build.env]]
+name = "JAVA_OPTS"
+value = "-Xmx1g"
+
+[[build.buildpacks]]
+id = "io.buildpacks/java"
+version = "1.0"
+
+[[build.buildpacks]]
+id = "io.buildpacks/nodejs"
+version = "1.0"
+
+[metadata]
+foo = "bar"
+
+[metadata.fizz]
+buzz = ["a", "b", "c"]
+```
+
+## Specification
+For more detail, you can check out the `project.toml` [specification][spec]
+
+[spec]: https://github.com/buildpacks/spec/blob/main/extensions/project-descriptor.md
+[supported-archives]: /docs/reference/builder-config#supported-archives