{"id":2986,"library":"lit","title":"LLVM Integrated Tester (lit)","description":"lit (LLVM Integrated Tester) is a portable command-line tool for executing LLVM and Clang style test suites, summarizing their results, and providing indication of failures. It is designed to be lightweight and flexible, supporting parallel test execution and various test formats. The current version is 18.1.8 and is actively maintained as part of the LLVM project.","status":"active","version":"18.1.8","language":"en","source_language":"en","source_url":"https://github.com/llvm/llvm-project/tree/main/llvm/utils/lit","tags":["testing","llvm","clang","command-line-tool","test-runner"],"install":[{"cmd":"pip install lit","lang":"bash","label":"Install via pip"}],"dependencies":[],"imports":[{"note":"lit is primarily a command-line tool that executes Python configuration files (lit.cfg.py). Direct import statements of 'lit' as a Python library for programmatic API calls are uncommon in application code. Configuration relies on predefined global objects like `lit_config` and `config` within these specific config files.","symbol":"lit_config","correct":"This is a global object implicitly available within lit.cfg.py / lit.site.cfg.py files."},{"note":"Similar to `lit_config`, the `config` object is exposed globally within `lit`'s Python configuration files (`lit.cfg.py`), allowing users to define test suite behavior without explicit Python imports from the 'lit' package itself.","symbol":"config","correct":"This is a global object implicitly available within lit.cfg.py / lit.site.cfg.py files."}],"quickstart":{"code":"# 1. Create a test directory and a lit configuration file:\n# my_project/\n# ├── lit.cfg.py\n# └── tests/\n#     └── my_test.txt\n\n# --- lit.cfg.py ---\n# This file is executed by lit to configure the test suite.\n# Define standard test formats.\nimport lit.formats\n\nconfig.name = 'MyProject'\nconfig.test_format = lit.formats.ShTest(not_tool='/usr/bin/not')\nconfig.suffixes = ['.txt']\n\n# Add an optional path to tools if they are not in PATH\n# config.substitutions = [('%my_tool', '/path/to/my_tool')]\n\n# --- tests/my_test.txt ---\n# RUN: echo \"Hello, lit!\" | FileCheck %s\n# CHECK: Hello, lit!\n\n# --- Run lit from the project root ---\n# In your terminal:\n# cd my_project\n# lit tests/","lang":"python","description":"This quickstart demonstrates how to set up a basic `lit` test suite. It involves creating a `lit.cfg.py` configuration file that `lit` uses to understand how to find and run tests, and a simple test file with `RUN` and `CHECK` directives. `lit` is then invoked from the command line against the test directory."},"warnings":[{"fix":"Focus on command-line invocation and Python configuration files (`lit.cfg.py`) for defining test behavior, rather than looking for a traditional Python API to import and call.","message":"lit is primarily a command-line testing tool. While written in Python, its main usage involves running the `lit` executable and configuring test suites via `lit.cfg.py` or `lit.site.cfg.py` files, rather than through direct Python API imports for general application logic. The Python files define test execution logic, not library functions to be called.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that your test directory hierarchy includes the necessary `lit.cfg.py` (or `lit.site.cfg.py`) files to define test suite parameters like `config.test_format` and `config.suffixes`.","message":"The `lit` command expects a `lit.cfg.py` or `lit.site.cfg.py` file to be present in the root of each test suite or discovered by searching upwards from the input path. Without these configuration files, `lit` cannot properly discover or execute tests.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that required LLVM tools (like `FileCheck` and `not`) are installed and accessible in your system's PATH, or specify their full paths using `config.substitutions` or directly in `config.test_format` (e.g., `not_tool='/usr/bin/not'`) within your `lit.cfg.py` file.","message":"The `lit` tool, especially for certain test formats, often relies on external LLVM utilities like `FileCheck` and `not`. If these are not available in the system's PATH, or explicitly configured in `lit.cfg.py`, tests that use them will fail.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}