There are two ways to include asset files in your project: `resource
` and `file
` targets.
## `resources
`
A [`resource
`](🔗) target is for files that are members of code packages, and are loaded via language-specific mechanisms, such as Python's `pkgutil.get_data()
` or Java's `getResource()
`.
Pants will make resources available on the appropriate runtime path, such as Python's `PYTHONPATH
` or the JVM classpath. Resources can be loaded directly from a binary in which they are embedded, such as a Pex file, without first unpacking it.
To reduce boilerplate, the [`resources
`](🔗) target generates a `resource
` target per file in the `sources
` field.
For example, to load resources in Python:
[Source root](🔗) stripping applies to resources, just as it does for code. In the example above, Python loads the resource named `project/config
`, rather than `src/python/project/config.json
`.
## `files
`
A `file
` target is for loose files that are copied into the chroot where Pants runs your code. You can then load these files through direct mechanisms like Python's `open()
` or Java's `FileInputStream
`. The files are not associated with a code package, and must be extracted out of a deployed archive file before they can be loaded.
To reduce boilerplate, the [`files
`](🔗) target generates a `file
` target per file in the `sources
` field.
For example, to load loose files in Python:
Note that we open the file with its full path, including the `src/python
` prefix.
`
file
` targets are not included with binaries like `pex_binary
`Pants will not include dependencies on `
file
` / `files
` targets when creating binaries like `pex_binary
` and `python_awslambda
` via `./pants package
`. Filesystem APIs like Python's `open()
` are relative to the current working directory, and they would try to read the files from where the binary is executed, rather than reading from the binary itself.Instead, use `
resource
` / `resources
` targets or an `archive
` target.
## When to use each asset target type
### When to use `resource
`
Use `resource
` / `resources
` for files that are associated with (and typically live alongside) the code that loads them. That code's target (e.g. `python_source
`) should depend on the `resource
` target, ensuring that code and data together are embedded directly in a binary package, such as a wheel, Pex file or AWS Lambda.
### When to use `file
`
Use `file
` / `files
` for files that aren't tightly coupled to any specific code, but need to be deployed alongside a binary, such as images served by a web server.
When writing tests, it is also often more convenient to open a file than to load a resource.
Column Title | `resource ` | `file ` |
**Runtime path** | Relative to source root | Relative to repo root |
**Loading mechanism** | Language's package loader, relative to package | Language's file loading idioms, relative to repo root |
**Use with** | Targets that produce binaries, such as `pex_binary `, `python_distribution `, `python_awslambda `. | `archive ` targets, tests |
## `relocated_files
`
When you use a `file
` target, Pants will preserve the path to the files, relative to your build root. For example, the file `src/assets/logo.png
` in your repo would be under this same path in the runtime chroot.
However, you may want to change the path to something else. For example, when creating an `archive
` target and setting the `files
` field, you might want those files to be placed at a different path in the archive; rather than `src/assets/logo.png
`, for example, you might want the file to be at `imgs/logo.png
`.
You can use the `relocated_files
` target to change the path used at runtime for the files. Your other targets can then add this target to their `dependencies
` field, rather than using the original `files
` target:
You can use an empty string in the `src
` to add to an existing prefix and an empty string in the `dest
` to strip an existing prefix.
If you want multiple different re-mappings for the same original files, you can define multiple `relocated_files
` targets.
The `relocated_files
` target only accepts `file
` and `files
` targets in its `files_targets
` field. To relocate where other targets like `resource
` and `python_source
` show up at runtime, you need to change where that code is located in your repository.
## `archive
`: create a `zip
` or `tar
` file
Running `./pants package
` on an `archive
` target will create a zip or tar file with built packages and/or loose files included. This is often useful when you want to create a binary and bundle it with some loose config files.
For example:
The format can be `zip
`, `tar
`, `tar.xz
`, `tar.gz
`, or `tar.bz2
`.
The `packages
` field is a list of targets that can be built using `./pants package
`, such as `pex_binary
`, `python_awslambda
`, and even other `archive
` targets. Pants will build the packages as if you had run `./pants package
`. It will include the results in your archive using the same name they would normally have, but without the `dist/
` prefix.
The `files
` field is a list of `file
`, `files
`, and `relocated_files
` targets. See [resources](🔗) for more details.
You can optionally set the field `output_path
` to change the generated archive's name.