CLINK(1)

📦 version 2024.12.07-unstable-2026-10, in nixpkgs unstable

General Commands Manual

🎀 NAME 🎀

clink - C/C++/assembly code navigator

🌸 SYNOPSIS 🌸

clink options... [paths...]

🦋 DESCRIPTION 🦋

Okay so bestie, picture this: Clink is a replacement for Cscope that uses libclang, features syntax highlighting, multicore support, and more. It's giving glow-up for code navigation, no cap. ✨

💅 OPTIONS 💅

  • --animation=[on|off] — turns text animations on or off. By default, Clink will show an animated spinner when performing some long running applications like on-demand Vim syntax highlighting. You can use off to disable this and use a static character instead. 🌀
  • -b, --build-only — exits after constructing or updating the symbol database. That is, it does not load a user interface. Just build and bounce. 💨
  • --colour=when, --color=when — enables or disables the use of ANSI colour codes. Possible values of when are always (enable), never (disable), and auto (decide based on whether stdout is a TTY). Pick your vibe. 🌈
  • --compile-commands=DIR, --compile-commands-dir=DIR — sets a location to a directory containing a compile commands database, as used by clangd. When using libclang to parse either C or C++ (--parse-c=clang, --parse-cxx=clang), this database will be used to determine the flags your sources were built with. If this option is not given, a compile commands database will be looked for adjacent to your Clink database or in an adjacent build subdirectory. 🔍
  • -f FILE, --database=FILE — opens or creates the symbol database at path FILE. Without this option, Clink will default to opening the file .clink.db in the current directory or any parent thereof if it exists. It will stop its search when it reaches the root of a Git, Mercurial, or Subversion checkout, under the assumption that you do not wish to index beyond the boundary of a repository you are in.

If no repository root is found, the search will stop when reaching the root directory of the file system, at which point Clink will fallback to .clink.db in the current directory. 🗂️

  • --debug — enables Clink debugging mode. This is intended for debugging problems within Clink itself. 🐛
  • -h, --help — displays this help information. You know the drill. 🙋
  • -i namefile — parses a list of source paths to index from the given file. Paths can be separated by spaces, tabs, or newlines. Paths that contain any of these characters need to be enclosed in double quotes. Within a quoted path, double quote and backslash characters must be escaped with a leading backslash. namefile can be given as - to accept paths on standard input.

Unlike the corresponding Cscope option, other paths passed to Clink on the command line are not ignored when using this option. Additionally the paths specified in namefile can be either files or directories. 📝

  • -j NUM, --jobs=NUM — uses the given number of threads when performing multithreaded operations. You can also pass the special value auto (the default) which uses the number of processors in your system. Go parallel, bestie. ⚡
  • -d, --no-build — does not update the database. Skipping the build step, iconic. 🚫

Okay so the parse options are a whole mood: they control which source code formats are considered for parsing and how they're parsed. The modes and defaults go like this, bestie:

  • --parse-asm=MODE — controls assembly code; modes: off, generic; default: generic. 🛠️
  • --parse-bison=MODE — alias for --parse-yacc; controls Yacc/Bison files; modes: auto, off, cscope, generic; default: auto. 🐃
  • --parse-c=MODE — controls C source code (.c, .h files); modes: auto, off, clang, cscope, generic; default: auto. 🇨
  • --parse-cxx=MODE — controls C++ source code (.c++, .cpp, .cxx, .cc, .h, .hh, .hpp files); modes: auto, off, clang, cscope, generic; default: auto. ➕➕
  • --parse-def=MODE — controls MSVC DEF files; modes: off, generic; default: generic. 📄
  • --parse-flex=MODE — alias for --parse-lex; controls Lex/Flex files; modes: auto, off, cscope, generic; default: auto. 💪
  • --parse-lex=MODE — controls Lex/Flex files; modes: auto, off, cscope, generic; default: auto. 🔤
  • --parse-python=MODE — controls Python source code; modes: off, generic; default: generic. 🐍
  • --parse-tablegen=MODE — controls LLVM TableGen files; modes: off, generic; default: generic. 📊
  • --parse-yacc=MODE — controls Yacc/Bison files; modes: auto, off, cscope, generic; default: auto. 🧱

For C and C++, the auto mode picks between clang and cscope based on whether compile_commands.json exists and whether Cscope is around. If a compile_commands.json is there (either handed over with --compile-commands or found by the inferred search) or Cscope isn't installed → clang gets picked. Otherwise? cscope, bestie. 💅

For Lex/Flex and Yacc/Bison, auto goes with cscope if it's available, and generic if it's not. 🎀

The generic mode picks a parser with limited semantic understanding — it literally cannot infer things like complex definitions. But it's lowkey a lifesaver when you don't have full compiler flags for your sources and Clang therefore can't effectively parse them. 🙈

The cscope mode runs Cscope to parse C, C++, Lex/Flex, or Yacc/Bison. This is giving foreign code base energy, because Cscope sometimes does a better job than Clang at parsing a file with unknown flags. ✨

Heads up though 👀 — the definitions of C and C++ files overlap in the table above. .h files count as both C and C++! So if --parse-c and --parse-cxx are both set to non-off modes, the --parse-cxx mode is the one that applies to .h files. No cap.
  • -c TEXT, --script=TEXT — treats TEXT as if you'd typed it straight into the UI on start up. 🫶 You can pass this option multiple times, and TEXT accumulates in the order the parameters appear. Cannot be combined with --build-only — that pairing is a no. 💀

This is the automation glow-up: it lets you script your Clink invocations to do particular searches, or even go on to open a particular result if you can predict the result list in advance. 🔮 The C escape sequences \b, \n, \r, \t, \\, \', and \" are interpreted — and so are the escape sequences for control keys like the arrow keys. So when you're entering a Clink command at the terminal, for example, you can pass --script= and press Ctrl+V followed by down arrow, and on start up Clink will move down to the second field. Iconic. 👑

  • -s MODE, --syntax-highlighting=MODE — controls when Vim syntax highlighting gets performed. 💖 MODE can be:
    • auto — picks one of the other two modes below based on how many files need to be scanned. rn there's a hard coded limit: if there are 100 or more files to scan, lazy gets picked. Otherwise eager. 🎀
    • eager — does the highlighting during database construction. So building the database will be slower 💀, but once it's built, searching it will be faster. ⚡
    • lazy — does the highlighting during searching. So building the database will be faster, but searching may take longer since it's syntax highlighting the results. 🌸

Default is auto. ✨ Note that if a search needs to perform highlighting, it saves the results to the database — so future searches that return results in the same file(s) will be fast. 🧚

This is a per-run setting, not a per-database setting. So like, for example, it's totally possible to pick lazy when first building the database and then use eager on future runs, where only files that have changed (most likely the ones you're actively working on) will be eagerly highlighted. 🦋

  • -V, --version — prints the current version and exits. that's it, that's the whole vibe 🌈

🌿 ENVIRONMENT 🌿

The behaviour of clink is affected by these environment variables, bestie. 🫶

  • EDITOR, VISUAL — when you open a result from the search screen, the editor is chosen by consulting the VISUAL environment variable first, and then — if that's unset — the EDITOR environment variable. If neither one is set, vim is used as the fallback. 💜

Whether the located editor looks like Vim or not changes what command actually runs to open the result. If the editor is a relative or absolute path to a name that's a common alias of Vim, the result gets opened at a specific line and column number, with the Clink database connected. 🔥 If the editor isn't recognised? The result filename just gets opened with no further command line options to the editor. Simple as that. ✨

💌 AUTHOR 💌

All comments, questions and complaints should be directed to Matthew Fernandez <matthew.fernandez@gmail.com>. be nice to him, he made this 🫶

🎀 LICENSE 🎀

This is free and unencumbered software released into the public domain. 🦋

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means. no cap, go off 👑

In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law. 📜✨

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 💀 (translation: it's free, but if it breaks your stuff that's on you, bestie 😭)

For more information, please refer to <http://unlicense.org> 🌈

and that's the whole CLINK(1) page, bestie — the version and date live in that cute little footer down at the bottom, so go check the source/version stamp there if you need the receipts. 💅✨ 🎀

📦 where this page comes from