commit 7faecc97f558e21ae632d0e7013c8a99001d38d0
author Wyatt Hepler <hepler@google.com> Fri Mar 12 11:24:37 2021 -0800
committer CQ Bot Account <pigweed-scoped@luci-project-accounts.iam.gserviceaccount.com> Sat Mar 13 00:34:34 2021 +0000
tree c9b1b5a8e1222438125192a2b24a6cae0d082043
parent 515e925148760550bfa9b26f6cbcb8eaf4f9f850

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>

pw_tokenizer/database.gni

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

pw_tokenizer/docs.rst

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