pw_build: GN template to evaluate expressions in a file

Pigweed's GN build wraps all invocations of a Python script with a
Python runner. One of the runner's main purposes is to determine the
binary outputs of GN libraries and executables, as this information
is not available through GN itself.

Sometimes, it is cumbersome or unfeasible to pass information to a
script through its command line arguments. Instead, the necessary
data is often written to a file for the script to parse. However,
doing so from within GN bypasses Pigweed's Python runner binary
resolution. `bloat.py` is an example of this -- it needed to import
and run the resolution logic itself.

This adds a template which runs GN binary resolution on files, enabling
the above use case more generally through the build system.

Change-Id: I70ca6e33e974f4b73e723295997c6197b0e91e43
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/108990
Reviewed-by: Keir Mierle <keir@google.com>
Commit-Queue: Alexei Frolov <frolv@google.com>
Reviewed-by: Brandon Vu <brandonvu@google.com>
Reviewed-by: Wyatt Hepler <hepler@google.com>
diff --git a/pw_bloat/bloat.gni b/pw_bloat/bloat.gni
index 3274d69..d7dc696 100644
--- a/pw_bloat/bloat.gni
+++ b/pw_bloat/bloat.gni
@@ -14,6 +14,7 @@
 
 import("//build_overrides/pigweed.gni")
 
+import("$dir_pw_build/evaluate_path_expressions.gni")
 import("$dir_pw_build/python_action.gni")
 
 declare_args() {
@@ -98,6 +99,10 @@
                },
                "json")
 
+    pw_evaluate_path_expressions("${target_name}.evaluate") {
+      files = [ _args_path ]
+    }
+
     _bloat_script_args = [
       "--gn-arg-path",
       _args_path,
@@ -134,12 +139,15 @@
         }
         script = "$dir_pw_bloat/py/pw_bloat/bloat.py"
         python_deps = [ "$dir_pw_bloat/py" ]
-        inputs = [ pw_bloat_BLOATY_CONFIG ]
+        inputs = [
+          pw_bloat_BLOATY_CONFIG,
+          _args_path,
+        ]
         outputs = [
           "${_doc_rst_output}.txt",
           _doc_rst_output,
         ]
-        deps = _all_target_dependencies
+        deps = _all_target_dependencies + [ ":${target_name}.evaluate" ]
         args = _bloat_script_args
 
         # Print size reports to stdout when they are generated, if requested.
@@ -291,6 +299,10 @@
                },
                "json")
 
+    pw_evaluate_path_expressions("${target_name}.evaluate") {
+      files = [ _diff_path ]
+    }
+
     _bloat_script_args = [
       "--gn-arg-path",
       _diff_path,
@@ -331,12 +343,12 @@
         }
         script = "$dir_pw_bloat/py/pw_bloat/bloat.py"
         python_deps = [ "$dir_pw_bloat/py" ]
-        inputs = _bloaty_configs
+        inputs = _bloaty_configs + [ _diff_path ]
         outputs = [
           "${_doc_rst_output}.txt",
           _doc_rst_output,
         ]
-        deps = _all_target_dependencies
+        deps = _all_target_dependencies + [ ":${target_name}.evaluate" ]
         args = _bloat_script_args
 
         # Print size reports to stdout when they are generated, if requested.
diff --git a/pw_bloat/py/pw_bloat/bloat.py b/pw_bloat/py/pw_bloat/bloat.py
index e2e74c8..0985340 100755
--- a/pw_bloat/py/pw_bloat/bloat.py
+++ b/pw_bloat/py/pw_bloat/bloat.py
@@ -16,17 +16,15 @@
 """
 
 import argparse
+import json
 import logging
 import os
 import subprocess
 import sys
-import json
 from typing import Iterable, Optional
-from pathlib import Path
 
 import pw_cli.log
 
-from pw_build.python_runner import expand_expressions, GnPaths
 from pw_bloat.label import from_bloaty_tsv
 from pw_bloat.label_output import (BloatTableOutput, LineCharset, RstOutput,
                                    AsciiCharset)
@@ -134,28 +132,6 @@
     return 0
 
 
-# TODO(frolv) Copied from python_runner.py
-def _abspath(path: Path) -> Path:
-    """Turns a path into an absolute path, not resolving symlinks."""
-    return Path(os.path.abspath(path))
-
-
-def _translate_file_paths(gn_arg_dict: dict, single_report: bool) -> dict:
-    tool = gn_arg_dict['toolchain'] if gn_arg_dict['toolchain'] != gn_arg_dict[
-        'default_toolchain'] else ''
-    paths = GnPaths(root=_abspath(gn_arg_dict['root']),
-                    build=_abspath(Path.cwd()),
-                    toolchain=tool,
-                    cwd=_abspath(gn_arg_dict['cwd']))
-    for curr_arg in gn_arg_dict['binaries']:
-        curr_arg['target'] = list(expand_expressions(paths,
-                                                     curr_arg['target']))[0]
-        if not single_report:
-            curr_arg['base'] = list(expand_expressions(paths,
-                                                       curr_arg['base']))[0]
-    return gn_arg_dict
-
-
 def main() -> int:
     """Program entry point."""
 
@@ -166,8 +142,6 @@
     json_file = open(args.gn_arg_path)
     gn_arg_dict = json.load(json_file)
 
-    gn_arg_dict = _translate_file_paths(gn_arg_dict, args.single_report)
-
     if args.single_report:
         single_binary_args = gn_arg_dict['binaries'][0]
         if single_binary_args['source_filter']:
diff --git a/pw_build/docs.rst b/pw_build/docs.rst
index 994a110..8132ddc 100644
--- a/pw_build/docs.rst
+++ b/pw_build/docs.rst
@@ -318,7 +318,10 @@
 * ``venv``: Optional gn target of the pw_python_venv that should be used to run
   this action.
 
-**Expressions**
+.. _module-pw_build-python-action-expressions:
+
+Expressions
+^^^^^^^^^^^
 
 ``pw_python_action`` evaluates expressions in ``args``, the arguments passed to
 the script. These expressions function similarly to generator expressions in
@@ -423,6 +426,69 @@
     stamp = true
   }
 
+.. _module-pw_build-evaluate-path-expressions:
+
+pw_evaluate_path_expressions
+----------------------------
+It is not always feasible to pass information to a script through command line
+arguments. If a script requires a large amount of input data, writing to a file
+is often more convenient. However, doing so bypasses ``pw_python_action``'s GN
+target label resolution, preventing such scripts from working with build
+artifacts in a build system-agnostic manner.
+
+``pw_evaluate_path_expressions`` is designed to address this use case. It takes
+a list of input files and resolves target expressions within them, modifying the
+files in-place.
+
+Refer to ``pw_python_action``'s :ref:`module-pw_build-python-action-expressions`
+section for the list of supported expressions.
+
+.. note::
+
+  ``pw_evaluate_path_expressions`` is typically used as an intermediate
+  sub-target of a larger template, rather than a standalone build target.
+
+**Arguments**
+
+* ``files``: A list of file paths to process.
+
+**Example**
+
+The following template defines an executable target which additionally outputs
+the list of object files from which it was compiled, making use of
+``pw_evaluate_path_expressions`` to resolve their paths.
+
+.. code-block::
+
+  import("$dir_pw_build/evaluate_path_expressions.gni")
+
+  template("executable_with_artifacts") {
+    executable("${target_name}.exe") {
+      sources = invoker.sources
+      if defined(invoker.deps) {
+        deps = invoker.deps
+      }
+    }
+
+    _artifacts_file = "$target_gen_dir/${target_name}_artifacts.json"
+    _artifacts = {
+      binary = "<TARGET_FILE(:${target_name}.exe)>"
+      objects = "<TARGET_OBJECTS(:${target_name}.exe)>"
+    }
+    write_file(_artifacts_file, _artifacts, "json")
+
+    pw_evaluate_path_expressions("${target_name}.evaluate") {
+      files = [ _artifacts_file ]
+    }
+
+    group(target_name) {
+      deps = [
+        ":${target_name}.exe",
+        ":${target_name}.evaluate",
+      ]
+    }
+  }
+
 .. _module-pw_build-pw_exec:
 
 pw_exec
diff --git a/pw_build/evaluate_path_expressions.gni b/pw_build/evaluate_path_expressions.gni
new file mode 100644
index 0000000..ac8d547
--- /dev/null
+++ b/pw_build/evaluate_path_expressions.gni
@@ -0,0 +1,89 @@
+# Copyright 2022 The Pigweed Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+import("python_action.gni")
+
+# Scans files for special GN target expressions and evaluates them, modifying
+# the files in-place.
+#
+# The supported expressions are the same as within the arguments list of a
+# pw_python_action target, namely:
+#
+#   <TARGET_FILE(//some/label:here)> - expands to the
+#       output file (such as a .a or .elf) from a GN target
+#   <TARGET_FILE_IF_EXISTS(//some/label:here)> - expands to
+#       the output file if the target exists, or nothing
+#   <TARGET_OBJECTS(//some/label:here)> - expands to the
+#       object files produced by the provided GN target
+#
+# This template may be useful, for example, to generate an artifact file
+# containing a list of binary objects produced by targets within a build.
+# Typically, this is used as a subtarget of a larger template, rather than a
+# standalone target.
+#
+# Args:
+#   files: List of file paths to scan for expressions.
+#
+# Example:
+#
+#   template("executable_with_artifacts") {
+#     executable("${target_name}.exe") {
+#       sources = invoker.sources
+#     }
+#
+#     _artifacts_file = "$target_gen_dir/${target_name}_artifacts.json"
+#     _artifacts = {
+#       binary = "<TARGET_FILE(:${target_name}.exe)>"
+#       objects = "<TARGET_OBJECTS(:${target_name}.exe)>"
+#     }
+#     write_file(_artifacts_file, _artifacts, "json")
+#
+#     pw_evaluate_path_expressions("${target_name}.evaluate") {
+#       files = [ _artifacts_file ]
+#     }
+#
+#     group(target_name) {
+#       deps = [
+#         ":${target_name}.exe",
+#         ":${target_name}.evaluate",
+#       ]
+#     }
+#   }
+#
+template("pw_evaluate_path_expressions") {
+  assert(defined(invoker.files),
+         "pw_evaluate_path_expressions requires input files to scan")
+
+  _script_args = [
+    "--gn-root",
+    rebase_path("//", root_build_dir),
+    "--current-path",
+    rebase_path(".", root_build_dir),
+    "--default-toolchain",
+    default_toolchain,
+    "--current-toolchain",
+    current_toolchain,
+  ]
+
+  foreach(_file, invoker.files) {
+    _script_args += [ rebase_path(_file) ]
+  }
+
+  pw_python_action(target_name) {
+    script = "$dir_pw_build/py/pw_build/gn_resolver.py"
+    inputs = invoker.files
+    args = _script_args
+    stamp = true
+  }
+}
diff --git a/pw_build/py/BUILD.gn b/pw_build/py/BUILD.gn
index f1bd9ac..cbaecb0 100644
--- a/pw_build/py/BUILD.gn
+++ b/pw_build/py/BUILD.gn
@@ -37,6 +37,7 @@
     "pw_build/generate_python_package_gn.py",
     "pw_build/generate_python_requirements.py",
     "pw_build/generated_tests.py",
+    "pw_build/gn_resolver.py",
     "pw_build/host_tool.py",
     "pw_build/mirror_tree.py",
     "pw_build/nop.py",
diff --git a/pw_build/py/pw_build/gn_resolver.py b/pw_build/py/pw_build/gn_resolver.py
new file mode 100644
index 0000000..28dcd9a
--- /dev/null
+++ b/pw_build/py/pw_build/gn_resolver.py
@@ -0,0 +1,459 @@
+# Copyright 2022 The Pigweed Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+"""Evaluates target expressions within a GN build context."""
+
+import argparse
+from dataclasses import dataclass
+import enum
+import logging
+import os
+import re
+import sys
+from pathlib import Path
+from typing import (Callable, Dict, List, Iterable, Iterator, NamedTuple,
+                    Optional, Tuple)
+
+_LOG = logging.getLogger(__name__)
+
+
+def abspath(path: Path) -> Path:
+    """Turns a path into an absolute path, not resolving symlinks."""
+    return Path(os.path.abspath(path))
+
+
+class GnPaths(NamedTuple):
+    """The set of paths needed to resolve GN paths to filesystem paths."""
+    root: Path
+    build: Path
+    cwd: Path
+
+    # Toolchain label or '' if using the default toolchain
+    toolchain: str
+
+    def resolve(self, gn_path: str) -> Path:
+        """Resolves a GN path to a filesystem path."""
+        if gn_path.startswith('//'):
+            return abspath(self.root.joinpath(gn_path.lstrip('/')))
+
+        return abspath(self.cwd.joinpath(gn_path))
+
+    def resolve_paths(self, gn_paths: str, sep: str = ';') -> str:
+        """Resolves GN paths to filesystem paths in a delimited string."""
+        return sep.join(
+            str(self.resolve(path)) for path in gn_paths.split(sep))
+
+
+@dataclass(frozen=True)
+class Label:
+    """Represents a GN label."""
+    name: str
+    dir: Path
+    relative_dir: Path
+    toolchain: Optional['Label']
+    out_dir: Path
+    gen_dir: Path
+
+    def __init__(self, paths: GnPaths, label: str):
+        # Use this lambda to set attributes on this frozen dataclass.
+        set_attr = lambda attr, val: object.__setattr__(self, attr, val)
+
+        # Handle explicitly-specified toolchains
+        if label.endswith(')'):
+            label, toolchain = label[:-1].rsplit('(', 1)
+        else:
+            # Prevent infinite recursion for toolchains
+            toolchain = paths.toolchain if paths.toolchain != label else ''
+
+        set_attr('toolchain', Label(paths, toolchain) if toolchain else None)
+
+        # Split off the :target, if provided, or use the last part of the path.
+        try:
+            directory, name = label.rsplit(':', 1)
+        except ValueError:
+            directory, name = label, label.rsplit('/', 1)[-1]
+
+        set_attr('name', name)
+
+        # Resolve the directory to an absolute path
+        set_attr('dir', paths.resolve(directory))
+        set_attr('relative_dir', self.dir.relative_to(abspath(paths.root)))
+
+        set_attr(
+            'out_dir',
+            paths.build / self.toolchain_name() / 'obj' / self.relative_dir)
+        set_attr(
+            'gen_dir',
+            paths.build / self.toolchain_name() / 'gen' / self.relative_dir)
+
+    def gn_label(self) -> str:
+        label = f'//{self.relative_dir.as_posix()}:{self.name}'
+        return f'{label}({self.toolchain!r})' if self.toolchain else label
+
+    def toolchain_name(self) -> str:
+        return self.toolchain.name if self.toolchain else ''
+
+    def __repr__(self) -> str:
+        return self.gn_label()
+
+
+class _Artifact(NamedTuple):
+    path: Path
+    variables: Dict[str, str]
+
+
+# Matches a non-phony build statement.
+_GN_NINJA_BUILD_STATEMENT = re.compile(r'^build (.+):[ \n](?!phony\b)')
+
+_OBJECTS_EXTENSIONS = ('.o', )
+
+# Extensions used for compilation artifacts.
+_MAIN_ARTIFACTS = '', '.elf', '.a', '.so', '.dylib', '.exe', '.lib', '.dll'
+
+
+def _get_artifact(entries: List[str]) -> _Artifact:
+    """Attempts to resolve which artifact to use if there are multiple.
+
+    Selects artifacts based on extension. This will not work if a toolchain
+    creates multiple compilation artifacts from one command (e.g. .a and .elf).
+    """
+    assert entries, "There should be at least one entry here!"
+
+    if len(entries) == 1:
+        return _Artifact(Path(entries[0]), {})
+
+    filtered = [p for p in entries if Path(p).suffix in _MAIN_ARTIFACTS]
+
+    if len(filtered) == 1:
+        return _Artifact(Path(filtered[0]), {})
+
+    raise ExpressionError(
+        f'Expected 1, but found {len(filtered)} artifacts, after filtering for '
+        f'extensions {", ".join(repr(e) for e in _MAIN_ARTIFACTS)}: {entries}')
+
+
+def _parse_build_artifacts(fd) -> Iterator[_Artifact]:
+    """Partially parses the build statements in a Ninja file."""
+    lines = iter(fd)
+
+    def next_line():
+        try:
+            return next(lines)
+        except StopIteration:
+            return None
+
+    # Serves as the parse state (only two states)
+    artifact: Optional[_Artifact] = None
+
+    line = next_line()
+
+    while line is not None:
+        if artifact:
+            if line.startswith('  '):  # build variable statements are indented
+                key, value = (a.strip() for a in line.split('=', 1))
+                artifact.variables[key] = value
+                line = next_line()
+            else:
+                yield artifact
+                artifact = None
+        else:
+            match = _GN_NINJA_BUILD_STATEMENT.match(line)
+            if match:
+                artifact = _get_artifact(match.group(1).split())
+
+            line = next_line()
+
+    if artifact:
+        yield artifact
+
+
+def _search_target_ninja(ninja_file: Path,
+                         target: Label) -> Tuple[Optional[Path], List[Path]]:
+    """Parses the main output file and object files from <target>.ninja."""
+
+    artifact: Optional[Path] = None
+    objects: List[Path] = []
+
+    _LOG.debug('Parsing target Ninja file %s for %s', ninja_file, target)
+
+    with ninja_file.open() as fd:
+        for path, _ in _parse_build_artifacts(fd):
+            # Older GN used .stamp files when there is no build artifact.
+            if path.suffix == '.stamp':
+                continue
+
+            if str(path).endswith(_OBJECTS_EXTENSIONS):
+                objects.append(Path(path))
+            else:
+                assert not artifact, f'Multiple artifacts for {target}!'
+                artifact = Path(path)
+
+    return artifact, objects
+
+
+def _search_toolchain_ninja(ninja_file: Path, paths: GnPaths,
+                            target: Label) -> Optional[Path]:
+    """Searches the toolchain.ninja file for outputs from the provided target.
+
+    Files created by an action appear in toolchain.ninja instead of in their own
+    <target>.ninja. If the specified target has a single output file in
+    toolchain.ninja, this function returns its path.
+    """
+
+    _LOG.debug('Searching toolchain Ninja file %s for %s', ninja_file, target)
+
+    # Older versions of GN used a .stamp file to signal completion of a target.
+    stamp_dir = target.out_dir.relative_to(paths.build).as_posix()
+    stamp_tool = 'stamp'
+    if target.toolchain_name() != '':
+        stamp_tool = f'{target.toolchain_name()}_stamp'
+    stamp_statement = f'build {stamp_dir}/{target.name}.stamp: {stamp_tool} '
+
+    # Newer GN uses a phony Ninja target to signal completion of a target.
+    phony_dir = Path(target.toolchain_name(), 'phony',
+                     target.relative_dir).as_posix()
+    phony_statement = f'build {phony_dir}/{target.name}: phony '
+
+    with ninja_file.open() as fd:
+        for line in fd:
+            for statement in (phony_statement, stamp_statement):
+                if line.startswith(statement):
+                    output_files = line[len(statement):].strip().split()
+                    if len(output_files) == 1:
+                        return Path(output_files[0])
+
+                    break
+
+    return None
+
+
+def _search_ninja_files(
+        paths: GnPaths,
+        target: Label) -> Tuple[bool, Optional[Path], List[Path]]:
+    ninja_file = target.out_dir / f'{target.name}.ninja'
+    if ninja_file.exists():
+        return (True, *_search_target_ninja(ninja_file, target))
+
+    ninja_file = paths.build / target.toolchain_name() / 'toolchain.ninja'
+    if ninja_file.exists():
+        return True, _search_toolchain_ninja(ninja_file, paths, target), []
+
+    return False, None, []
+
+
+@dataclass(frozen=True)
+class TargetInfo:
+    """Provides information about a target parsed from a .ninja file."""
+
+    label: Label
+    generated: bool  # True if the Ninja files for this target were generated.
+    artifact: Optional[Path]
+    object_files: Tuple[Path]
+
+    def __init__(self, paths: GnPaths, target: str):
+        object.__setattr__(self, 'label', Label(paths, target))
+
+        generated, artifact, objects = _search_ninja_files(paths, self.label)
+
+        object.__setattr__(self, 'generated', generated)
+        object.__setattr__(self, 'artifact', artifact)
+        object.__setattr__(self, 'object_files', tuple(objects))
+
+    def __repr__(self) -> str:
+        return repr(self.label)
+
+
+class ExpressionError(Exception):
+    """An error occurred while parsing an expression."""
+
+
+class _ArgAction(enum.Enum):
+    APPEND = 0
+    OMIT = 1
+    EMIT_NEW = 2
+
+
+class _Expression:
+    def __init__(self, match: re.Match, ending: int):
+        self._match = match
+        self._ending = ending
+
+    @property
+    def string(self):
+        return self._match.string
+
+    @property
+    def end(self) -> int:
+        return self._ending + len(_ENDING)
+
+    def contents(self) -> str:
+        return self.string[self._match.end():self._ending]
+
+    def expression(self) -> str:
+        return self.string[self._match.start():self.end]
+
+
+_Actions = Iterator[Tuple[_ArgAction, str]]
+
+
+def _target_file(paths: GnPaths, expr: _Expression) -> _Actions:
+    target = TargetInfo(paths, expr.contents())
+
+    if not target.generated:
+        raise ExpressionError(f'Target {target} has not been generated by GN!')
+
+    if target.artifact is None:
+        raise ExpressionError(f'Target {target} has no output file!')
+
+    yield _ArgAction.APPEND, str(target.artifact)
+
+
+def _target_file_if_exists(paths: GnPaths, expr: _Expression) -> _Actions:
+    target = TargetInfo(paths, expr.contents())
+
+    if target.generated:
+        if target.artifact is None:
+            raise ExpressionError(f'Target {target} has no output file!')
+
+        if paths.build.joinpath(target.artifact).exists():
+            yield _ArgAction.APPEND, str(target.artifact)
+            return
+
+    yield _ArgAction.OMIT, ''
+
+
+def _target_objects(paths: GnPaths, expr: _Expression) -> _Actions:
+    if expr.expression() != expr.string:
+        raise ExpressionError(
+            f'The expression "{expr.expression()}" in "{expr.string}" may '
+            'expand to multiple arguments, so it cannot be used alongside '
+            'other text or expressions')
+
+    target = TargetInfo(paths, expr.contents())
+    if not target.generated:
+        raise ExpressionError(f'Target {target} has not been generated by GN!')
+
+    for obj in target.object_files:
+        yield _ArgAction.EMIT_NEW, str(obj)
+
+
+# TODO(b/234886742): Replace expressions with native GN features when possible.
+_FUNCTIONS: Dict['str', Callable[[GnPaths, _Expression], _Actions]] = {
+    'TARGET_FILE': _target_file,
+    'TARGET_FILE_IF_EXISTS': _target_file_if_exists,
+    'TARGET_OBJECTS': _target_objects,
+}
+
+_START_EXPRESSION = re.compile(fr'<({"|".join(_FUNCTIONS)})\(')
+_ENDING = ')>'
+
+
+def _expand_arguments(paths: GnPaths, string: str) -> _Actions:
+    pos = 0
+
+    for match in _START_EXPRESSION.finditer(string):
+        if pos != match.start():
+            yield _ArgAction.APPEND, string[pos:match.start()]
+
+        ending = string.find(_ENDING, match.end())
+        if ending == -1:
+            raise ExpressionError(f'Parse error: no terminating "{_ENDING}" '
+                                  f'was found for "{string[match.start():]}"')
+
+        expression = _Expression(match, ending)
+        yield from _FUNCTIONS[match.group(1)](paths, expression)
+
+        pos = expression.end
+
+    if pos < len(string):
+        yield _ArgAction.APPEND, string[pos:]
+
+
+def expand_expressions(paths: GnPaths, arg: str) -> Iterable[str]:
+    """Expands <FUNCTION(...)> expressions; yields zero or more arguments."""
+    if arg == '':
+        return ['']
+
+    expanded_args: List[List[str]] = [[]]
+
+    for action, piece in _expand_arguments(paths, arg):
+        if action is _ArgAction.OMIT:
+            return []
+
+        expanded_args[-1].append(piece)
+        if action is _ArgAction.EMIT_NEW:
+            expanded_args.append([])
+
+    return (''.join(arg) for arg in expanded_args if arg)
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--gn-root',
+                        type=Path,
+                        required=True,
+                        help=('Path to the root of the GN tree; '
+                              'value of rebase_path("//", root_build_dir)'))
+    parser.add_argument('--current-path',
+                        type=Path,
+                        required=True,
+                        help='Value of rebase_path(".", root_build_dir)')
+    parser.add_argument('--default-toolchain',
+                        required=True,
+                        help='Value of default_toolchain')
+    parser.add_argument('--current-toolchain',
+                        required=True,
+                        help='Value of current_toolchain')
+    parser.add_argument('files',
+                        metavar='FILE',
+                        nargs='+',
+                        type=Path,
+                        help='Files to scan for expressions to evaluate')
+    return parser.parse_args()
+
+
+def _resolve_expressions_in_file(file: Path, paths: GnPaths):
+    source = file.read_text()
+    file.write_text(''.join(expand_expressions(paths, source)))
+
+
+def main(
+    gn_root: Path,
+    current_path: Path,
+    default_toolchain: str,
+    current_toolchain: str,
+    files: Iterable[Path],
+) -> int:
+    """Evaluates GN target expressions within a list of files.
+
+    Modifies the files in-place with their resolved contents.
+    """
+    tool = current_toolchain if current_toolchain != default_toolchain else ''
+    paths = GnPaths(root=abspath(gn_root),
+                    build=Path.cwd(),
+                    cwd=abspath(current_path),
+                    toolchain=tool)
+
+    for file in files:
+        try:
+            _resolve_expressions_in_file(file, paths)
+        except ExpressionError as err:
+            _LOG.error('Error evaluating expressions in %s:', file)
+            _LOG.error('  %s', err)
+            return 1
+
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(**vars(_parse_args())))
diff --git a/pw_build/py/pw_build/python_runner.py b/pw_build/py/pw_build/python_runner.py
index f38974f..c431b48 100755
--- a/pw_build/py/pw_build/python_runner.py
+++ b/pw_build/py/pw_build/python_runner.py
@@ -1,4 +1,4 @@
-# Copyright 2020 The Pigweed Authors
+# Copyright 2022 The Pigweed Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License"); you may not
 # use this file except in compliance with the License. You may obtain a copy of
@@ -19,26 +19,24 @@
 
 import argparse
 import atexit
-from dataclasses import dataclass
-import enum
 import json
 import logging
 import os
 from pathlib import Path
 import platform
-import re
 import shlex
 import subprocess
 import sys
 import time
-from typing import Callable, Dict, Iterable, Iterator, List, NamedTuple
-from typing import Optional, Tuple
+from typing import List, Optional, Tuple
 
 try:
+    from pw_build import gn_resolver
     from pw_build.python_package import load_packages
-except ImportError:
+except (ImportError, ModuleNotFoundError):
     # Load from python_package from this directory if pw_build is not available.
     from python_package import load_packages  # type: ignore
+    import gn_resolver  # type: ignore
 
 if sys.platform != 'win32':
     import fcntl  # pylint: disable=import-error
@@ -47,6 +45,10 @@
 _LOG = logging.getLogger(__name__)
 _LOCK_ACQUISITION_TIMEOUT = 30 * 60  # 30 minutes in seconds
 
+# TODO(frolv): Remove these aliases once downstream projects are migrated.
+GnPaths = gn_resolver.GnPaths
+expand_expressions = gn_resolver.expand_expressions
+
 
 def _parse_args() -> argparse.Namespace:
     """Parses arguments for this script, splitting out the command to run."""
@@ -111,376 +113,6 @@
     return parser.parse_args()
 
 
-def _abspath(path: Path) -> Path:
-    """Turns a path into an absolute path, not resolving symlinks."""
-    return Path(os.path.abspath(path))
-
-
-class GnPaths(NamedTuple):
-    """The set of paths needed to resolve GN paths to filesystem paths."""
-    root: Path
-    build: Path
-    cwd: Path
-
-    # Toolchain label or '' if using the default toolchain
-    toolchain: str
-
-    def resolve(self, gn_path: str) -> Path:
-        """Resolves a GN path to a filesystem path."""
-        if gn_path.startswith('//'):
-            return _abspath(self.root.joinpath(gn_path.lstrip('/')))
-
-        return _abspath(self.cwd.joinpath(gn_path))
-
-    def resolve_paths(self, gn_paths: str, sep: str = ';') -> str:
-        """Resolves GN paths to filesystem paths in a delimited string."""
-        return sep.join(
-            str(self.resolve(path)) for path in gn_paths.split(sep))
-
-
-@dataclass(frozen=True)
-class Label:
-    """Represents a GN label."""
-    name: str
-    dir: Path
-    relative_dir: Path
-    toolchain: Optional['Label']
-    out_dir: Path
-    gen_dir: Path
-
-    def __init__(self, paths: GnPaths, label: str):
-        # Use this lambda to set attributes on this frozen dataclass.
-        set_attr = lambda attr, val: object.__setattr__(self, attr, val)
-
-        # Handle explicitly-specified toolchains
-        if label.endswith(')'):
-            label, toolchain = label[:-1].rsplit('(', 1)
-        else:
-            # Prevent infinite recursion for toolchains
-            toolchain = paths.toolchain if paths.toolchain != label else ''
-
-        set_attr('toolchain', Label(paths, toolchain) if toolchain else None)
-
-        # Split off the :target, if provided, or use the last part of the path.
-        try:
-            directory, name = label.rsplit(':', 1)
-        except ValueError:
-            directory, name = label, label.rsplit('/', 1)[-1]
-
-        set_attr('name', name)
-
-        # Resolve the directory to an absolute path
-        set_attr('dir', paths.resolve(directory))
-        set_attr('relative_dir', self.dir.relative_to(_abspath(paths.root)))
-
-        set_attr(
-            'out_dir',
-            paths.build / self.toolchain_name() / 'obj' / self.relative_dir)
-        set_attr(
-            'gen_dir',
-            paths.build / self.toolchain_name() / 'gen' / self.relative_dir)
-
-    def gn_label(self) -> str:
-        label = f'//{self.relative_dir.as_posix()}:{self.name}'
-        return f'{label}({self.toolchain!r})' if self.toolchain else label
-
-    def toolchain_name(self) -> str:
-        return self.toolchain.name if self.toolchain else ''
-
-    def __repr__(self) -> str:
-        return self.gn_label()
-
-
-class _Artifact(NamedTuple):
-    path: Path
-    variables: Dict[str, str]
-
-
-# Matches a non-phony build statement.
-_GN_NINJA_BUILD_STATEMENT = re.compile(r'^build (.+):[ \n](?!phony\b)')
-
-_OBJECTS_EXTENSIONS = ('.o', )
-
-# Extensions used for compilation artifacts.
-_MAIN_ARTIFACTS = '', '.elf', '.a', '.so', '.dylib', '.exe', '.lib', '.dll'
-
-
-def _get_artifact(entries: List[str]) -> _Artifact:
-    """Attempts to resolve which artifact to use if there are multiple.
-
-    Selects artifacts based on extension. This will not work if a toolchain
-    creates multiple compilation artifacts from one command (e.g. .a and .elf).
-    """
-    assert entries, "There should be at least one entry here!"
-
-    if len(entries) == 1:
-        return _Artifact(Path(entries[0]), {})
-
-    filtered = [p for p in entries if Path(p).suffix in _MAIN_ARTIFACTS]
-
-    if len(filtered) == 1:
-        return _Artifact(Path(filtered[0]), {})
-
-    raise ExpressionError(
-        f'Expected 1, but found {len(filtered)} artifacts, after filtering for '
-        f'extensions {", ".join(repr(e) for e in _MAIN_ARTIFACTS)}: {entries}')
-
-
-def _parse_build_artifacts(fd) -> Iterator[_Artifact]:
-    """Partially parses the build statements in a Ninja file."""
-    lines = iter(fd)
-
-    def next_line():
-        try:
-            return next(lines)
-        except StopIteration:
-            return None
-
-    # Serves as the parse state (only two states)
-    artifact: Optional[_Artifact] = None
-
-    line = next_line()
-
-    while line is not None:
-        if artifact:
-            if line.startswith('  '):  # build variable statements are indented
-                key, value = (a.strip() for a in line.split('=', 1))
-                artifact.variables[key] = value
-                line = next_line()
-            else:
-                yield artifact
-                artifact = None
-        else:
-            match = _GN_NINJA_BUILD_STATEMENT.match(line)
-            if match:
-                artifact = _get_artifact(match.group(1).split())
-
-            line = next_line()
-
-    if artifact:
-        yield artifact
-
-
-def _search_target_ninja(ninja_file: Path,
-                         target: Label) -> Tuple[Optional[Path], List[Path]]:
-    """Parses the main output file and object files from <target>.ninja."""
-
-    artifact: Optional[Path] = None
-    objects: List[Path] = []
-
-    _LOG.debug('Parsing target Ninja file %s for %s', ninja_file, target)
-
-    with ninja_file.open() as fd:
-        for path, _ in _parse_build_artifacts(fd):
-            # Older GN used .stamp files when there is no build artifact.
-            if path.suffix == '.stamp':
-                continue
-
-            if str(path).endswith(_OBJECTS_EXTENSIONS):
-                objects.append(Path(path))
-            else:
-                assert not artifact, f'Multiple artifacts for {target}!'
-                artifact = Path(path)
-
-    return artifact, objects
-
-
-def _search_toolchain_ninja(ninja_file: Path, paths: GnPaths,
-                            target: Label) -> Optional[Path]:
-    """Searches the toolchain.ninja file for outputs from the provided target.
-
-    Files created by an action appear in toolchain.ninja instead of in their own
-    <target>.ninja. If the specified target has a single output file in
-    toolchain.ninja, this function returns its path.
-    """
-
-    _LOG.debug('Searching toolchain Ninja file %s for %s', ninja_file, target)
-
-    # Older versions of GN used a .stamp file to signal completion of a target.
-    stamp_dir = target.out_dir.relative_to(paths.build).as_posix()
-    stamp_tool = 'stamp'
-    if target.toolchain_name() != '':
-        stamp_tool = f'{target.toolchain_name()}_stamp'
-    stamp_statement = f'build {stamp_dir}/{target.name}.stamp: {stamp_tool} '
-
-    # Newer GN uses a phony Ninja target to signal completion of a target.
-    phony_dir = Path(target.toolchain_name(), 'phony',
-                     target.relative_dir).as_posix()
-    phony_statement = f'build {phony_dir}/{target.name}: phony '
-
-    with ninja_file.open() as fd:
-        for line in fd:
-            for statement in (phony_statement, stamp_statement):
-                if line.startswith(statement):
-                    output_files = line[len(statement):].strip().split()
-                    if len(output_files) == 1:
-                        return Path(output_files[0])
-
-                    break
-
-    return None
-
-
-def _search_ninja_files(
-        paths: GnPaths,
-        target: Label) -> Tuple[bool, Optional[Path], List[Path]]:
-    ninja_file = target.out_dir / f'{target.name}.ninja'
-    if ninja_file.exists():
-        return (True, *_search_target_ninja(ninja_file, target))
-
-    ninja_file = paths.build / target.toolchain_name() / 'toolchain.ninja'
-    if ninja_file.exists():
-        return True, _search_toolchain_ninja(ninja_file, paths, target), []
-
-    return False, None, []
-
-
-@dataclass(frozen=True)
-class TargetInfo:
-    """Provides information about a target parsed from a .ninja file."""
-
-    label: Label
-    generated: bool  # True if the Ninja files for this target were generated.
-    artifact: Optional[Path]
-    object_files: Tuple[Path]
-
-    def __init__(self, paths: GnPaths, target: str):
-        object.__setattr__(self, 'label', Label(paths, target))
-
-        generated, artifact, objects = _search_ninja_files(paths, self.label)
-
-        object.__setattr__(self, 'generated', generated)
-        object.__setattr__(self, 'artifact', artifact)
-        object.__setattr__(self, 'object_files', tuple(objects))
-
-    def __repr__(self) -> str:
-        return repr(self.label)
-
-
-class ExpressionError(Exception):
-    """An error occurred while parsing an expression."""
-
-
-class _ArgAction(enum.Enum):
-    APPEND = 0
-    OMIT = 1
-    EMIT_NEW = 2
-
-
-class _Expression:
-    def __init__(self, match: re.Match, ending: int):
-        self._match = match
-        self._ending = ending
-
-    @property
-    def string(self):
-        return self._match.string
-
-    @property
-    def end(self) -> int:
-        return self._ending + len(_ENDING)
-
-    def contents(self) -> str:
-        return self.string[self._match.end():self._ending]
-
-    def expression(self) -> str:
-        return self.string[self._match.start():self.end]
-
-
-_Actions = Iterator[Tuple[_ArgAction, str]]
-
-
-def _target_file(paths: GnPaths, expr: _Expression) -> _Actions:
-    target = TargetInfo(paths, expr.contents())
-
-    if not target.generated:
-        raise ExpressionError(f'Target {target} has not been generated by GN!')
-
-    if target.artifact is None:
-        raise ExpressionError(f'Target {target} has no output file!')
-
-    yield _ArgAction.APPEND, str(target.artifact)
-
-
-def _target_file_if_exists(paths: GnPaths, expr: _Expression) -> _Actions:
-    target = TargetInfo(paths, expr.contents())
-
-    if target.generated:
-        if target.artifact is None:
-            raise ExpressionError(f'Target {target} has no output file!')
-
-        if paths.build.joinpath(target.artifact).exists():
-            yield _ArgAction.APPEND, str(target.artifact)
-            return
-
-    yield _ArgAction.OMIT, ''
-
-
-def _target_objects(paths: GnPaths, expr: _Expression) -> _Actions:
-    if expr.expression() != expr.string:
-        raise ExpressionError(
-            f'The expression "{expr.expression()}" in "{expr.string}" may '
-            'expand to multiple arguments, so it cannot be used alongside '
-            'other text or expressions')
-
-    target = TargetInfo(paths, expr.contents())
-    if not target.generated:
-        raise ExpressionError(f'Target {target} has not been generated by GN!')
-
-    for obj in target.object_files:
-        yield _ArgAction.EMIT_NEW, str(obj)
-
-
-# TODO(b/234886742): Replace expressions with native GN features when possible.
-_FUNCTIONS: Dict['str', Callable[[GnPaths, _Expression], _Actions]] = {
-    'TARGET_FILE': _target_file,
-    'TARGET_FILE_IF_EXISTS': _target_file_if_exists,
-    'TARGET_OBJECTS': _target_objects,
-}
-
-_START_EXPRESSION = re.compile(fr'<({"|".join(_FUNCTIONS)})\(')
-_ENDING = ')>'
-
-
-def _expand_arguments(paths: GnPaths, string: str) -> _Actions:
-    pos = 0
-
-    for match in _START_EXPRESSION.finditer(string):
-        if pos != match.start():
-            yield _ArgAction.APPEND, string[pos:match.start()]
-
-        ending = string.find(_ENDING, match.end())
-        if ending == -1:
-            raise ExpressionError(f'Parse error: no terminating "{_ENDING}" '
-                                  f'was found for "{string[match.start():]}"')
-
-        expression = _Expression(match, ending)
-        yield from _FUNCTIONS[match.group(1)](paths, expression)
-
-        pos = expression.end
-
-    if pos < len(string):
-        yield _ArgAction.APPEND, string[pos:]
-
-
-def expand_expressions(paths: GnPaths, arg: str) -> Iterable[str]:
-    """Expands <FUNCTION(...)> expressions; yields zero or more arguments."""
-    if arg == '':
-        return ['']
-
-    expanded_args: List[List[str]] = [[]]
-
-    for action, piece in _expand_arguments(paths, arg):
-        if action is _ArgAction.OMIT:
-            return []
-
-        expanded_args[-1].append(piece)
-        if action is _ArgAction.EMIT_NEW:
-            expanded_args.append([])
-
-    return (''.join(arg) for arg in expanded_args if arg)
-
-
 class LockAcquisitionTimeoutError(Exception):
     """Raised on a timeout."""
 
@@ -576,7 +208,8 @@
             init_py_files = top_level_source_dir.parent.glob('*/__init__.py')
             if not any(init_py_files):
                 continue
-            python_paths_list.append(_abspath(top_level_source_dir.parent))
+            python_paths_list.append(
+                gn_resolver.abspath(top_level_source_dir.parent))
 
         # Sort the PYTHONPATH list, it will be in a different order each build.
         python_paths_list = sorted(python_paths_list)
@@ -586,13 +219,13 @@
         return 1
 
     # GN build scripts are executed from the root build directory.
-    root_build_dir = _abspath(Path.cwd())
+    root_build_dir = gn_resolver.abspath(Path.cwd())
 
     tool = current_toolchain if current_toolchain != default_toolchain else ''
-    paths = GnPaths(root=_abspath(gn_root),
-                    build=root_build_dir,
-                    cwd=_abspath(current_path),
-                    toolchain=tool)
+    paths = gn_resolver.GnPaths(root=gn_resolver.abspath(gn_root),
+                                build=root_build_dir,
+                                cwd=gn_resolver.abspath(current_path),
+                                toolchain=tool)
 
     command = [sys.executable]
 
@@ -662,8 +295,8 @@
     # Build the command to run.
     try:
         for arg in original_cmd[1:]:
-            command += expand_expressions(paths, arg)
-    except ExpressionError as err:
+            command += gn_resolver.expand_expressions(paths, arg)
+    except gn_resolver.ExpressionError as err:
         _LOG.error('%s: %s', sys.argv[0], err)
         return 1
 
diff --git a/pw_build/py/python_runner_test.py b/pw_build/py/python_runner_test.py
index 4e965cf..18c50ff 100755
--- a/pw_build/py/python_runner_test.py
+++ b/pw_build/py/python_runner_test.py
@@ -20,8 +20,8 @@
 import tempfile
 import unittest
 
-from pw_build.python_runner import ExpressionError, GnPaths, Label, TargetInfo
-from pw_build.python_runner import expand_expressions
+from pw_build.gn_resolver import ExpressionError, GnPaths, Label, TargetInfo
+from pw_build.gn_resolver import expand_expressions
 
 ROOT = Path(r'C:\gn_root' if platform.system() == 'Windows' else '/gn_root')