io_copy
io_copy asynchronously copies files or directories within the project root and returns a dependency. source accepts one path string or a list of path strings. Source paths may be project-relative or absolute, which allows passing results from io_glob directly. Its path behavior follows GNU cp while exposing build-friendly Starlark arguments.
- An existing directory target receives the source base name.
- A source list requires an existing directory target. Sources are copied sequentially in list order. An empty list is a successful no-op.
- A target ending in
/or/.must already be a directory. - A directory source requires
recursive=True. - A recursive directory copied to a missing target creates that target as the copied directory. When the target already exists as a directory, the copy is placed below it using the source base name.
- A recursive source ending in
/.copies its contents directly into the target. - Missing target parent directories are errors. Directories within a recursive source tree are created as needed.
Existing files are replaced by default. Set overwrite=False to keep an existing non-directory when its corresponding source is also a non-directory, while still merging recursive directories. File/directory type conflicts are always errors. Existing directories are never replaced by non-directories.
New files and directories copy source permission bits subject to the process umask. Existing destination modes remain unchanged. Timestamps, ownership, hard-link relationships, and extended attributes are not preserved.
Like GNU cp, non-recursive copies follow a source symbolic link, while recursive copies preserve source links. Preserved links retain their link text, including dangling, absolute, or project-external targets. On Windows, links whose targets cannot be resolved inside the project are created as file links. File access through a link that escapes the project root is rejected. Copying is not atomic; an error or cancellation can leave a partial target.
Arguments
| Argument | Required | Description |
|---|---|---|
source | Yes | Project-relative or absolute source path within the project root, or list of such paths. |
target | Yes | Project-relative target path. |
recursive | No | Copy directories recursively. Defaults to False. |
overwrite | No | Replace existing non-directory entries. Defaults to True. |
deps | No | Dependencies to complete before copying. |
Examples
load("@io@1", "io_copy")
binary = io_copy("build/app", "dist/", deps=[build_app])
assets = io_copy("assets/.", "dist/assets", recursive=True)
headers = io_copy(["include/app.h", "include/version.h"], "dist/include/")