Skip to content

Build system

XLS uses the Bazel build system for itself and all its dependencies. Bazel is an easy to configure and use, and has powerful extension facilities. (It's also well-documented!) XLS provdes a number of Starlark macros, described below, to simplify build target definition.


Below are summaries of public macro functionality. Full documentation is available in xls/build_rules/build_defs.bzl.


This macro generates Verilog from an DSLX target (currently given as a dslx_test target). This target also accepts several key/value parameters (as configs for generation):

  • clock_period_ps: The target clock period in picoseconds. Only used with the pipeline generator.
  • clock_margin_percent: The percent of the target clock period to reserve as "margin". Only used with the pipeline generator.
  • entry: The DSLX function to synthesize. If not given, a "best guess" will be made.
  • flop_inputs, flop_outputs: Whether to add flops at the inputs/outputs of the generated module. Only used with the pipeline generator.
  • generator: The code generator to be used. Can be either combinational or pipeline.
  • module_name: The desired name of the generated Verilog module.
  • pipeline_stages: The desired number of pipeline stages.
  • reset: The name of the reset signal to use, if any.
  • reset_active_low: Whether the reset signal is active low. Must also specify reset option. Only used with the pipeline generator.


Generates a source/header file pair to wrap invocation of a DSLX function by the JIT - this wrapper is a much more straightforward way to interact with the JIT versus direct use. It accepts a DSLX target and entry function in the same manner as above.


Main driver for:

  • Compiling DSLX files to IR
  • Running DSLX test cases (defined alongside the designs)
  • Proving DSLX/IR equivalence
  • Generating a benchmark for the associated IR
  • Proving logical equivalence for the optimized vs. unoptimized IR

In general, if one has a DSLX .x file, there should be an associated dslx_test target - this is the entry point to "downstream" capabilities (IR transformations, codegen, interpretation/JIT, etc.).

Note: This macro is targeted for refactoring, as it currently contains a broad swath of not-always-directly-related functionality.


This macro is for internal developer use only, for generating RTL with internally-released toolchains.

Bazel queries

Understanding the build tree for a new project can be difficult, but fortunately Bazel provides a powerful query mechanism. bazel query enables a user to examine build targets, dependencies between them, and much more. A few usage examples are provided here, but the full documentation (linked above) is comprehensive.

Finding transitive dependencies

To understand why, for example, the combinational verilog generator depends on the ABSL container algorithm library, one could run:

$ bazel query 'somepath(//xls/codegen:combinational_generator, @com_google_absl//absl/algorithm:container)'

This result shows that one such path goes through the :vast target. Another such path goes through the xls/ir:ir target, then the xls/ir:value target. somepath provides some path, not all paths (that's what allpaths is for).

Finding dependees ("reverse dependencies")

Sometimes it's useful to identify the set of targets depending on some other target - the rdeps query performs this:

$ bazel query 'rdeps(//xls/codegen:all, //xls/codegen:combinational_generator)'

This shows the transitive closure of all dependencies of the combinational generator, with the starting set being all targets in //xls/codegen:all. This set of dependees can quickly grow to be unmanageable, so keep the initial set (the first argument) as small as possible, and consider specifying a third argument for maximum search depth.