rules_tcl

Bazel rules for building, testing, and managing Tcl applications and libraries.

Overview

rules_tcl provides a comprehensive set of Bazel rules for working with the Tcl scripting language. It supports:

• Building executables with tcl_binary
• Creating reusable libraries with tcl_library
• Writing and running tests with tcl_test
• Code quality checks with linting and formatting aspects
• Dependency management through Tcl's package system

The rules handle Tcl's package system, runfiles, and provide seamless integration with Bazel's build system.

Quick Start

Setup

Add the following to your MODULE.bazel file:

bazel_dep(name = "rules_tcl", version = "{version}")

register_toolchains(
    "@rules_tcl//tcl/toolchain",
)

Basic Example

Create a simple Tcl executable:

load("@rules_tcl//tcl:tcl_binary.bzl", "tcl_binary")

tcl_binary(
    name = "hello",
    srcs = ["hello.tcl"],
)

Library Example

Create a reusable Tcl library:

load("@rules_tcl//tcl:tcl_library.bzl", "tcl_library")

tcl_library(
    name = "greetings",
    srcs = [
        "greet.tcl",
        "pkgIndex.tcl",  # Required for libraries
    ],
)

Tcl Bazel rules

Rules

• tcl_binary
• tcl_format_test
• tcl_library
• tcl_lint_test
• tcl_toolchain

Aspects

• tcl_format_aspect
• tcl_lint_aspect

tcl_binary

load("@rules_tcl//tcl:defs.bzl", "tcl_binary")

tcl_binary(name, deps, srcs, data, env, main)

A tcl_binary is an executable Tcl program consisting of a collection of .tcl source files (possibly belonging to other tcl_library rules), a *.runfiles directory tree containing all the code and data needed by the program at run-time, and a stub script that starts up the program with the correct initial environment and data.

load("@rules_tcl//tcl:defs.bzl", "tcl_binary")

tcl_binary(
    name = "foo",
    srcs = ["foo.tcl"],
    deps = [
        ":bar",  # a tcl_library
    ],
)

ATTRIBUTES

tcl_format_test

load("@rules_tcl//tcl:defs.bzl", "tcl_format_test")

tcl_format_test(name, target)

A test rule for performing formatting checks on a Tcl target.

The tcl_format_test rule creates a test that verifies a Tcl target's source files are properly formatted according to the configured style. This is useful for enforcing consistent code style in CI/CD pipelines.

Usage:

load("@rules_tcl//tcl:tcl_format_test.bzl", "tcl_format_test")

tcl_library(
    name = "mylib",
    srcs = ["mylib.tcl", "pkgIndex.tcl"],
)

tcl_format_test(
    name = "mylib_format",
    target = ":mylib",
)

Run the format test with:

bazel test //path/to:mylib_format

The test will fail if any source files are not properly formatted. Unlike tcl_lint_test, this test includes pkgIndex.tcl files in the formatting check.

ATTRIBUTES

tcl_library

load("@rules_tcl//tcl:defs.bzl", "tcl_library")

tcl_library(name, deps, srcs, data)

A Tcl library that can be depended upon by other Tcl targets.

A tcl_library represents a Tcl package that can be imported using Tcl's package require command. The library must include a pkgIndex.tcl file in its srcs attribute, which defines the package metadata and how to load the package.

Important: The pkgIndex.tcl file must be included in the srcs attribute. This file is used by Tcl's package system to locate and load the package.

Example:

load("@rules_tcl//tcl:defs.bzl", "tcl_library")

tcl_library(
    name = "mylib",
    srcs = [
        "mylib.tcl",
        "pkgIndex.tcl",
    ],
    deps = [
        ":otherlib",  # Another tcl_library
    ],
    visibility = ["//visibility:public"],
)

The library can then be used as a dependency in other targets:

tcl_binary(
    name = "app",
    srcs = ["app.tcl"],
    deps = [":mylib"],
)

ATTRIBUTES

tcl_lint_test

load("@rules_tcl//tcl:defs.bzl", "tcl_lint_test")

tcl_lint_test(name, target)

A test rule for performing linting checks on a Tcl target.

The tcl_lint_test rule creates a test that verifies a Tcl target passes linting checks. This is useful for enforcing code quality in CI/CD pipelines.

Usage:

load("@rules_tcl//tcl:tcl_lint_test.bzl", "tcl_lint_test")

tcl_library(
    name = "mylib",
    srcs = ["mylib.tcl", "pkgIndex.tcl"],
)

tcl_lint_test(
    name = "mylib_lint",
    target = ":mylib",
)

Run the lint test with:

bazel test //path/to:mylib_lint

The test will fail if the target has any linting errors. The test automatically excludes pkgIndex.tcl files from linting, as these are typically generated or follow a specific format.

ATTRIBUTES

tcl_toolchain

load("@rules_tcl//tcl:defs.bzl", "tcl_toolchain")

tcl_toolchain(name, tclcore, tclint, tcllib, tclsh)

A toolchain rule that defines the Tcl interpreter and libraries for building Tcl targets.

The tcl_toolchain rule configures the Tcl environment used by all tcl_binary, tcl_library, and tcl_test targets. It specifies:

• The Tcl interpreter (tclsh) to use for execution
• The Tcl core library files (tclcore)
• The Tcl standard library (tcllib)
• Optional linting tools (tclint) for code quality checks

Typically, you don't need to create a tcl_toolchain directly. The rules provide a default toolchain that you register in your MODULE.bazel:

register_toolchains("@rules_tcl//tcl/toolchain")

If you need a custom toolchain (e.g., a different Tcl version), you can define your own:

load("@rules_tcl//tcl:tcl_toolchain.bzl", "tcl_toolchain")

tcl_toolchain(
    name = "my_tcl_toolchain",
    tclsh = "@tcl_8_6//:tclsh",
    tclcore = "@tcl_8_6//:tclcore",
    tcllib = "@tcllib//:tcllib",
    tclint = "@tclint//:tclint",  # Optional, for linting
)

ATTRIBUTES

tcl_format_aspect

load("@rules_tcl//tcl:defs.bzl", "tcl_format_aspect")

tcl_format_aspect()

An aspect for performing formatting checks on Tcl targets.

The tcl_format_aspect checks that Tcl source files are properly formatted according to the configured style. It uses tclint to verify formatting.

Usage:

Apply the aspect to check formatting of all dependencies via command line:

bazel build //my:target --aspects=@rules_tcl//tcl:tcl_format_aspect.bzl%tcl_format_aspect

Or configure it in your .bazelrc file to enable format checking for all builds:

# Enable tclfmt for all targets in the workspace
build:tclfmt --aspects=@rules_tcl//tcl:tcl_format_aspect.bzl%tcl_format_aspect
build:tclfmt --output_groups=+tcl_format_checks

Then use it with:

bazel build //my:target --config=tclfmt

Or use it in a test:

load("@rules_tcl//tcl:tcl_format_test.bzl", "tcl_format_test")

tcl_format_test(
    name = "format_check",
    target = ":my_library",
)

Ignoring targets:

To skip format checking for specific targets, add one of these tags:

• no_tcl_format
• no_tclformat
• no_tclfmt
• noformat
• nofmt

tcl_library(
    name = "generated_code",
    srcs = ["generated.tcl"],
    tags = ["no_tcl_format"],
)

The aspect processes all source files including pkgIndex.tcl files.

ASPECT ATTRIBUTES

ATTRIBUTES

tcl_lint_aspect

load("@rules_tcl//tcl:defs.bzl", "tcl_lint_aspect")

tcl_lint_aspect()

An aspect for performing linting checks on Tcl targets.

The tcl_lint_aspect applies linting checks to all Tcl targets in the dependency graph. It uses tclint to check for code quality issues.

Usage:

Apply the aspect to check all dependencies of a target via command line:

bazel build //my:target --aspects=@rules_tcl//tcl:tcl_lint_aspect.bzl%tcl_lint_aspect

Or configure it in your .bazelrc file to enable linting for all builds:

# Enable tclint for all targets in the workspace
build:tclint --aspects=@rules_tcl//tcl:tcl_lint_aspect.bzl%tcl_lint_aspect
build:tclint --output_groups=+tcl_lint_checks

Then use it with:

bazel build //my:target --config=tclint

Or use it in a test:

load("@rules_tcl//tcl:tcl_lint_test.bzl", "tcl_lint_test")

tcl_lint_test(
    name = "lint_check",
    target = ":my_library",
)

Ignoring targets:

To skip linting for specific targets, add one of these tags:

• no_tcl_lint
• no_lint
• nolint

tcl_library(
    name = "legacy_code",
    srcs = ["legacy.tcl"],
    tags = ["no_tcl_lint"],
)

The aspect only processes source files (not generated files) and excludes pkgIndex.tcl files.

ASPECT ATTRIBUTES

ATTRIBUTES