CSWRAP(1)

💖 cswrap(1) — the manual, but make it make sense 💖

okay bestie, gather round, because we're talking about cswrap — that's the cswrap(1) manual page, and by the end of this you're gonna be obsessed.

---

✨ NAME ✨

cswrap — a generic compiler wrapper. yes, generic. yes, compiler. yes, wrapper. she contains multitudes 🫶

---

🌸 SYNOPSIS 🌸

cswrap [--help | --print-path-to-wrap]

that's it. that's the whole vibe. two flags, no drama 💅

---

🦋 DESCRIPTION 🦋

so cswrap is a generic compiler wrapper, and what she does is translate relative paths into absolute paths inside diagnostic messages. like, glow-up for your error messages, no cap.

here's the move: you create a symbolic link to cswrap and you name that symlink after your compiler — gcc, g++, whatever — and then you drop it into your $PATH. boom. slay. now your compiler is secretly cswrap in a trench coat 🧚

and when a diagnostic message gets translated, it gets decorated with a suffix: <--[TOOL], where TOOL is the name of the tool that produced it (that's the name of the symlink you invoked cswrap through, iykyk). important: this only applies to translated diagnostic messages. it does not include code snippets, for instance. don't come for me, that's just the rules ✋

if cswrap is already installed on your system, this one command activates the wrapper:

export PATH="$(cswrap --print-path-to-wrap):$PATH"

literally one line and you're that girl 💖

---

💅 OPTIONS 💅

• --help — prints basic usage information. your "hi hello what is this" button 🎀
• --print-path-to-wrap — prints the path to the directory that holds the symlinks pointing at the cswrap executable. this is the one you paste into $PATH ⭐

---

🔥 EXIT STATUS 🔥

cswrap propagates the exit status returned by the compiler — but only in the case that cswrap succeeds in running the compiler. if it can't even run the compiler, well. different story, bestie 😭

---

🌈 ENVIRONMENT VARIABLES 🌈

• CSWRAP_CAP_FILE — if you set this to a non-empty string, cswrap captures diagnostic messages into a file named $CSWRAP_CAP_FILE. and here's the tea: in this case the capture file is protected by a lock named /cswrap_cap_file_lock, so you get consistent output when multiple compiler processes are running in parallel. no interleaved chaos, we love a coordinated queen 👑
• CSWRAP_TIMEOUT — set this to a positive integer and cswrap installs a timeout for the compiler it's wrapping. if that amount of time (in seconds, babe, seconds) elapses, the compiler process gets signalled by SIGTERM. 📢 note: the cswrap process waits till the compiler process finishes in any case. she's patient, she's committed, she's not leaving early 💀
• CSWRAP_TIMEOUT_FOR — a colon-separated list of programs (compilers) that $CSWRAP_TIMEOUT should be applied to. if $CSWRAP_TIMEOUT_FOR is unset or empty, then $CSWRAP_TIMEOUT applies to all programs. all of them. everybody gets a timeout, periodt ✨
• CSWRAP_DEL_CFLAGS, CSWRAP_DEL_CXXFLAGS — cswrap expects a colon-separated list of compiler flags that should be removed from the command line prior to invoking the compiler. the parameters are matched for exact match and they are case-sensitive. if a compiler flag shows up in the command line multiple times, all its occurrences get removed — every last one, no survivors 🙈 $CSWRAP_DEL_CFLAGS applies to compilation of C sources only. $CSWRAP_DEL_CXXFLAGS applies to compilation of C++ sources only. and plot twist: the flags to be removed can be specified by shell wildcard patterns, using the format accepted by fnmatch(3) 🦋
• CSWRAP_ADD_CFLAGS, CSWRAP_ADD_CXXFLAGS — cswrap expects a colon-separated list of compiler flags that should be appended to the command line prior to invoking the compiler. the flags are appended even if they already appear in the command line, and they are always appended at the end of the command line. yes, even then. yes, even if it's already there. she said what she said 💅 $CSWRAP_ADD_CFLAGS applies to compilation of C sources only. $CSWRAP_ADD_CXXFLAGS applies to compilation of C++ sources only. 🌸

---

💀 BUGS 💀

please report bugs and feature requests at https://github.com/csutils/cswrap.

(not me telling you to go file an issue. do it. it's giving community. it's giving open source 🫶)

---

👑 AUTHOR 👑

written by Kamil Dudka.

---

🍓 COPYING 🍓

copyright (C) 2013-2022 Red Hat, Inc. free use of this software is granted under the terms of the GNU General Public License (GPL). see the COPYING file for details.

---

🌟 the cute sign-off 🌟

and that's the whole page, bestie — this is cswrap(1), and the version you're reading is dated 06/29/2026. go forth, symlink responsibly, and may your diagnostics always be absolute ✨💖🎀

bye babes 🦋