### Build tt-mlir Documentation

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

This snippet illustrates the process of building the tt-mlir project documentation. It assumes necessary tools like mdbbook and sphinx are installed, then activates the environment, builds the docs using CMake, and serves them locally with mdbbook.

```bash
source env/activate
cmake --build build -- docs
mdbook serve build/docs
```

--------------------------------

### Install Pre-Commit Hooks for tt-mlir

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

This snippet details the installation of pre-commit hooks for the tt-mlir project. Running these commands from the repository root installs the hooks, which automatically run linting checks on every git commit.

```bash
source env/activate
pre-commit install
```

--------------------------------

### Run Pre-Commit Hooks on All Files

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

This snippet demonstrates how to run all pre-commit hooks on all files in the repository. This is useful for catching up on linting if pre-commit hooks were installed after some commits were made.

```bash
pre-commit run --all-files
```

--------------------------------

### Example tt-explorer Server Start Command

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/tt-explorer/cli.md

An example command to start the tt-explorer server on port 8000, accessible globally via 0.0.0.0, and preventing the automatic opening of a browser tab. This demonstrates practical application of the CLI options.

```bash
tt-explorer -p 8000 -u 0.0.0.0 -q
```

--------------------------------

### Build tt-mlir Project with Default Options

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

This snippet shows the basic commands to build the tt-mlir project. It first activates the environment and then configures and builds the project using CMake and Ninja. No specific build flags are used, resulting in a default build configuration.

```bash
source env/activate
cmake -G Ninja -B build
cmake --build build
```

--------------------------------

### Integrate API Execution with Artifacts and Arguments

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/ttrt.md

A comprehensive example combining API initialization, argument configuration, logger setup, and artifact management for executing an API instance. It demonstrates passing custom arguments and artifacts to the `API.Run` constructor.

```python
from ttrt.common.api import API
from ttrt.common.util import Logger
from ttrt.common.util import Artifacts

API.initialize_apis()

custom_args = {}
custom_args["--clean-artifacts"] = True
custom_args["--save-artifacts"] = True
custom_args["--loops"] = 10
custom_args["--init"] = "randn"
custom_args["binary"] = "/path/to/subtract.ttnn"

log_file_name = "some_file_name.log"
custom_logger = Logger(log_file_name)

artifacts_folder_path = "/opt/folder"
custom_artifacts = Artifacts(logger=custom_logger, artifacts_folder_path=artifacts_folder_path)

run_instance = API.Run(args=custom_args, logger=custom_logger, artifacts=custom_artifacts)
result_code, results = run_instance()
```

--------------------------------

### Build tt-mlir Environment

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

Builds the necessary development environment for tt-mlir, including LLVM and Flatbuffers, and sets up a Python virtual environment. It's recommended to run this within a clean environment (no venv activated).

```bash
{{#include ../../../.github/Dockerfile.ci:environment_build}}
source env/activate
```

--------------------------------

### Clone tt-mlir Repository

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

Clones the tt-mlir source code repository from GitHub. This is the first step to obtain the project files for local development.

```bash
git clone https://github.com/tenstorrent/tt-mlir.git
```

--------------------------------

### Install Ubuntu System Dependencies for tt-mlir

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

Installs essential system dependencies for tt-mlir on Ubuntu, including git, clang, cmake, ninja, pip, and python3.11-venv. These are required for building and running tt-mlir.

```bash
sudo apt install git clang cmake ninja-build pip python3.11-venv
```

--------------------------------

### Lint tt-mlir Build with clang-tidy

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

This snippet explains how to perform linting on the tt-mlir build using clang-tidy. It activates the environment and executes the clang-tidy build target. This helps in identifying errors and stylistic issues before runtime.

```bash
source env/activate
cmake --build build -- clang-tidy
```

--------------------------------

### Create tt-mlir Toolchain Directory

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

Sets up and creates the directory for the tt-mlir toolchain, which will house LLVM and other build dependencies. This command ensures the directory exists and is owned by the current user.

```bash
export TTMLIR_TOOLCHAIN_DIR=/opt/ttmlir-toolchain/
sudo mkdir -p "${TTMLIR_TOOLCHAIN_DIR}"
sudo chown -R "${USER}" "${TTMLIR_TOOLCHAIN_DIR}"
```

--------------------------------

### Start tt-explorer Server CLI

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/tt-explorer/cli.md

Starts the tt-explorer server with specified port, URL, and browser options. It requires no external dependencies to run. The output is the running server accessible via the specified URL and port.

```bash
tt-explorer -p <port> -u <url> -q
```

--------------------------------

### Example Test Matrix Configuration (JSON)

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/ci.md

This example demonstrates how to specify multiple machine runners and build images for a test suite using JSON arrays. The 'script' field indicates the test type to be executed.

```json
{
    "runs-on": ["n150","n300"],
    "image": ["speedy","tracy"],
    "script": "unit"
}
```

--------------------------------

### Run PyKernel Example on macOS

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/pykernel.md

Executes a PyKernel example on macOS after building the project with PyKernel enabled and runtime disabled. This demonstrates the full compilation pipeline from Python to EmitC without requiring hardware.

```bash
export SYSTEM_DESC_PATH=$(pwd)/system_desc.ttsys
source env/activate
python test/pykernel/gen/custom_dm_matmul.py
```

--------------------------------

### Install Sphinx and Markdown Builder with CMake

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/CMakeLists.txt

Installs the necessary Python packages, Sphinx and sphinx-markdown-builder, using pip. This ensures that the documentation generation tools are available for subsequent steps. It uses `execute_process` to run the pip install command.

```cmake
execute_process(
    COMMAND ${Python_EXECUTABLE} -m pip install sphinx sphinx-markdown-builder
    # Optional arguments for pip install, like --upgrade, -e for editable install, etc.
    # ARGS ${_pip_args}
    # Specify the working directory if needed
    # WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
)
```

--------------------------------

### MLIR Module Output for Basic Example

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/builder/stablehlo-builder.md

Shows the resulting MLIR module generated from the basic StableHLO creation example. It defines a function `model` with three input arguments and performs a `stablehlo.add` operation, returning the result.

```mlir
module {
  func.func @model(%arg0: tensor<32x32xf32>, %arg1: tensor<32x32xf32>, %arg2: tensor<32x32xf32>) -> tensor<32x32xf32> {
    %0 = stablehlo.add %arg0, %arg1 : tensor<32x32xf32>
    return %0 : tensor<32x32xf32>
  }
}
```

--------------------------------

### Example Test Script Arguments (Bash)

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/ci.md

This bash script example shows how to interpret arguments passed to a test script. The first argument is expected to be the path to pytest test files, and the second is a pytest marker expression.

```bash
# arg $1: path to pytest test files
# arg $2: pytest marker expression to select tests to run

```

--------------------------------

### Example JSON Request for TT-MLIR API

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/tt-explorer/usage-api.md

An example of a JSON request payload sent from the UI to the server to invoke a command. It includes all necessary fields like extensionId, cmdId, modelPath, settings, and deleteAfterConversion, demonstrating a typical conversion request.

```json
{
	"extensionId": "tt_adapter",
	"cmdId": "convert",
	"modelPath": "/tmp/tmp80eg73we/mnist_sharding.mlir",
	"settings": {
		"const_element_count_limit": 16,
		"edge_label_font_size": 7.5,
		"artificial_layer_node_count_threshold": 1000,
		"keep_layers_with_a_single_child": false,
		"show_welcome_card": false,
		"disallow_vertical_edge_labels": false,
		"show_op_node_out_of_layer_edges_without_selecting": false,
		"highlight_layer_node_inputs_outputs": false,
		"hide_empty_node_data_entries": false
	},
	"deleteAfterConversion": true
}
```

--------------------------------

### VecAdd Demo Setup and Execution

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/pykernel.md

This Python code snippet illustrates the setup and execution of the VecAdd demo. It involves opening a device, defining tensor shapes and data, configuring memory, creating input and output tensors, instantiating the custom `VecAddMulticorePyKernelOp`, executing the operation, and comparing the results with a built-in `ttnn.add` operation. Dependencies include `ttnn`, `torch`, `ceil`, `max`, `map`, and `ttnn.BufferType`.

```python
# Open a device
device = ttnn.open_device(device_id=0)

# Define tensor shapes and data
num_tiles = 4
shape = [1, num_tiles, 32, 32]
data = torch.rand(shape).to(torch.bfloat16)
data2 = torch.rand(shape).to(torch.bfloat16)


# Configure memory
dram_memory_config = ttnn.DRAM_MEMORY_CONFIG

# Create input tensors
a_tensor = ttnn.from_torch(
    data,
    dtype=ttnn.bfloat16,
    layout=ttnn.TILE_LAYOUT,
    device=device,
    memory_config=dram_memory_config,
)

b_tensor = ttnn.from_torch(
    data2,
    dtype=ttnn.bfloat16,
    layout=ttnn.TILE_LAYOUT,
    device=device,
    memory_config=dram_memory_config,
)


# Create output tensor
output_tensor = ttnn.allocate_tensor_on_device(
    ttnn.Shape(shape),
    ttnn.bfloat16,
    ttnn.TILE_LAYOUT,
    device,
    dram_memory_config,
)

# Create the custom operation
vecadd_op = VecAddMulticorePyKernelOp()

# Execute the operation with the tensors and options
output = vecadd_op(a_tensor, b_tensor, output_tensor)

# Compare with the built-in add operation
golden = ttnn.add(a_tensor, b_tensor)

# Convert to torch tensors for comparison
torch_golden = ttnn.to_torch(golden)
torch_output = ttnn.to_torch(output)

```

--------------------------------

### Install Mac OS System Dependencies for tt-mlir

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

Installs CMake and Ninja build tools on Mac OS using Homebrew, which are necessary system dependencies for tt-mlir development on this platform.

```bash
brew install cmake ninja
```

--------------------------------

### Adapter Initialize API

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/tt-explorer/usage-api.md

Initializes the system by loading the SystemDesc into the environment. Called from TTAdapter.__init__.

```APIDOC
## POST /initialize

### Description
Initializes the system by loading the SystemDesc into the environment.

### Method
POST

### Endpoint
/initialize

### Parameters
#### Request Body
- **cmdId** (string) - Required - The command ID, must be 'initialize'.

### Request Example
```json
{
  "cmdId": "initialize"
}
```

### Response
#### Success Response (200)
- **graphs** (array) - An array containing system description information.
  - **system_desc_path** (string) - The path to the system description file.

#### Response Example
```json
{
	"graphs": [
		{
			"system_desc_path": "<path to system_desc.ttsys>"
		}
	]
}
```
```

--------------------------------

### Resolve TTMLIRPythonCAPI RPATH Build Error

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

This snippet provides a solution for a common CMake build error related to RPATH when using the Ninja generator. The error indicates an issue with installing the TTMLIRPythonCAPI target. The solution involves removing the build directory, updating CMake and Ninja, and rebuilding.

```bash
# Ensure you have a recent version of CMake and Ninja installed.
# Example: pip3 install -U ninja

# Remove the stale build directory
rm -rf build

# Reconfigure and rebuild
source env/activate
cmake -G Ninja -B build
cmake --build build
```

--------------------------------

### Execute API and Retrieve Results

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/ttrt.md

Shows how to execute an API instance and retrieve results. Note that API instances are stateless, and subsequent calls do not preserve previous artifacts. New artifact directories can be generated for multiple API calls.

```bash
result_code, results = query_instance()
result_code, results = read_instance()
result_code, results = run_instance()
```

--------------------------------

### CMake Error: C++ Compiler Not Found

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

This CMake error indicates that the C++ compiler (clang++) or C compiler (clang) is not found in the system's PATH. To resolve this, ensure the compiler is installed and accessible. You can specify the compiler path by setting the CXX or CC environment variables, or by providing the full path to the compiler in the CMake cache.

```cmake
CMake Error at CMakeLists.txt:2 (project):
  The CMAKE_CXX_COMPILER:
    clang++
  is not a full path and was not found in the PATH.
  Tell CMake where to find the compiler by setting either the environment
  variable "CXX" or the CMake cache entry CMAKE_CXX_COMPILER to the full path
  to the compiler, or to the compiler name if it is in the PATH.
CMake Error at CMakeLists.txt:2 (project):
  The CMAKE_C_COMPILER:
    clang
  is not a full path and was not found in the PATH.
  Tell CMake where to find the compiler by setting either the environment
  variable "CC" or the CMake cache entry CMAKE_C_COMPILER to the full path to
  the compiler, or to the compiler name if it is in the PATH.
```

--------------------------------

### Preparing tt-mlir Development Environment

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/llvm_dependency_update.md

This section details the initial steps for setting up a clean development environment for tt-mlir using a base Docker image. This ensures a fresh build environment without pre-existing dependencies, which is crucial for dependency updates and troubleshooting.

```docker
ghcr.io/tenstorrent/tt-mlir/tt-mlir-base-ird-ubuntu-22-04:latest
```

--------------------------------

### Test tt-mlir Build

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

This snippet demonstrates how to test the tt-mlir build after compilation. It involves activating the environment and then running the 'check-ttmlir' target within the CMake build system.

```bash
source env/activate
cmake --build build -- check-ttmlir
```

--------------------------------

### Run clang-tidy CI Job for tt-mlir

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

This snippet shows how to run clang-tidy in a CI-like manner, focusing only on committed files modified relative to the 'origin/main' branch. This is useful for replicating the CI linting job locally.

```bash
source env/activate
cmake --build build -- clang-tidy-ci
```

--------------------------------

### Configure Optimizer with Specific Options

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/optimizer.md

Enables the optimizer and configures specific options like memory layout analysis and the maximum number of legal layouts. This example demonstrates setting 'enable-optimizer', 'memory-layout-analysis-enabled', and 'max-legal-layouts' for detailed optimization.

```bash
ttmlir-opt --ttir-to-ttnn-backend-pipeline="enable-optimizer=true memory-layout-analysis-enabled=true max-legal-layouts=8" input.mlir
```

--------------------------------

### Run VecAdd Demo using pykernel-demo

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/pykernel.md

This bash script demonstrates how to build and run the VecAdd demo using the `pykernel-demo` target. It assumes the environment is activated and specific CMake flags are set during the build process. This command compiles the project and then executes the demo, which showcases the PyKernel operation.

```bash
source env/activate
# Ensure the TTMLIR_ENABLE_RUNTIME and TTMLIR_ENABLE_PYKERNEL flags are set during build
cmake --build build -- pykernel-demo
```

--------------------------------

### Environment Setup for ttrt Flatbuffer Execution (Bash)

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/builder/stablehlo-builder.md

Provides bash commands to set up the environment for running flatbuffers with golden data in ttrt. This includes building the project, querying artifacts, and setting the SYSTEM_DESC_PATH environment variable. These commands should be run before creating MLIR modules or flatbuffers.

```Bash
cmake --build build
ttrt query --save-artifacts
export SYSTEM_DESC_PATH=/path/to/system_desc.ttsys
```

--------------------------------

### Debugging Python on macOS with lldb

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

When debugging Python on macOS using lldb, you might encounter 'attach failed (Not allowed to attach to process)' errors. This is due to security restrictions. To overcome this, you need to codesign the Python binary with debug entitlements. This involves creating an entitlement XML file and then using the `codesign` command to sign the binary.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>com.apple.security.cs.disable-library-validation</key>
        <true/>
        <key>com.apple.security.get-task-allow</key>
        <true/>
</dict>
</plist>
```

```bash
sudo codesign -f -s - --entitlements debuggee-entitlement.xml /opt/ttmlir-toolchain/venv/bin/python
```

--------------------------------

### Example: Create Basic StableHLO Module

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/builder/stablehlo-builder.md

Demonstrates creating a simple StableHLO module by defining a Python function `model` that performs an addition operation using `StableHLOBuilder`. The `build_stablehlo_module` function is then used to generate the MLIR module from this model function and specified input shapes.

```python
from builder.base.builder import Operand
from builder.stablehlo.stablehlo_builder import StableHLOBuilder
from builder.base.builder_utils import build_stablehlo_module

shapes = [(32, 32), (32, 32), (32, 32)]

def model(in0: Operand, in1: Operand, in2: Operand, builder: StableHLOBuilder):
    return builder.add(in0, in1)

module, builder = build_stablehlo_module(model, shapes)
```

--------------------------------

### CMake Installation of TTMLIR Components

Source: https://github.com/tenstorrent/tt-mlir/blob/main/cmake/modules/CMakeLists.txt

Installs the generated TTMLIRConfig.cmake file and exports TTMLIR targets for use by other CMake projects. This setup ensures that TTMLIR can be easily integrated into larger build systems.

```cmake
# Installation configuration
set(TTMLIR_EXPORT_NAME "TTMLIRTargets")

install(FILES ${ttmlir_cmake_builddir}/TTMLIRConfig.cmake
  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/ttmlir
  COMPONENT SharedLib)

install(EXPORT ${TTMLIR_EXPORT_NAME}
  FILE TTMLIRTargets.cmake
  NAMESPACE TTMLIR::
  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/ttmlir
  COMPONENT SharedLib)

get_property(TTMLIR_EXPORTS GLOBAL PROPERTY TTMLIR_EXPORTS)
if(TTMLIR_EXPORTS)
  install(TARGETS ${TTMLIR_EXPORTS}
    EXPORT ${TTMLIR_EXPORT_NAME}
    COMPONENT SharedLib)
endif()
```

--------------------------------

### ttmlir-opt: TTIR to TTNN Backend Pipeline (Bash)

Source: https://context7.com/tenstorrent/tt-mlir/llms.txt

This bash command demonstrates how to use the 'ttmlir-opt' command-line tool to register a device and run the TTIR to TTNN backend pipeline. It takes an MLIR file as input and outputs an optimized TTNN MLIR file. The system description path is provided as an argument.

```bash
# Register device and run TTIR to TTNN backend pipeline
./build/bin/ttmlir-opt \
  --ttcore-register-device="system-desc-path=/path/to/system_desc.ttsys" \
  --ttir-to-ttnn-backend-pipeline \
  test/ttmlir/Dialect/TTNN/simple_subtract.mlir \
  -o ttnn.mlir
```

--------------------------------

### Resolving tt-metal Update Failures

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/getting-started.md

Failures during tt-metal updates in the tt-mlir project typically stem from Git stash conflicts within the ExternalProject build process. This error can occur even without manual modifications due to build artifacts. The primary solution involves removing the tt-metal directory and retrying the build. If issues persist, clearing the build directory and rerunning CMake is recommended.

```bash
rm -rf third_party/tt-metal
```

```bash
rm -rf build
```

--------------------------------

### CMake Build and Install Directory Setup

Source: https://github.com/tenstorrent/tt-mlir/blob/main/cmake/modules/CMakeLists.txt

Configures CMake variables for build and installation directories, including paths for libraries, binaries, and configuration files. It also includes logic to determine default paths if specific variables are not set.

```cmake
set(ttmlir_cmake_builddir "${CMAKE_BINARY_DIR}/lib/cmake/ttmlir")
set(ttmlir_cmake_installdir "${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/cmake/ttmlir")

include(${CMAKE_CURRENT_SOURCE_DIR}/TTMLIRInstall.cmake)

get_property(TTMLIR_EXPORTS GLOBAL PROPERTY TTMLIR_EXPORTS)
export(TARGETS ${TTMLIR_EXPORTS} FILE ${ttmlir_cmake_builddir}/TTMLIRTargets.cmake)

set(ttmlir_library_dir "${CMAKE_LIBRARY_OUTPUT_DIRECTORY}")
if(NOT ttmlir_library_dir)
  set(ttmlir_library_dir "${CMAKE_BINARY_DIR}/lib")
endif()

set(ttmlir_tools_dir "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}")
if(NOT ttmlir_tools_dir)
  set(ttmlir_tools_dir "${CMAKE_BINARY_DIR}/bin")
endif()

set(TTMLIR_CONFIG_CMAKE_DIR "${ttmlir_cmake_builddir}")
set(TTMLIR_CONFIG_BINARY_DIR "${TTMLIR_BINARY_DIR}")
set(TTMLIR_CONFIG_INSTALL_PREFIX "${CMAKE_INSTALL_PREFIX}")
set(TTMLIR_CONFIG_LIBRARY_DIRS "${ttmlir_library_dir}")
set(TTMLIR_CONFIG_TOOLS_DIR "${ttmlir_tools_dir}")
set(TTMLIR_CONFIG_MLIR_CMAKE_DIR "${MLIR_DIR}")
set(TTMLIR_CONFIG_INCLUDE_EXPORTS "include(\"\${TTMLIR_CMAKE_DIR}/TTMLIRTargets.cmake\")")
set(TTMLIR_CONFIG_INCLUDE_DIRS
  "${TTMLIR_BINARY_DIR}/include"
  "${TTMLIR_SOURCE_DIR}/include"
  )
```

--------------------------------

### Serve Markdown Documentation Locally with mdbook

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/docs.md

Starts a local development server to view the built Markdown documentation. This command uses mdbook to serve the content from the build directory, typically accessible at http://localhost:3000.

```bash
mdbook serve build/docs

```

--------------------------------

### Add MLIR Python Modules for TTPykernel with CMake

Source: https://github.com/tenstorrent/tt-mlir/blob/main/tools/pykernel/CMakeLists.txt

This CMake snippet adds the TTPykernel Python modules to the project, specifying installation prefixes and referencing previously declared sources. It uses the `add_mlir_python_modules` command, which requires the `AddMLIRPython` module to be included. The output is a Python package installable at a specified location.

```cmake
add_mlir_python_modules(TTPykernelModules
    ROOT_PREFIX "${TTMLIR_PYTHON_PACKAGES_DIR}/pykernel"
    INSTALL_PREFIX "python_packages/pykernel"
    DECLARED_SOURCES TTPykernelSources
)
```

--------------------------------

### Build tt-mlir Project with CMake

Source: https://context7.com/tenstorrent/tt-mlir/llms.txt

Instructions to activate the virtual environment, configure the project using CMake and Ninja, build the project, and query system artifacts required for testing. Ensure the environment is activated before executing any commands.

```bash
# Activate virtual environment (required before any operations)
source env/activate

# Configure project with CMake and Ninja
cmake -G Ninja -B build -DCMAKE_CXX_COMPILER_LAUNCHER=ccache

# Build and install into venv
cmake --build build

# Query system and save descriptor (required for tests)
ttrt query --save-artifacts

# Set system descriptor path for Python tests
export SYSTEM_DESC_PATH=$(pwd)/ttrt-artifacts/system_desc.ttsys
```

--------------------------------

### Optional Component Build Example (JSON)

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/ci.md

An example of configuring a build job to include an optional component. The 'if' field is set to the component name defined in the optional components configuration (e.g., 'emitc'). This ensures the build only runs if relevant files are changed.

```json
{ "image": "speedy", "script": "emitc.sh", "if": "emitc" }
```

--------------------------------

### CMake Configuration for TT-MLIR Project

Source: https://github.com/tenstorrent/tt-mlir/blob/main/test/install/CMakeLists.txt

This snippet shows the CMake configuration for a C++ project that utilizes the TT-MLIR library. It sets the minimum CMake version, project name, C++ standard, finds the TTMLIR package, and links the executable against TTMLIR dialects. It assumes TTMLIR is installed and its configuration files are discoverable.

```cmake
cmake_minimum_required(VERSION 3.20)
project(TestTTMLIRInstall C CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(TTMLIR REQUIRED CONFIG HINTS ${TTMLIR_DIR})
if(NOT TTMLIR_FOUND)
  message(FATAL_ERROR "TTMLIR not found")
endif()

message(STATUS "TTMLIR found in: ${TTMLIR_DIR}")
message(STATUS "TTMLIR_DIR: ${TTMLIR_DIR}")
message(STATUS "TTMLIR_INCLUDE_DIRS: ${TTMLIR_INCLUDE_DIRS}")
message(STATUS "TTMLIR_LIBRARY_DIRS: ${TTMLIR_LIBRARY_DIRS}")
message(STATUS "TTMLIR_TOOLS_DIR: ${TTMLIR_TOOLS_DIR}")
add_executable(test_install test_install.cpp)

# Link against a basic TTMLIR library that has no StableHLO dependencies.
target_link_libraries(test_install PRIVATE
  TTMLIR::MLIRTTCoreDialect
  MLIRFuncDialect
)
```

--------------------------------

### Install Shared Library Dependencies with CMake

Source: https://github.com/tenstorrent/tt-mlir/blob/main/third_party/CMakeLists.txt

Installs shared library dependencies to the specified installation directory. This command is executed conditionally and provides feedback on the installation process.

```cmake
install(CODE
    "message(STATUS \"Installing tt-metal shared lib dependencies (${library_paths}) to ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}\")"
    file(
        INSTALL
        ${library_paths}
        DESTINATION ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}
        TYPE SHARED_LIBRARY
        FOLLOW_SYMLINK_CHAIN
    )"
    COMPONENT SharedLib
)
```

--------------------------------

### Building tt-mlir with Runtime, Optimizer, and StableHLO

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/llvm_dependency_update.md

This command builds the tt-mlir compiler with specific features enabled, including runtime, optimizer, and StableHLO support. It utilizes Ninja as the build system generator and ccache for faster compilation.

```bash
source env/activate
cmake -G Ninja -B build -DTTMLIR_ENABLE_RUNTIME=ON -DTTMLIR_ENABLE_OPMODEL=ON -DTTMLIR_ENABLE_STABLEHLO=ON -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
cmake --build build
```

--------------------------------

### Install TTMLIR Targets

Source: https://github.com/tenstorrent/tt-mlir/blob/main/lib/CMakeLists.txt

Installs the 'TTMLIRCompiler' shared library and the 'TTMLIRCompilerStatic' static library to the appropriate installation directories. The installation of the static library is conditional based on whether StableHLO is enabled, to manage external dependencies.

```cmake
install(TARGETS TTMLIRCompiler DESTINATION ${CMAKE_INSTALL_LIBDIR} COMPONENT SharedLib)

if(NOT TTMLIR_ENABLE_STABLEHLO)
  install(TARGETS TTMLIRCompilerStatic
    EXPORT TTMLIRTargets
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
    COMPONENT StaticLib)
else()
  install(TARGETS TTMLIRCompilerStatic
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
    COMPONENT StaticLib)
endif()
```

--------------------------------

### Build tt-mlir with TTNN JIT Enabled (Bash)

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/ttnn-jit.md

Builds the tt-mlir project with necessary flags to enable the TTNN JIT runtime. Includes options for performance tracing and generating system descriptors.

```bash
# Build tt-mlir with TTNN JIT enabled
-DTTMLIR_ENABLE_RUNTIME=ON -DTTMLIR_ENABLE_TTNN_JIT=ON

# Optional: Enable Tracy for profiling
-DTT_RUNTIME_ENABLE_PERF_TRACE=ON

# Generate system descriptor
ttrt query --save-artifacts
export SYSTEM_DESC_PATH=`pwd`/ttrt-artifacts/system_desc.ttsys
```

--------------------------------

### Rebuild Environment and Project

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/llvm_dependency_update.md

This sequence of CMake commands shows how to rebuild the environment and the main tt-mlir project after applying changes or patches. It includes steps for configuring and building the environment, activating it, and then configuring and building the project with specific build options.

```bash
cmake -B env/build env
cmake --build env/build
source env/activate
cmake -G Ninja -B build -DTTMLIR_ENABLE_RUNTIME=ON -DTTMLIR_ENABLE_OPMODEL=ON -DTTMLIR_ENABLE_STABLEHLO=ON -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
cmake --build build
```

--------------------------------

### Install tt-metal Components using CMake Install Rules

Source: https://github.com/tenstorrent/tt-mlir/blob/main/third_party/CMakeLists.txt

This section details the CMake installation rules for various components of the tt-metal library. It covers the installation of ttnn, runtime, and the core tt_metal directories. Special handling is included for third-party dependencies within tt_metal, ensuring only necessary files like tt_llk and umd are installed. The configuration also specifies component-based installation (SharedLib, TTNNStandalone) and excludes certain directories or patterns as needed.

```cmake
# When installing, copy all needed files (for runtime) from `tt-metal` repo to the install directory.
# EXCLUDE_FROM_ALL is used to avoid installing these files when installing the default component.
install(
  DIRECTORY
    ${PROJECT_SOURCE_DIR}/third_party/tt-metal/src/tt-metal/ttnn
  DESTINATION ${CMAKE_INSTALL_PREFIX}/tt-metal
  USE_SOURCE_PERMISSIONS
  COMPONENT SharedLib
  EXCLUDE_FROM_ALL
)

install(
  DIRECTORY
    ${PROJECT_SOURCE_DIR}/third_party/tt-metal/src/tt-metal/runtime
  DESTINATION ${CMAKE_INSTALL_PREFIX}/tt-metal
  USE_SOURCE_PERMISSIONS
  COMPONENT SharedLib
  EXCLUDE_FROM_ALL
)

# `tt_metal` directory is installed with two commands, since we need special handling of `third_party` directory.
# We only need `tt_llk" and `umd` files from `third_party` directory.
install(
  DIRECTORY
    ${PROJECT_SOURCE_DIR}/third_party/tt-metal/src/tt-metal/tt_metal
  DESTINATION ${CMAKE_INSTALL_PREFIX}/tt-metal
  COMPONENT SharedLib
  EXCLUDE_FROM_ALL
  PATTERN "third_party" EXCLUDE
)

# NOTE: For some reason, CMake creates all directories even for non-matched files, but those will be empty.
install(
  DIRECTORY
    ${PROJECT_SOURCE_DIR}/third_party/tt-metal/src/tt-metal/tt_metal
  DESTINATION ${CMAKE_INSTALL_PREFIX}/tt-metal
  COMPONENT SharedLib
  EXCLUDE_FROM_ALL
  FILES_MATCHING
  REGEX "third_party/tt_llk/tt_llk_blackhole/"
  REGEX "third_party/tt_llk/tt_llk_wormhole_b0/"
  REGEX "third_party/umd/"
)

# TTNN Standalone install commands
#
# Copy .cpmcache libs
# Each is listed separately to maintain proper relative path
#
install(
  DIRECTORY
    ${CPM_SOURCE_CACHE}/fmt/69912fb6b71fcb1f7e5deca191a2bb4748c4e7b6/include
  DESTINATION tt-metal/.cpmcache/fmt/69912fb6b71fcb1f7e5deca191a2bb4748c4e7b6
  COMPONENT TTNNStandalone
  EXCLUDE_FROM_ALL
)
install(
  DIRECTORY
    ${CPM_SOURCE_CACHE}/enchantum/2fb7ab238e36c101b9848892ddb6382276b65837/enchantum/include
  DESTINATION tt-metal/.cpmcache/enchantum/2fb7ab238e36c101b9848892ddb6382276b65837/enchantum
  COMPONENT TTNNStandalone
  EXCLUDE_FROM_ALL
)
install(
  DIRECTORY
    ${CPM_SOURCE_CACHE}/nlohmann_json/798e0374658476027d9723eeb67a262d0f3c8308/include
  DESTINATION tt-metal/.cpmcache/nlohmann_json/798e0374658476027d9723eeb67a262d0f3c8308
  COMPONENT TTNNStandalone
  EXCLUDE_FROM_ALL
)
install(
  DIRECTORY
    ${CPM_SOURCE_CACHE}/reflect
  DESTINATION tt-metal/.cpmcache
  COMPONENT TTNNStandalone
  EXCLUDE_FROM_ALL
)
install(
  DIRECTORY
    ${CPM_SOURCE_CACHE}/spdlog/b1c2586bb5c35a7929362e87f62433eb68206873/include
  DESTINATION tt-metal/.cpmcache/spdlog/b1c2586bb5c35a7929362e87f62433eb68206873
  COMPONENT TTNNStandalone
  EXCLUDE_FROM_ALL
)
install(
  DIRECTORY
    ${CPM_SOURCE_CACHE}/tt-logger/5d45c661affa374c5656335a77010ab503f96a99/include
  DESTINATION tt-metal/.cpmcache/tt-logger/5d45c661affa374c5656335a77010ab503f96a99
  COMPONENT TTNNStandalone
  EXCLUDE_FROM_ALL
)
# Copy third_party
install(
  DIRECTORY
    ${PROJECT_SOURCE_DIR}/third_party/tt-metal/src/tt-metal/tt_metal/third_party
  DESTINATION tt-metal/tt_metal
  COMPONENT TTNNStandalone
  EXCLUDE_FROM_ALL
)
# Copy tt_stl
install(
  DIRECTORY
    ${PROJECT_SOURCE_DIR}/third_party/tt-metal/src/tt-metal/tt_stl
  DESTINATION tt-metal
  COMPONENT TTNNStandalone
  EXCLUDE_FROM_ALL
)

# DistributedRuntime install commands

```

--------------------------------

### Install TTMLIR Python Wheel Component (CMake)

Source: https://github.com/tenstorrent/tt-mlir/blob/main/python/CMakeLists.txt

This CMake `install` command defines a component for installing the TTMLIR bindings wheel. It installs the contents of the `python_packages` directory to the destination `.`, excluding it from the default build targets. This is crucial for creating a distributable Python package.

```cmake
install(DIRECTORY ${CMAKE_BINARY_DIR}/python_packages/ DESTINATION . COMPONENT TTMLIRPythonWheel EXCLUDE_FROM_ALL)

```

--------------------------------

### Install Directories with CMake

Source: https://github.com/tenstorrent/tt-mlir/blob/main/third_party/CMakeLists.txt

Installs specified directories from the project source into the target installation path. This is useful for including test configurations or custom mesh descriptors.

```cmake
install(
  DIRECTORY
    ${PROJECT_SOURCE_DIR}/third_party/tt-metal/src/tt-metal/tests/tt_metal/distributed/config
  DESTINATION tt-metal/tests/tt_metal/distributed
  COMPONENT DistributedRuntime
  EXCLUDE_FROM_ALL
)

install(
  DIRECTORY
    ${PROJECT_SOURCE_DIR}/third_party/tt-metal/src/tt-metal/tests/tt_metal/tt_fabric/custom_mesh_descriptors
  DESTINATION tt-metal/tests/tt_metal/tt_fabric
  COMPONENT DistributedRuntime
  EXCLUDE_FROM_ALL
)
```

--------------------------------

### Install TT-Alchemist Python Wheel for Distribution

Source: https://github.com/tenstorrent/tt-mlir/blob/main/tools/tt-alchemist/csrc/CMakeLists.txt

This target installs the tt-alchemist Python wheel that was previously built for distribution. It uses pip to install the wheel file from the distribution directory, ensuring a clean installation of the packaged library. This target is dependent on the successful completion of the wheel building target.

```cmake
if(TTMLIR_ENABLE_ALCHEMIST_WHEEL)
  add_custom_target(tt-alchemist-install-wheel-distribution
    DEPENDS tt-alchemist-build-wheel-distribution
    COMMAND ${Python3_EXECUTABLE} -m pip install
      --force-reinstall
      ${CMAKE_CURRENT_BINARY_DIR}/dist/*.whl
    COMMENT "Installing tt-alchemist wheel"
  )
endif()
```

--------------------------------

### Incremental Build and Clean Build

Source: https://github.com/tenstorrent/tt-mlir/blob/main/docs/src/ttrt.md

Instructions for performing an incremental build after making code changes, and for cleaning the build directory and dependencies to ensure a fresh build from scratch. This is often necessary after local commits or when switching build configurations.

```bash
# make some changes
# commit
cmake --build build

rm -rf build third_party/tt-metal
```

--------------------------------

### Install ttrt as Python Wheel

Source: https://github.com/tenstorrent/tt-mlir/blob/main/tools/ttrt/README.md

This section details how to install the ttrt tool as a Python wheel. It involves creating and activating a virtual environment, then using pip to install the generated .whl file.

```bash
python -m venv ttrt_env
source ttrt_env/bin/activate
pip install ttrt-0.0.235-cp311-cp311-linux_x86_64.whl
```