• zng-res::delegate — 继续搜索可以处理此请求的工具。
• zng-res::warning={message} — 将 {message} 打印为警告。
• zng-res::on-final={args} — 订阅在所有工具运行之后再次以 ZR_FINAL={args} 被调用。

如果工具失败，则打印整个 stderr，并且资源构建失败。

重建过程首先删除目标目录并重新运行所有工具。如果一个工具任务可能很慢，应该缓存结果。环境变量ZNG_RES_CACHE设置了一个目录的路径，该工具可以在此目录中存储针对此请求的中间文件。缓存目录以<SOURCE><TARGET><REQUEST>和请求文件内容为键。

工具工作目录（current_dir）始终设置为Cargo工作区根目录。如果<SOURCE>不在任何Cargo项目中，则打印警告，并将<SOURCE>用作工作目录。

内置工具

以下是提供的内置工具

$ cargo zng res --tools

.zr-copy @ cargo-zng
  Copy the file or dir

.zr-glob @ cargo-zng
  Copy all matches in place

.zr-rp @ cargo-zng
  Replace ${VAR|<file|!cmd} occurrences in the content

.zr-sh @ cargo-zng
  Run a bash script

.zr-shf @ cargo-zng
  Run a bash script on the final pass

.zr-warn @ cargo-zng
  Print a warning message

.zr-fail @ cargo-zng
  Print an error message and fail the build

.zr-apk @ cargo-zng
  Build an Android APK from a staging directory

call 'cargo zng res --help tool' to read full help from a tool

每个工具的扩展帮助

.zr-copy

$ cargo zng res --tool copy

.zr-copy</bold> @ cargo-zng
  Copy the file or dir

  The request file:
    source/foo.txt.zr-copy
     | # comment
     | path/bar.txt

  Copies `path/bar.txt` to:
    target/foo.txt

  Paths are relative to the Cargo workspace root.

.zr-glob

$ cargo zng res --tool glob

.zr-glob</bold> @ cargo-zng
  Copy all matches in place

  The request file:
    source/l10n/fluent-files.zr-glob
     | # localization dir
     | l10n
     | # only Fluent files
     | **/*.ftl
     | # except test locales
     | !:**/pseudo*

  Copies all '.ftl' not in a *pseudo* path to:
    target/l10n/

  The first path pattern is required and defines the entries that
  will be copied, an initial pattern with '**' flattens the matches.
  The path is relative to the Cargo workspace root.

  The subsequent patterns are optional and filter each file or dir selected by
  the first pattern. The paths are relative to each match, if it is a file
  the filters apply to the file name only, if it is a dir the filters apply to
  the dir and descendants.

  The glob pattern syntax is:

      ? — matches any single character.
      * — matches any (possibly empty) sequence of characters.
     ** — matches the current directory and arbitrary subdirectories.
    [c] — matches any character inside the brackets.
  [a-z] — matches any characters in the Unicode sequence.
   [!b] — negates the brackets match.

  And in filter patterns only:

  !:pattern — negates the entire pattern.

.zr-rp

$ cargo zng res --tool rp

.zr-rp</bold> @ cargo-zng
  Replace ${VAR|<file|!cmd} occurrences in the content

  The request file:
    source/greetings.txt.zr-rp
     | Thanks for using ${ZR_APP}!

  Writes the text content with ZR_APP replaced:
    target/greetings.txt
    | Thanks for using Foo App!

  The parameters syntax is ${VAR|!|<[:[case]][?else]}:

  ${VAR}          — Replaces with the env var value, or fails if it is not set.
  ${VAR:case}     — Replaces with the env var value, case converted.
  ${VAR:?else}    — If VAR is not set or is empty uses 'else' instead.

  ${<file.txt}    — Replaces with the 'file.txt' content.
                    Paths are relative to the workspace root.
  ${<file:case}   — Replaces with the 'file.txt' content, case converted.
  ${<file:?else}  — If file cannot be read or is empty uses 'else' instead.

  ${!cmd -h}      — Replaces with the stdout of the bash script line.
                    The script runs the same bash used by '.zr-sh'.
                    The script must be defined all in one line.
                    A separate bash instance is used for each occurrence.
                    The working directory is the workspace root.
  ${!cmd:case}    — Replaces with the stdout, case converted.
                    If the script contains ':' quote it with double quotes"
  $!{!cmd:?else}  — If script fails or ha no stdout, uses 'else' instead.

  $${VAR}         — Escapes $, replaces with '${VAR}'.

  The :case functions are:

  :k or :kebab  — kebab-case (cleaned)
  :K or :KEBAB  — UPPER-KEBAB-CASE (cleaned)
  :s or :snake  — snake_case (cleaned)
  :S or :SNAKE  — UPPER_SNAKE_CASE (cleaned)
  :l or :lower  — lower case
  :U or :UPPER  — UPPER CASE
  :T or :Title  — Title Case
  :c or :camel  — camelCase (cleaned)
  :P or :Pascal — PascalCase (cleaned)
  :Tr or :Train — Train-Case (cleaned)
  :           — Unchanged
  :clean      — Cleaned
  :f or :file — Sanitize file name

  Cleaned values only keep ascii alphabetic first char and ascii alphanumerics, ' ', '-' and '_' other chars.
  More then one case function can be used, separated by pipe ':T|f' converts to title case and sanitize for file name.


  The fallback(:?else) can have nested ${...} patterns.
  You can set both case and else: '${VAR:case?else}'.

  Variables:

  All env variables can be used, of particular use with this tool are:

  ZR_APP — package.metadata.zng.about.app or package.name
  ZR_ORG — package.metadata.zng.about.org or the first package.authors
  ZR_VERSION — package.version
  ZR_DESCRIPTION — package.description
  ZR_HOMEPAGE — package.homepage
  ZR_LICENSE — package.license
  ZR_PKG_NAME — package.name
  ZR_PKG_AUTHORS — package.authors
  ZR_CRATE_NAME — package.name in snake_case
  ZR_QUALIFIER — package.metadata.zng.about.qualifier

  See `zng::env::about` for more details about metadata vars.
  See the cargo-zng crate docs for a full list of ZR vars.

.zr-sh

$ cargo zng res --tool sh

.zr-sh</bold> @ cargo-zng
  Run a bash script

  Script is configured using environment variables (like other tools):

  ZR_SOURCE_DIR — Resources directory that is being build.
  ZR_TARGET_DIR — Target directory where resources are being built to.
  ZR_CACHE_DIR — Dir to use for intermediary data for the specific request.
  ZR_WORKSPACE_DIR — Cargo workspace that contains source dir. Also the working dir.
  ZR_REQUEST — Request file that called the tool (.zr-sh).
  ZR_REQUEST_DD — Parent dir of the request file.
  ZR_TARGET — Target file implied by the request file name.
  ZR_TARGET_DD — Parent dir of the target file.

  ZR_FINAL — Set if the script previously printed `zng-res::on-final={args}`.

  In a Cargo workspace the `zng::env::about` metadata is also set:

  ZR_APP — package.metadata.zng.about.app or package.name
  ZR_ORG — package.metadata.zng.about.org or the first package.authors
  ZR_VERSION — package.version
  ZR_DESCRIPTION — package.description
  ZR_HOMEPAGE — package.homepage
  ZR_LICENSE — package.license
  ZR_PKG_NAME — package.name
  ZR_PKG_AUTHORS — package.authors
  ZR_CRATE_NAME — package.name in snake_case
  ZR_QUALIFIER — package.metadata.zng.about.qualifier

  Script can make requests to the resource builder by printing to stdout.
  Current supported requests:

  zng-res::warning={msg} — Prints the `{msg}` as a warning after the script exits.
  zng-res::on-final={args} — Schedule second run with `ZR_FINAL={args}`, on final pass.

  If the script fails the entire stderr is printed and the resource build fails. Scripts run with
  `set -e` by default.

  Tries to run on $ZR_SH, $PROGRAMFILES/Git/bin/bash.exe, bash, sh.

.zr-shf

$ cargo zng res --tool shf

.zr-shf</bold> @ cargo-zng
  Run a bash script on the final pass

  Apart from running on final this tool behaves exactly like .zr-sh

.zr-warn

$ cargo zng res --tool warn

.zr-warn</bold> @ cargo-zng
  Print a warning message

  You can combine this with '.zr-rp' tool

  The request file:
    source/warn.zr-warn.zr-rp
     | ${ZR_APP}!

  Prints a warning with the value of ZR_APP

.zr-fail

$ cargo zng res --tool fail

.zr-fail</bold> @ cargo-zng
  Print an error message and fail the build

  The request file:
    some/dir/disallow.zr-fail.zr-rp
     | Don't copy ${ZR_REQUEST_DD} with a glob!

  Prints an error message and fails the build if copied