pw_tokenizer: pw_tokenizer_database args update
- Rename 'paths' to 'optional_paths' for clarity and consistency with
'optional_targets'.
- Assert that 'optional_paths' are in the output directory.
- Expands docs.
Change-Id: I649beb99072f8b9700228238d2772c75d7ba17e3
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/37580
Reviewed-by: Armando Montanez <amontanez@google.com>
Reviewed-by: Keir Mierle <keir@google.com>
Commit-Queue: Wyatt Hepler <hepler@google.com>
diff --git a/pw_tokenizer/database.gni b/pw_tokenizer/database.gni
index 846c329..81d6832 100644
--- a/pw_tokenizer/database.gni
+++ b/pw_tokenizer/database.gni
@@ -33,10 +33,11 @@
# targets: GN targets (executables or libraries) from which to add tokens;
# these targets are added to deps
# optional_targets: GN targets from which to add tokens, if the output files
-# already exist; these targets are NOT added to deps
-# paths: Paths or globs from which to add tokens. A common use for this is to
-# find all .elf files in the output directory (e.g.
-# "$root_build_dir/**/*.elf").
+# already exist; these targets are NOT added to 'deps'
+# optional_paths: Paths or globs to files in the output directory from which
+# to add tokens. For example, "$root_build_dir/**/*.elf" finds all ELF
+# files in the output directory; this does NOT add anything to 'deps': add
+# targets to 'deps' or 'targets' if they must be built first
# input_databases: paths to other database files from which to add tokens
# deps: GN targets to build prior to generating the database; artifacts from
# these targets are NOT implicitly used for database generation
@@ -132,8 +133,13 @@
args += [ "<TARGET_FILE_IF_EXISTS($target)>$_domain" ]
}
- if (defined(invoker.paths)) {
- args += rebase_path(invoker.paths)
+ if (defined(invoker.optional_paths)) {
+ _paths = rebase_path(invoker.optional_paths)
+ _out_dir = rebase_path(root_build_dir)
+ assert(filter_include(_paths, [ "$_out_dir/*" ]) == _paths,
+ "Paths in 'optional_paths' must be in the out directory. Use " +
+ "'input_databases' for files in the source tree.")
+ args += _paths
}
deps = _targets
diff --git a/pw_tokenizer/docs.rst b/pw_tokenizer/docs.rst
index a738414..eec6773 100644
--- a/pw_tokenizer/docs.rst
+++ b/pw_tokenizer/docs.rst
@@ -625,9 +625,16 @@
pw_tokenizer_database("my_database") {
database = "database_in_the_source_tree.csv"
deps = [ ":apps" ]
- paths = [ "$root_build_dir/**/*.elf" ]
+ optional_paths = [ "$root_build_dir/**/*.elf" ]
}
+.. note::
+
+ The ``paths`` and ``optional_targets`` arguments do not add anything to
+ ``deps``, so there is no guarantee that the referenced artifacts will exist
+ when the database is updated. Provide ``targets`` or ``deps`` or build other
+ GN targets first if this is a concern.
+
Detokenization
==============
Detokenization is the process of expanding a token to the string it represents