This is an automated email from the ASF dual-hosted git repository.
tqchen pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tvm-tirx.git
The following commit(s) were added to refs/heads/main by this push:
new 28071049d [DOCS] Add a Writing Builder Code section with
@T.function.builder (#188)
28071049d is described below
commit 28071049d3a490387a657bfc3108066856028a7d
Author: Tianqi Chen <[email protected]>
AuthorDate: Wed Nov 4 13:54:29 2026 -0500
[DOCS] Add a Writing Builder Code section with @T.function.builder (#188)
This PR adds a Writing Builder Code subsection to the Printing and
Parsing guide, now that `@T.function.builder` is available.
The subsection gathers the existing raw `IRBuilder` example and the
explanation of why builder code stays in the Python domain, which now
notes it is especially helpful for agents. It then shows
`@T.function.builder` building `add_one` with the same signature as
`@T.function`. The `line_trace_scope()` note becomes a sentence
contrasting raw `IRBuilder` code with the decorator, which records
source locations automatically.
---
docs/ir_guides/printing_and_parsing.rst | 28 +++++++++++++++++++---------
examples/ir_guides/printing_and_parsing.py | 11 +++++++++++
2 files changed, 30 insertions(+), 9 deletions(-)
diff --git a/docs/ir_guides/printing_and_parsing.rst
b/docs/ir_guides/printing_and_parsing.rst
index acdda3dc9..143021a8b 100644
--- a/docs/ir_guides/printing_and_parsing.rst
+++ b/docs/ir_guides/printing_and_parsing.rst
@@ -236,6 +236,9 @@ TVMScript function on each call:
language for this: ``value`` and ``dtype`` are evaluated like any other
Python name when the builder program runs.
+Writing Builder Code
+~~~~~~~~~~~~~~~~~~~~
+
The builder is also a public API, so we can construct the same function
directly, without the parser:
@@ -249,17 +252,24 @@ to ``add_one``. Hand-written builder code uses the
user-facing API, such as
``T.serial`` and ``T.assign``, rather than the protocol hooks the parser
emits.
-Writing builder code directly is sometimes helpful because it stays
-**unambiguously in the Python domain**. A plain Python ``for`` or ``if``
-runs while the IR is built, and IR control flow comes only from explicit
-frames such as ``T.serial`` and ``T.if_`` with ``T.then_``. Developers and
-agents therefore know exactly what each line executes.
+Writing builder code directly is sometimes helpful, especially for agents,
+because it stays **unambiguously in the Python domain**. A plain Python
+``for`` or ``if`` runs while the IR is built, and IR control flow comes only
+from explicit frames such as ``T.serial`` and ``T.if_`` with ``T.then_``.
+Developers and agents therefore know exactly what each line executes.
-.. note::
+``@T.function.builder`` lets us write builder code as a function, with the
+same signature as ``@T.function``:
+
+.. literalinclude:: ../../examples/ir_guides/printing_and_parsing.py
+ :language: python
+ :start-after: # [function_builder.begin]
+ :end-before: # [function_builder.end]
- To record source locations, wrap the construction in
- ``builder.line_trace_scope()``, and each statement then records its
- source line in ``loc``.
+The parameters come from the annotations, and the body runs as plain
+Python. The result is structurally equal to ``add_one``. Each statement
+also records its source line in ``loc``, which raw ``IRBuilder`` code does
+only inside ``builder.line_trace_scope()``.
.. _tvmscript-region-syntax:
diff --git a/examples/ir_guides/printing_and_parsing.py
b/examples/ir_guides/printing_and_parsing.py
index 866768c1d..6f187098b 100644
--- a/examples/ir_guides/printing_and_parsing.py
+++ b/examples/ir_guides/printing_and_parsing.py
@@ -91,3 +91,14 @@ print(
)
)
# [highlight.end]
+
+
+# [function_builder.begin]
[email protected]
+def add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+ with T.serial(n) as i:
+ T.assign(B[i], A[i] + 1)
+ # [function_builder.end]
+
+
+ir.assert_structural_equal(add_one, built)
