{"id":32348571,"url":"https://github.com/db7/tikl","last_synced_at":"2026-01-16T16:35:59.877Z","repository":{"id":320085886,"uuid":"1080702347","full_name":"db7/tikl","owner":"db7","description":"A simple tester inspired by LLVM-lit","archived":false,"fork":false,"pushed_at":"2026-01-15T13:53:42.000Z","size":256,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-15T15:36:13.162Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"0bsd","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/db7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-21T18:40:14.000Z","updated_at":"2026-01-15T13:53:47.000Z","dependencies_parsed_at":"2025-10-22T21:10:42.212Z","dependency_job_id":null,"html_url":"https://github.com/db7/tikl","commit_stats":null,"previous_names":["db7/tinl","db7/tikl"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/db7/tikl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/db7%2Ftikl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/db7%2Ftikl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/db7%2Ftikl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/db7%2Ftikl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/db7","download_url":"https://codeload.github.com/db7/tikl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/db7%2Ftikl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-24T07:56:04.231Z","updated_at":"2026-01-16T16:35:59.856Z","avatar_url":"https://github.com/db7.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tikl — Tikl ist kein Lit\n\ntikl is a deliberately small test driver inspired by [LLVM's\nlit](https://llvm.org/docs/CommandGuide/lit.html). It keeps the familiar `//\nRUN:` style annotations but trims the feature set down so it stays portable and\neasy to hack on.\n\n## Highlights\n\n- Reads test files looking for `RUN:`, `REQUIRES:`, and `UNSUPPORTED:`\n  directives, then executes the resulting shell pipelines.\n- Simple `%placeholder` substitution system that can be extended via an optional\n  config file (see `tikl.conf`), e.g. `%s` expands to the current test\n  path and `%b` maps it into `bin/…`.\n- Scratch directories default to `/tmp`, but `-T DIR` lets you keep temp files\n  on a different volume or sandbox.\n- Optional per-step timeout via `-t SECONDS` keeps hung tests from blocking the\n  whole run.\n- `%b`/`%B` map into `bin/` by default, yet `-b DIR` lets you route build\n  artefacts to a custom tree.\n- Feature flags (`-D feature`) gate tests via `REQUIRES`/`UNSUPPORTED`, which\n  keeps suites portable across different hosts.\n- In default mode, tikl enables `pipefail` when supported (falling back to\n  `/bin/bash` if needed), so `RUN:` pipelines fail if any stage fails.\n- Zero dependencies beyond a POSIX-ish `sh`, so it travels well across systems.\n\n## Building\n\n```sh\nmake\n```\n\nThis produces the `tikl` binary in the project root. A unit test and integration\nsmoke tests are available via `make test`.\n\nTo install into a prefix, run:\n\n```sh\nmake install PREFIX=/usr/pkg DESTDIR=/path/to/staging\n```\n\nAfter installation you will have `tikl`, the helper `tikl-check`, and the\naccompanying manpage; `man tikl` offers a condensed reference for day-to-day\nuse.\n\n## Quick start\n\n```sh\n./tikl -c tikl.conf test/basic.c\n```\n\nThe example above runs a single test under `test/`, relying on the built-in\n`%check` placeholder and the provided config to map it to the local\n`tikl-check`. After `tikl` and `tikl-check` are installed on your `PATH`, you no\nlonger need `-c tikl.conf`. For suites, point tikl at multiple files (or\nglob via your shell) and it will execute each test in sequence, reporting\n`[ RUN ]`, `[ SKIP ]`, `[FAIL]`, and `[  OK ]` statuses. Use `-q` for concise\noutput or `-v` to echo the shell commands as they run.\n\n### `%check` in action\n\nA typical test pairs a `RUN:` directive with `%check` so the helper script can\nverify a file's contents:\n\n```c\n// RUN: %cc %s -o %b\n// RUN: %b | %check\n// CHECK: expected content\n\n#include \u003cstdio.h\u003e\n\nint main(void) {\n    printf(\"expected content\\n\");\n    return 0;\n}\n```\n\n## `%check` and `CHECK:` helpers\n\nWith the default `tikl.conf` in this repository, `%check` expands to\n`tikl-check %s`, which reads `CHECK:` family directives in the test file and\nensures the output obeys each expectation. You don't have to pass `%s`\nexplicitly—tikl fills it in during substitution. Patterns are matched in order,\nso `CHECK:` expectations cannot leap backwards in the stream.\n\nSupported directives:\n\n- `CHECK:` looks for the literal fragment (or regex block) anywhere after the\n  previous match.\n- `CHECK-NOT:` fails when the substring appears anywhere in the remaining\n  output.\n- `CHECK-NEXT:` insists the next output line contains the fragment.\n- `CHECK-SAME:` keeps matching on the current line.\n- `CHECK-EMPTY:` expects the next line to be blank.\n- `CHECK-COUNT: N foo` requires `foo` to be seen exactly `N` times.\n- Embed regular expressions inline with `{{...}}`; surrounding text is matched\n  literally, so `CHECK: value={{[0-9]+}}` accepts `value=123`.\n- Use inline helper calls anywhere tikl performs substitutions—`RUN:` commands,\n  config values, and `CHECK` directives: `%(basename ARG [SUFFIX])` strips a\n  path down to its filename (optionally removing a trailing `SUFFIX` just like\n  the shell command), `%(dirname ARG)` returns the containing directory, and\n  `%(realpath ARG)` resolves symlinks. Arguments can contain other placeholders\n  or helper calls. These helpers are only active when tikl is running in its\n  default (non-`-L`) mode.\n\ntikl deliberately diverges from LLVM's FileCheck/lit in two ways:\n\n1. `%placeholder` tokens are expanded inside every `CHECK` variant. Values come\n   from your substitution config (e.g. `%foo` from `foo = ...`) plus the built-in\n   `%s`, `%S`, `%b`, and `%B`. Use `%%name` to keep the literal text `%name`.\n2. Literal text outside `{{...}}` is treated as literal text, so parentheses and\n   other regex metacharacters do not need escaping.\n3. Inline helper expressions `%(basename ARG [SUFFIX])` / `%(dirname ARG)` /\n   `%(realpath ARG)` run inside `CHECK` patterns, allowing quick path\n   manipulation without touching the surrounding shell script.\n\nPass `-L` to tikl when you need lit-compatible behaviour: `%` tokens are left\nverbatim and regex metacharacters regain their default meaning (so `foo(bar)`\nmust be written as `foo\\(bar\\)`).\n\nNeed a different tag? Append options after `%check`, e.g. `| %check --check-prefix=ALT`\nor `| %check -p ALT`, so only `ALT:` directives are honoured. Use multiple\n`--check-prefix`/`-p` flags to match several prefixes in one pass, or override\n`%check` entirely via your own config when a different helper better suits your\nproject. Add `--print-output-on-fail` (`-x`) to `%check` when you want\n`tikl-check` to dump the checked program's output after any failing directive.\n\n## Configuration\n\n| Placeholder | Expands to                               |\n|-------------|------------------------------------------|\n| `%s`        | Path to the current test file (relative to cwd) |\n| `%S`        | Directory containing the test (relative to cwd) |\n| `%t`        | Scratch file path unique to this command |\n| `%T`        | Scratch directory                        |\n| `%b`        | Path in `bin/` mirroring the source name |\n| `%B`        | Directory portion of `%b`                |\n\n`%check` maps to `tikl-check %s` out of the box. Additional placeholders come\nfrom `key = value` pairs in the config file. For example, `cc = cc -O2 -g` in\n`tikl.conf` makes `%cc` available inside `RUN:` lines. The bundled\n`tikl.conf` also defines `%a` as `%(realpath %s)` for cases that need an\nabsolute path. Use `-b DIR` if you need `%b` to land somewhere other than\n`bin/`.\n\nBy default tikl discards stdout/stderr from `RUN:` pipelines to keep logs\ncompact. Use `-v` to echo the shell commands, or `-vv` to also stream their\noutput.\n\nLines beginning with `-` inside the config file are treated as default command\nline flags (for example, `-D feature` or `-j 4`). Explicit command-line options\noverride any defaults supplied this way.\n\n### Handling flakes and expected failures\n\n- `ALLOW_RETRIES: N` gives each `RUN:` step up to `N + 1` attempts. tikl reruns a\n  failing command until it succeeds or the allowance is exhausted, logging each\n  retry when it happens.\n- `XFAIL:` marks a test as an expected failure. tikl reports `[XFAIL]` when a\n  step fails (or times out) and considers the test successful. If every step\n  passes instead, the run is flagged as `[XPASS]` and fails overall so the stale\n  expectation gets noticed. Add an optional reason after the colon for context.\n\n## Options summary\n\n- `-T DIR` — change the scratch directory root used for `%t`/`%T`.\n- `-b DIR` — change the root directory used for `%b`/`%B` (defaults to `bin`).\n- `-s DIR` — locate test sources under `DIR` so tikl can be invoked from a\n  separate build/bin directory.\n- `-T DIR` — used as-is for scratch paths (independent of `-b`/`-s`); use an\n  absolute path if you need it to be stable across working directories.\n- `-L` — force lit-compatible behaviour (turn off non-standard tikl extensions).\n- `-t SECONDS` — terminate any `RUN` command that exceeds the given wall-clock\n  budget (returns exit code 124).\n- `-V` — print the tikl version and exit.\n\n`-s DIR` is resolved to an absolute path. `-b DIR` is used as-is, so prefer an\nabsolute path if you want `%b`/`%B` to stay stable regardless of your working\ndirectory. For example, with sources under `/a/src`, binaries in `/b/bin`, and a\nworking directory of `/c`, run `tikl -s /a/src -b /b/bin x/test.c` to get\n`%s=/a/src/x/test.c`, `%S=/a/src/x`, `%b=/b/bin/x/test`, and `%B=/b/bin/x`.\n\n## Fuzzing\n\nAn AFL++ harness lives in `fuzz/`. It builds a tikl variant with command\nexecution disabled and feeds it curated directive seeds. See `fuzz/README.md`\nfor setup instructions and post-run triage tips.\n\n## Disclaimers\n\ntikl borrows the broad idea—and a few naming conventions—from LLVM's lit, but\nintentionally keeps to a smaller scope so it can stay approachable. If you need\nthe full-featured original, check out the [LLVM lit\ndocumentation](https://llvm.org/docs/CommandGuide/lit.html).\n\nNote that the original version of this program was mostly vibe-coded.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdb7%2Ftikl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdb7%2Ftikl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdb7%2Ftikl/lists"}