[DSLX fuzz testing] Create the dslx_fuzz_test BUILD macro for FuzzTest-based testing of DSLX code.

docs_src/bazel_rules_macros.md

@@ -639,7 +639,8 @@ currently produced should be considered INCOMPLETE.
 load("//xls/build_rules:xls_build_defs.bzl", "cc_xls_ir_jit_wrapper")
 
 cc_xls_ir_jit_wrapper(<a href="#cc_xls_ir_jit_wrapper-name">name</a>, <a href="#cc_xls_ir_jit_wrapper-src">src</a>, <a href="#cc_xls_ir_jit_wrapper-jit_wrapper_args">jit_wrapper_args</a>, <a href="#cc_xls_ir_jit_wrapper-wrapper_type">wrapper_type</a>, <a href="#cc_xls_ir_jit_wrapper-top">top</a>, <a href="#cc_xls_ir_jit_wrapper-llvm_opt_level">llvm_opt_level</a>,
-                      <a href="#cc_xls_ir_jit_wrapper-exec_properties">exec_properties</a>, <a href="#cc_xls_ir_jit_wrapper-tags">tags</a>, <a href="#cc_xls_ir_jit_wrapper-aot_tags">aot_tags</a>, <a href="#cc_xls_ir_jit_wrapper-jobs">jobs</a>, <a href="#cc_xls_ir_jit_wrapper-kwargs">**kwargs</a>)
+                      <a href="#cc_xls_ir_jit_wrapper-exec_properties">exec_properties</a>, <a href="#cc_xls_ir_jit_wrapper-tags">tags</a>, <a href="#cc_xls_ir_jit_wrapper-aot_tags">aot_tags</a>, <a href="#cc_xls_ir_jit_wrapper-jobs">jobs</a>, <a href="#cc_xls_ir_jit_wrapper-alwayslink">alwayslink</a>, <a href="#cc_xls_ir_jit_wrapper-enable_llvm_coverage">enable_llvm_coverage</a>,
+                      <a href="#cc_xls_ir_jit_wrapper-kwargs">**kwargs</a>)
 </pre>
 
 Invokes the JIT wrapper generator and compiles the result as a cc_library.
@@ -664,9 +665,42 @@ identical to this macro.
 | <a id="cc_xls_ir_jit_wrapper-tags"></a>tags |  normal tags to pass to actions.   |  `[]` |
 | <a id="cc_xls_ir_jit_wrapper-aot_tags"></a>aot_tags |  Tags to apply to the AOT compiler only.   |  `[]` |
 | <a id="cc_xls_ir_jit_wrapper-jobs"></a>jobs |  Number of jobs to use for AOT compilation.   |  `1` |
+| <a id="cc_xls_ir_jit_wrapper-alwayslink"></a>alwayslink |  Whether to always link the generated library.   |  `False` |
+| <a id="cc_xls_ir_jit_wrapper-enable_llvm_coverage"></a>enable_llvm_coverage |  Whether to enable LLVM coverage for the AOT compiled code.   |  `False` |
 | <a id="cc_xls_ir_jit_wrapper-kwargs"></a>kwargs |  Keyword arguments. Named arguments.   |  none |
 
 
+<a id="dslx_fuzz_test"></a>
+
+## dslx_fuzz_test
+
+<pre>
+load("//xls/build_rules:xls_build_defs.bzl", "dslx_fuzz_test")
+
+dslx_fuzz_test(<a href="#dslx_fuzz_test-name">name</a>, <a href="#dslx_fuzz_test-library">library</a>, <a href="#dslx_fuzz_test-test_function">test_function</a>, <a href="#dslx_fuzz_test-opt_ir">opt_ir</a>, <a href="#dslx_fuzz_test-jit_namespace">jit_namespace</a>, <a href="#dslx_fuzz_test-tags">tags</a>)
+</pre>
+
+A macro that instantiates a DSLX fuzz test.
+
+The macro instantiates:
+1. An xls_dslx_ir target to generate non-optimized IR.
+2. A cc_xls_ir_jit_wrapper target to generate C++ fuzz test wrapper code.
+3. A cc_test target to run the fuzz test.
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="dslx_fuzz_test-name"></a>name |  The name of the test target.   |  none |
+| <a id="dslx_fuzz_test-library"></a>library |  The xls_dslx_library target containing the DSLX code.   |  none |
+| <a id="dslx_fuzz_test-test_function"></a>test_function |  The name of the top-level DSLX function to be fuzzed.   |  none |
+| <a id="dslx_fuzz_test-opt_ir"></a>opt_ir |  Whether to generate optimized IR or not.   |  `False` |
+| <a id="dslx_fuzz_test-jit_namespace"></a>jit_namespace |  The C++ namespace for the generated JIT wrapper class.   |  `"dslx_fuzztest::impl"` |
+| <a id="dslx_fuzz_test-tags"></a>tags |  Tags to apply to the generated cc_test target.   |  `[]` |
+
+
 <a id="get_mangled_ir_symbol"></a>
 
 ## get_mangled_ir_symbol

xls/build_rules/BUILD

@@ -41,6 +41,7 @@ exports_files(
         "xls_common_rules.bzl",
         "xls_config_rules.bzl",
         "xls_dslx_rules.bzl",
+        "xls_fuzz_rules.bzl",
         "xls_ir_rules.bzl",
         "xls_ir_macros.bzl",
         "xls_jit_wrapper_rules.bzl",
@@ -257,6 +258,7 @@ bzl_library(
         ":xls_config_rules_bzl",
         ":xls_diff_test_bzl",
         ":xls_dslx_rules_bzl",
+        ":xls_fuzz_rules_bzl",
         ":xls_ir_macros_bzl",
         ":xls_ir_rules_bzl",
         ":xls_jit_wrapper_rules_bzl",
@@ -331,6 +333,18 @@ bzl_library(
     deps = ["@bazel_skylib//rules:diff_test"],
 )
 
+bzl_library(
+    name = "xls_fuzz_rules_bzl",
+    srcs = ["xls_fuzz_rules.bzl"],
+    visibility = ["//visibility:private"],
+    deps = [
+        ":xls_ir_macros_bzl",
+        ":xls_jit_wrapper_rules_bzl",
+        ":xls_macros_bzl",
+        "@rules_cc//cc:core_rules",
+    ],
+)
+
 xls_toolchain(
     name = "default_xls_toolchain",
     visibility = ["//xls:xls_public"],

xls/build_rules/tests/BUILD

@@ -19,6 +19,7 @@ load(
     "cc_xls_ir_jit_wrapper",
     "check_sha256sum_frozen",
     "check_sha256sum_test",
+    "dslx_fuzz_test",
     "get_mangled_ir_symbol",
     "xls_benchmark_ir",
     "xls_dslx_cpp_type_library",
@@ -941,3 +942,21 @@ cc_test(
         "@googletest//:gtest",
     ],
 )
+
+xls_dslx_library(
+    name = "fuzz_test_example_dslx",
+    srcs = ["fuzz_test_example.x"],
+)
+
+dslx_fuzz_test(
+    name = "fuzz_test_example_fuzz_test",
+    library = ":fuzz_test_example_dslx",
+    test_function = "my_fuzz_property",
+)
+
+dslx_fuzz_test(
+    name = "fuzz_test_example_opt_fuzz_test",
+    library = ":fuzz_test_example_dslx",
+    opt_ir = True,
+    test_function = "my_fuzz_property",
+)

xls/build_rules/tests/fuzz_test_example.x

@@ -0,0 +1,15 @@
+// Copyright 2026 The XLS 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
+//
+//      http://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.
+
+fn my_fuzz_property(x: u32, y: u32) -> bool { x + y == y + x }

xls/build_rules/xls_build_defs.bzl

@@ -41,6 +41,10 @@ load(
     _xls_dslx_prove_quickcheck_test = "xls_dslx_prove_quickcheck_test",
     _xls_dslx_test = "xls_dslx_test",
 )
+load(
+    "//xls/build_rules:xls_fuzz_rules.bzl",
+    _dslx_fuzz_test = "dslx_fuzz_test",
+)
 load(
     "//xls/build_rules:xls_ir_macros.bzl",
     _xls_dslx_ir_macro = "xls_dslx_ir_macro",
@@ -123,3 +127,4 @@ xls_model_generation = _xls_model_generation
 xls_ir_verilog_fdo = _xls_ir_verilog_fdo
 
 xls_diff_test = _xls_diff_test
+dslx_fuzz_test = _dslx_fuzz_test

xls/build_rules/xls_fuzz_rules.bzl

@@ -0,0 +1,121 @@
+# Copyright 2026 The XLS 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
+#
+#      http://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.
+
+"""This module contains the dslx_fuzz_test macro."""
+
+load("@rules_cc//cc:cc_test.bzl", "cc_test")
+load(
+    "//xls/build_rules:xls_ir_macros.bzl",
+    xls_dslx_ir = "xls_dslx_ir_macro",
+)
+load(
+    "//xls/build_rules:xls_jit_wrapper_rules.bzl",
+    "FUNCTION_WRAPPER_TYPE",
+    "FUZZTEST_WRAPPER_TYPE",
+    "cc_xls_ir_jit_wrapper",
+)
+load(
+    "//xls/build_rules:xls_macros.bzl",
+    xls_dslx_opt_ir = "xls_dslx_opt_ir_macro",
+)
+
+def dslx_fuzz_test(
+        name,
+        library,
+        test_function,
+        opt_ir = False,
+        jit_namespace = "dslx_fuzztest::impl",
+        tags = []):
+    """A macro that instantiates a DSLX fuzz test.
+
+    The macro instantiates:
+    1. An xls_dslx_ir target to generate non-optimized IR.
+    2. A cc_xls_ir_jit_wrapper target to generate C++ fuzz test wrapper code.
+    3. A cc_test target to run the fuzz test.
+
+    Args:
+      name: The name of the test target.
+      library: The xls_dslx_library target containing the DSLX code.
+      opt_ir: Whether to generate optimized IR or not.
+      test_function: The name of the top-level DSLX function to be fuzzed.
+      jit_namespace: The C++ namespace for the generated JIT wrapper class.
+      tags: Tags to apply to the generated cc_test target.
+    """
+    if opt_ir:
+        ir_name = name + "_opt_ir"
+        ir_file = name + "_" + test_function + ".opt.ir"
+        build_ir = xls_dslx_opt_ir
+    else:
+        ir_name = name + "_ir"
+        ir_file = name + "_" + test_function + ".ir"
+        build_ir = xls_dslx_ir
+
+    build_ir(
+        name = ir_name,
+        library = library,
+        dslx_top = test_function,
+        ir_file = ir_file,
+    )
+
+    lib_name = name + "_lib"
+    lib_class_name = name + "_" + test_function + "_lib"
+    cc_xls_ir_jit_wrapper(
+        name = lib_name,
+        src = ":" + ir_name,
+        wrapper_type = FUNCTION_WRAPPER_TYPE,
+        jit_wrapper_args = {
+            "class_name": lib_class_name,
+            "namespace": jit_namespace,
+        },
+        enable_llvm_coverage = True,
+        testonly = True,
+    )
+
+    fuzzer_name = name + "_fuzzer"
+    lib_header_path = "%s/%s.h" % (native.package_name(), lib_name)
+    cc_xls_ir_jit_wrapper(
+        name = fuzzer_name,
+        src = ":" + ir_name,
+        wrapper_type = FUZZTEST_WRAPPER_TYPE,
+        jit_wrapper_args = {
+            "class_name": name + "_" + test_function + "_Fuzzer",
+            "namespace": jit_namespace,
+            "lib_class_name": jit_namespace + "::" + lib_class_name,
+            "lib_header_path": lib_header_path,
+        },
+        testonly = True,
+        deps = [":" + lib_name],
+    )
+
+    cc_test(
+        name = name,
+        srcs = [],
+        deps = [
+            ":" + fuzzer_name,
+            "@googletest//:gtest",
+            "//xls/common/fuzzing:fuzztest",
+            "//xls/common:xls_gunit_main",
+            "//xls/ir:value",
+            "@com_google_absl//absl/status",
+            "@com_google_absl//absl/status:statusor",
+            "//xls/common/status:status_macros",
+            "//xls/jit:function_base_jit_wrapper",
+            "//xls/ir:bits",
+            "//xls/ir",
+            "//xls/ir:type",
+            "//xls/ir:value_test_util",
+        ],
+        tags = tags,
+        testonly = True,
+    )