How to bring up a dev/test loop for TileFoundry, and how we work on it.
Use a dedicated tilefoundry-dev conda env (Python ≥ 3.12 + torch
built against your local CUDA). Cloning an existing torch+CUDA env
is easiest. Do not install tilefoundry into base.
conda create --clone <torch_env> -n tilefoundry-dev
conda activate tilefoundry-devRecord where your env lives in a gitignored .dev-env at repo root
(informational; nothing reads it automatically):
echo CONDA_ENV=tilefoundry-dev > .dev-envgit submodule update --init --recursive # third_party/cutlass
python -m pip install -e '.[test]' -e targets/nvidia -e targets/appleWhen upgrading a checkout from before the distribution split, delete the
repository-root tilefoundry.egg-info before reinstalling all three editable projects.
The core distribution declares runtime deps (apache-tvm-ffi, torch) and
the [test] extra (pytest). Each target distribution provides its own package
data and registration entry point. After this import tilefoundry resolves to
src/tilefoundry/... and plain pytest tests/ works from repo root.
Do not set PYTHONPATH — in particular PYTHONPATH=tests:src
shadows stdlib types via tests/types/__init__.py.
pytest tests/ runs the entire suite — unit, codegen, nvcc-compiled,
and GPU end-to-end — with no marker gating. There is no --gpu flag or
-m nvcc opt-in. A machine without nvcc or a CUDA device fails the
compile and e2e tests. It does not skip them. End-to-end coverage is never
silently hidden. Per-test dump output lands under
test_results/{file_stem}/{test_name}/... (gitignored).
Set TILEFOUNDRY_CACHE_DIR to keep compile results across runs. The test session
defaults CCACHE_DIR to its ccache/ subdirectory and TORCH_EXTENSIONS_DIR to
its torch_extensions/ subdirectory, creating both directories. With ccache
on PATH, it defaults CMAKE_CUDA_COMPILER_LAUNCHER and
CMAKE_CXX_COMPILER_LAUNCHER to ccache. CCACHE_BASEDIR follows the process's
temporary directory (TMPDIR), and CCACHE_NOHASHDIR defaults to 1. Existing
environment values take precedence. Only the main test process removes torch
extension locks older than 30 minutes. Without a cache root, torch extensions
stay under <repo>/.torch_extensions and no compiler launcher is configured.
CI uses /__w/tf-cache as its cache root.
Common inner loops:
pytest tests/core/passes tests/core/ir tests/nvidia/cuda/ir -q # IR / passes edits
pytest tests/nvidia/cuda/codegen tests/nvidia/cuda/runtime -q # codegen-text edits
pytest tests/nvidia/cuda/integration -q # runtime header / host wrapper editsmainis the integration branch. Develop ontask/<id>-<short>branches and merge via PR.- Discuss requirements / design / trade-offs before any code change.
- Plan: draft under
docs/plans/<name>.mdagainstdocs/plans/TEMPLATE.md, then runscripts/finalize_plan_context.py <plan>to inject the plan-level Preflight + per-milestone policy ACs fromdocs/policies/project-policy.json. - Reviewers read the finalized plan as the implementation contract.
- After approval, implement milestone-by-milestone: claim a task, cut the branch, code + test, post results, open the PR.
- One commit per milestone batch; commit messages carry the milestone
tag. No
--amend, no force-push tomain, no--no-verify. - Claiming done requires test evidence.
- Commit, issue and pull request titles, the pull request body, branch names and the review loop: CONTRIBUTING.md.
Cross-cutting rules every change MUST honour. Each section is a short bullet list — keep it that way.
- Documentation lives in a module / class / function docstring. A
#line is for a tool (ruff:/noqa/type:/pragma:/mypy:/fmt:/isort:) or a shebang, never for a reader. In C / C++ / CUDA the docstring's place is a Doxygen block above the declaration (/** */,///, trailing///<);//and/* */are not used. - A docstring spends at most 8 prose lines and stays inside 100 columns.
Google sections (
Args:/Returns:/Raises:/Yields:/Attributes:) are structure, not prose, and do not count. - Docstrings follow Google style, validated by ruff
D2,D3,D4underconvention = "google". - Describe local logic only.
- The spec is the only durable document a docstring may reference
(
docs/spec/... §...). Never referencedocs/plans/.... - A constraint that must guide code long-term belongs in the spec first.
- No milestone / version references.
- No PR / task / commit / issue / msg / thread coordinates.
- No agent or human names; no discussion / review narration.
- No prose cataloguing what the code does NOT do.
- A line that genuinely names one of these shapes says
hygiene:and why. It excuses that line from the reference checks alone, never from placement, length or width.
- A commit touches only what the current task requires.
- Adjacent / autoformat / submodule changes ship in separate commits.
- Out-of-scope changes that cannot be split MUST be called out in the commit body.
- A milestone that changes a public contract lists its owning
docs/spec/*.mdfiles as# <path>headers in its##### Delivered; one that changes none names no spec path. There is no separate declaration to keep in step with them. - Contract-changing implementation and its specification ship in the same milestone.
- Break type-only import cycles with quoted forward-reference annotations.
- Do not guard type-only imports with
typing.TYPE_CHECKING; theforward-referencespre-commit hook rejects that shim. Ruff cannot be asked to do it — its ownTC001-TC003push the other way. - Import runtime dependencies normally or lazily at their point of use.
Import torch through the proxies in
tilefoundry.utils.lazysoimport tilefoundrydoes not load torch.
- Settle with the author how a milestone is accepted, while the plan is
written, in its
##### Accepted by.scripts/finalize_plan_context.pyrefuses to finalize a plan that leaves that choice open. It prints the contract fromdocs/policies/project-policy.json. - Each milestone defines its own Target State Design before implementation. Show every part the milestone settles in its delivered form as code or compact pseudocode. Implementation and review match that design.
- A Target State Design covers every step its milestone lists. A step with no delivered shape is a reviewer's finding before implementation begins.
- One workflow may evidence several acceptance criteria. An acceptance criterion describes behaviour, not a one-test obligation.
- Lock contracts, not implementation detail. Do not test source text, AST shape, private calls, object identity, counts, or names merely to prevent a future refactor.
- A leading
@funcdocstring is accepted; strings in nested blocks remain bare expressions. - Use
tf.<op>attribute path; do not alias individual ops. - Variadic ops take one explicit list, tuple, or supported static list comprehension; attributes go by keyword.
- Every
@funcparameter MUST reach the return through real ops; dead_ = exprassignments do not count.
- C++/CUDA sources follow the repo
.clang-format(clang-format ≥ 18, LLVM base withIndentWidth: 4,ColumnLimit: 80,PointerAlignment: Right,Standard: c++17). Runpre-commit installonce; the versioned.pre-commit-config.yamlthen formats every touched*.h/*.hpp/*.cuh/*.cu/*.cpp/*.ccwithclang-format -ion commit. An equivalent manual check isclang-format --dry-run -Werror <files>. - Formatting scope is touched files only — never run a tree-wide reformat in a feature commit (that belongs in its own isolated commit).
- Naming: types (
struct/class/enum/usingaliases) arePascalCase(Topology,Mesh,ShardLayout); functions aresnake_case(topology_shape,make_shard_tensor); template parameters areT-prefixedPascalCase(TLayout,TMesh,TAttrs) — no trailing underscore. - Headers: each target's preamble directly includes its package-owned runtime
header. There is no umbrella header or target-selection macro. Device headers
use
.cuhwhere required by their compiler; ordinary C++ headers use.h.
The terms, and the rules N1–N7 for using them in names, are in terms.
- S1–S11 and C4–C6 in this section bind the Python sources in the scope of code-organization §4, with its exceptions.
- S10: Classes are
CapWords; functions, methods and variables aresnake_case; constants areUPPER_CASE; an exception class name ends inError. Reflection dispatches some method names on a class name (<prefix>_<ClassName>:visit_*,visit_leaf_*,print_*and the pattern printer's readers).pyproject.tomllists these names inignore-names. It lists the DSL's authored names (S,P,B, …) there too. (checker: ruffN) - C4: No name starts with
_: files, classes, functions, methods, attributes, variables, parameters and import aliases. Dunder names and a lone_are exempt. (checker:scripts/code_organization_lint.py) - S11: A public class or function name does not repeat its package's name.
The classes and functions of package
p, and the namespexports, do not containp. A name that is exactlyp(cost.Cost) is allowed. Module file names are not constrained. (checker:scripts/code_organization_lint.py) ir/types/layout_algebra.pyhas a mechanically checkable public surface. Every name in its__all__MUST have the same name in CuTe.is_inverse_projectableis the sole exception. Python has no overload dispatch, soswizzle_layout.pyneeds the separately namedsupports_composition,supports_inverse, andinverseadapters.NotProjectableErrorinlayout.pyis the named Python diagnostic for composed application and inversion. These are explicit exceptions. They are not a license for unrelated helpers in the algebra modules.
- S8: A class that derives from a frozen dataclass and declares fields of its own is itself
@dataclass(frozen=True). A frozen dataclass's__post_init__writes only throughobject.__setattr__(self, "<own field>", ...). (checker:scripts/code_organization_lint.py) - C5: An attribute, or an element of an attribute, is written only through the
self/clsof the method that writes it. Nosetattr,delattr,object.__setattr__,vars(x).updateorx.__dict__change is applied to another object. A method may change a copy of its own instance that it just made withcopy.copy(self). (checker:scripts/code_organization_lint.py) - C6: No
global. A module-level container is immutable (tuple,frozenset,MappingProxyType);__all__is exempt. Mutable runtime state lives in a class instance and is written by that instance's own methods (C5). (checker:scripts/code_organization_lint.py) - S7: A
@propertybody is not onlyreturn self.<field>; a setter body is not onlyself.<field> = value. (checker:scripts/code_organization_lint.py)
- S2:
@classmethodis used only for a named constructor:from_<source>, orcreatefor a factory protocol whose subclass decides the implementation. (checker:scripts/code_organization_lint.py) - S9: A named constructor that uses only its class's layer and lower ones is a
@classmethodfrom_<source>(S2). One that uses a higher layer is a module functionmake_<name>whose return type is defined in another module. (checker:scripts/code_organization_lint.py; the layer half by C2) - S9 recognizes its subject by name (
make_*), so a rename evades it.
- S1: No
@staticmethod; write a module function. (checker:scripts/code_organization_lint.py) - S4: No nested function or class, unless it closes over a local of the enclosing function other than
self/cls. (checker:scripts/code_organization_lint.py) - S5: No custom metaclass,
__del__,__import__orimportlib.import_module. A plugin loading point that imports by name carries a per-file ignore (code-organization §4).getattr/hasattrare allowed for dispatch. (checker:scripts/code_organization_lint.py) - S6: A parameter default is neither a mutable value nor a function call. (checker: ruff
B006,B008) - Data lives in the low layer and behaviour in the high layer. A lower layer calls a higher implementation through
services(code-organization §3). - A key with no registration raises
MissingHandlerErrorwhere it is looked up; the tests cover the registrations. Write a registration next to its key's owner. Put an Op's registrations in the Op's own module. Put a Target's in that Target's package. Put a core HIR-to-TIR pairing in theschedulepackage. - A walk over Exprs, Stmts or types uses a
Functor,VisitororMutatorof visitor-mutator,TypeVisitorandTypeMutatorincluded.
Use targets/apple as a minimal example and
targets/nvidia as the complete compiler/runtime reference.
Follow the target loading and extension contract
in §1.3 for packaging, entry points, and registration.
Keep tests in tests/<vendor>/<target>/.