R1 - Addresses feedback

Author: jkshtj

mlir/docs/DefiningDialects/Operations.md

@@ -175,6 +175,93 @@ understanding the operation.
 >     starting with a capital letter and without trailing punctuation.
 >     Put expanded explanation in the description.
 
+#### Autogenerated LIT tests from IR examples in operation description
+
+To help ensure that IR based op examples stay synchronized with
+the actual operation definitions and remain valid as the codebase evolves,
+MLIR supports automatically generating roundtrip verification LIT tests from
+code examples embedded in operation descriptions.
+
+##### Embedding an IR example in op description
+
+To embed a testable MLIR example in an operation's description, use a special
+markdown code block with the `mlir_example` tag:
+
+```tablegen
+def MyOp : MyDialect_Op<"my_op"> {
+  let summary = "An example operation";
+
+  let description = [{
+    This operation demonstrates example usage.
+
+    ```mlir_example
+    # func.func @example(%arg0: i32) -> i32 { // This line will be ignored when generating `.md` documentation
+      %result = mydialect.my_op %arg0 : i32
+      return %result : i32
+    # } // This line is ignored as well
+    ```
+
+     ```mlir_example(custom-driver)
+    # func.func @example(%arg0: i32) -> i32 {
+      %result = mydialect.my_op %arg0 : i32
+      return %result : i32
+    # }
+    ```
+  }];
+}
+```
+
+Things to note:
+
+1. Any portion of the embedded snippet that need not be included in the
+   `.md` documentation can be demarcated with a `#` prefix. Lines starting with
+   `#` are stripped out when generating operation documentation but are included
+   (without the `#` and indentation) in the generated LIT tests. This allows you
+   to provide context (like function wrappers) needed for valid MLIR IR without
+   cluttering the documentation.
+
+2. You can optionally specify a custom tool/driver to use in the generated RUN
+   line by adding it in parentheses after `mlir_example`, such as
+   `mlir_example(custom-driver)`. If not specified, `mlir-opt` is used by default.
+
+3. Multiple `mlir_example` blocks can be included in a single operation's
+   description. Each block will generate a separate test file with a unique name
+   based on the operation name and example index (e.g.,
+   `generated_MyOp_example_0.mlir`, `generated_MyOp_example_1.mlir`).
+
+4. The generated RUN line automatically includes the `--verify-roundtrip` flag
+   to ensure the operation can be parsed and printed correctly.
+
+##### CMake integration for LIT test file generation
+
+MLIR provides a CMake function `add_embedded_lit_tests` to automatically extract
+and generate LIT test files from TableGen definitions during the build process.
+This function is defined in `mlir/cmake/modules/AddMLIR.cmake`.
+
+**Usage:**
+
+```cmake
+add_embedded_lit_tests(<target_name> <tablegen_file> <output_directory>)
+```
+
+**Parameters:**
+- `target_name`: Name for the CMake target that will be created
+- `tablegen_file`: Path to the TableGen file containing operations with `mlir_example` blocks
+- `output_directory`: Directory where the extracted test files will be written
+
+**Example:**
+
+```cmake
+# Extract tests from MyDialectOps.td and generate them in test/Dialect/MyDialect/
+add_embedded_lit_tests(MyDialectEmbeddedTests
+                       ${CMAKE_CURRENT_SOURCE_DIR}/include/MyDialect/MyDialectOps.td
+                       ${CMAKE_CURRENT_SOURCE_DIR}/test/Dialect/MyDialect/)
+```
+
+The generated test files can then be picked up by your LIT test configuration
+automatically, ensuring that all embedded examples are continuously tested as
+part of your regular test suite.
+
 ### Operation arguments
 
 There are three kinds of arguments: operands, attributes, and properties.

mlir/include/mlir/IR/Testable.td

@@ -14,8 +14,6 @@
 #ifndef MLIR_PASS_PASSBASE
 #define MLIR_PASS_PASSBASE
 
-include "mlir/IR/Testable.td"
-
 //===----------------------------------------------------------------------===//
 // Options
 //===----------------------------------------------------------------------===//
@@ -64,7 +62,7 @@ class Statistic<string varName, string statName, string desc> {
 // Pass
 //===----------------------------------------------------------------------===//
 
-class PassBase<string passArg, string base> : Testable {
+class PassBase<string passArg, string base> {
   // The command line argument of the pass.
   string argument = passArg;
 

mlir/include/mlir/Pass/PassBase.td

@@ -1,65 +1,74 @@
-// RUN: mlir-tblgen -gen-lit-tests -I %S/../../include -dialect=test %s | FileCheck %s
+// RUN: mlir-tblgen -gen-lit-tests -I %S/../../include %s | FileCheck %s
 
-include "mlir/Pass/PassBase.td"
-include "mlir/IR/Testable.td"
+include "mlir/IR/OpBase.td"
 
-def TestPassWithEmbeddedLitTests : Pass<"test-pass-with-embedded-lit-tests"> {
-  let summary = "pass summary";
+def Test_Dialect : Dialect {
+  let name = "test";
+  let cppNamespace = "test";
+}
+
+def TestOp : Op<Test_Dialect, "test_op"> {
+  let summary = "test op with mlir_example code blocks";
   let description = [{
-    Pass description
+    This operation demonstrates the mlir_example feature for ops.
+
+    Basic usage:
+    ```mlir_example(mlir-opt)
+    # func.func @foo(%arg0: i32) -> i32 {
+      %0 = test.test_op %arg0 : i32
+      return %0 : i32
+    # }
+    ```
+
+    And some more back to back examples -
+
+    ```mlir_example(some-other-tool)
+    # func.func @foo1(%arg1: i32) -> i32 {
+      %0 = test.test_op %arg1 : i32
+      return %0 : i32
+    # }
+    ```
+    ```mlir_example(yet-another-tool)
+    # func.func @foo2(%arg2: i32) -> i32 {
+      %0 = test.test_op %arg2 : i32
+      return %0 : i32
+    # }
+    ```
   }];
-  
-  let tests = [
-    LitTest<
-      "lit_test_file_1.mlir", 
-      [{
-          func.func @test1() {
-            return 42;
-          }
-      }],
-      [
-        "// RUN: mlir-opt %s --verify-roundtrip | FileCheck %s",
-      ],
-      [
-        "// RANDOM-CHECK-LABEL: func.func @test1",
-      ]
-    >,
-    LitTest<
-      "lit_test_file_2.mlir", 
-      [{
-          func.func @test2() {
-            return 42;
-          }
-      }],
-      [
-        "// RUN: mlir-opt %s --verify-roundtrip | FileCheck %s",
-      ],
-      [
-        "// RANDOM-CHECK-LABEL: func.func @test2",
-      ]
-    >,
-  ];
+
+  let arguments = (ins I32:$input);
+  let results = (outs I32:$output);
 }
 
-// CHECK-LABEL:       // Generated 2 LIT test files
-// CHECK:             // Use the following files for LIT testing:
+// CHECK-LABEL:     // Generated 3 LIT test files
+// CHECK:           // Use the following files for LIT testing:
+
+// CHECK:           // File: generated_TestOp_example_0.mlir
+// CHECK:           // --- BEGIN generated_TestOp_example_0.mlir ---
+// CHECK:           mlir-opt %s --verify-roundtrip
+// CHECK:           // Generated from TableGen definition: TestOp
+// CHECK:           func.func @foo(%arg0: i32) -> i32 {
+// CHECK:           %0 = test.test_op %arg0 : i32
+// CHECK:           return %0 : i32
+// CHECK:           }
+// CHECK:           // --- END generated_TestOp_example_0.mlir ---
 
-// CHECK:             // File: generated_TestPassWithEmbeddedLitTests_lit_test_file_1.mlir
-// CHECK:             // --- BEGIN generated_TestPassWithEmbeddedLitTests_lit_test_file_1.mlir ---
-// CHECK:             // RUN: mlir-opt %s --verify-roundtrip | FileCheck %s
-// CHECK:             // Generated from TableGen definition: TestPassWithEmbeddedLitTests
-// CHECK:             func.func @test1() {
-// CHECK:                return 42;
-// CHECK:             }
-// CHECK:             // RANDOM-CHECK-LABEL: func.func @test1
-// CHECK:             --- END generated_TestPassWithEmbeddedLitTests_lit_test_file_1.mlir ---
+// CHECK:           // File: generated_TestOp_example_1.mlir
+// CHECK:           // --- BEGIN generated_TestOp_example_1.mlir ---
+// CHECK:           some-other-tool %s --verify-roundtrip
+// CHECK:           // Generated from TableGen definition: TestOp
+// CHECK:           func.func @foo1(%arg1: i32) -> i32 {
+// CHECK:           %0 = test.test_op %arg1 : i32
+// CHECK:           return %0 : i32
+// CHECK:           }
+// CHECK:           // --- END generated_TestOp_example_1.mlir ---
 
-// CHECK:             // File: generated_TestPassWithEmbeddedLitTests_lit_test_file_2.mlir
-// CHECK:             // --- BEGIN generated_TestPassWithEmbeddedLitTests_lit_test_file_2.mlir ---
-// CHECK:             // RUN: mlir-opt %s --verify-roundtrip | FileCheck %s
-// CHECK:             // Generated from TableGen definition: TestPassWithEmbeddedLitTests
-// CHECK:             func.func @test2() {
-// CHECK:               return 42;
-// CHECK:             }
-// CHECK:             // RANDOM-CHECK-LABEL: func.func @test2
-// CHECK:             // --- END generated_TestPassWithEmbeddedLitTests_lit_test_file_2.mlir ---
+// CHECK:           // File: generated_TestOp_example_2.mlir
+// CHECK:           // --- BEGIN generated_TestOp_example_2.mlir ---
+// CHECK:           yet-another-tool %s --verify-roundtrip
+// CHECK:           // Generated from TableGen definition: TestOp
+// CHECK:           func.func @foo2(%arg2: i32) -> i32 {
+// CHECK:           %0 = test.test_op %arg2 : i32
+// CHECK:           return %0 : i32
+// CHECK:           }
+// CHECK:           // --- END generated_TestOp_example_2.mlir ---