Tip
Documentation TsukiNi22/xstyle (v1.2.0): user guide, concepts, every option and rule (searchable, EN / FR) and the interactive project graph.
Checker and fixer of my coding style, C++ first (cpp-style, cpp-comments, cpp-class layout, libutils
usage), then C, assembly (NASM x86-64), Python, shell, Rust and the generic rules of every language. Each issue is printed with its file, line
and column (terminal hyperlink), the rule broken and the fix proposed; a summary counts the issues by severity
(unforgivable, major, minor, negligible) and by rule, plus one mandatory reminder that is never counted
(R34). Everything that can be fixed safely is fixed
with --fix, for every rule or only some codes, files or directories.
Moved out of ai-utils (style/xstyle, history kept) into its own repository: RPM / DEB / Arch (pacman) packages
on the gh-pages branch, also listed in my-universe with the other packages of TsukiNi22.
- Dependencies
- Packages
- Quick Setup - 1 (all)
- Quick Setup - 2 (Limited)
- Usage
- libutils
- Languages
- Rules
- Development
- Workflows/Release
Caution
The MIT license of this project (LICENSE) only applies to the code of xstyle itself, not to its dependencies.
| Name + Link | Status | Last Update |
|---|---|---|
| libutils |
| Name | Version | Fedora (dnf) |
Debian/Ubuntu (apt) |
Arch (pacman) |
|---|---|---|---|---|
clang++ / cmake |
C++20 / >= 3.20 |
clang cmake |
clang cmake |
clang cmake |
libutils |
4.x (>= 4.1.0, >= 4.2.0 on Arch) |
libutils |
libutils |
libutils |
| GoogleTest (tests only) | any | gtest-devel |
libgtest-dev |
gtest |
ccache [OPTIONAL] |
any | ccache |
ccache |
ccache |
Note
The libutils checks read the installed headers: /usr/include, /usr/local/include, ~/.local/include, CPATH, else
its Windows build (the MinGW sysroot of the mingw64-libutils packages, or a source build of libutils.sh windows).
xstyle --libutils-check compares them with the reference of the libutils skill of ai-utils
($XSTYLE_LIBUTILS_SKILL, else ~/.claude/skills/libutils, else ~/personal_delivery/other/ai-utils/libutils/libutils).
Note
Every package has a pre-release/unstable version named <package_name>-pre.
The -pre packages are marked as obsolete by any release/stable package (without -pre) of the same version or higher.
The same packages exist as RPM (Fedora), DEB (Debian/Ubuntu) and Arch Linux (pacman, .pkg.tar.zst): same names, content and dependencies.
| File Name | Content |
|---|---|
xstyle |
Install the default package (xstyle-op) |
xstyle-op |
Executable compiled with the optimization options |
xstyle-db |
Executable compiled with the debug options (intended for debugging only) |
xstyle-as |
Executable compiled with the asan options (intended for debugging only) |
Warning
The three variants install the same /usr/bin/xstyle: only one of them can be installed at a time.
Every package also installs the completion of the shells (flags, rule codes, severities, languages, comma lists), generated by xstyle --completion bash|zsh|fish:
| Shell | File | Loaded |
|---|---|---|
| bash | /usr/share/bash-completion/completions/xstyle |
on demand by bash-completion |
| zsh | /usr/share/zsh/site-functions/_xstyle |
new shells (compinit) |
| fish | /usr/share/fish/vendor_completions.d/xstyle.fish |
on demand |
Setup into
/usr/local(or~/.local)
git clone https://github.com/TsukiNi22/xstyle.git
cd xstyleexport BUILD_DIR=build
cmake -S . -B $BUILD_DIR -DCMAKE_BUILD_TYPE=Optimized
cmake --build $BUILD_DIR --parallel $(nproc) # ./xstyle at the root + build/completion/
sudo cmake --build $BUILD_DIR --target install --parallel $(nproc) # /usr/local/bin/xstyle + the completions
cmake --install $BUILD_DIR --prefix ~/.local # or without root: ~/.local/bin/xstyleSetup into
/usr
Warning
If during the installation using tools like dnf, apt... you see an invalid hash error, reset the cache of the tool or relaunch the setup.sh script.
If the error still persists, it might be due to an error in the repository.
Warning
Restriction: fedora-based (rpm), debian-based (deb), arch-based (pacman)
Note
The usage of sudo in the script can be removed with the --no-sudo argument.
Every package repository of TsukiNi22 at once (xstyle, libutils, brain, context-forge...), with my-universe:
curl -fsSL https://tsukini22.github.io/my-universe/install.sh | bash -s # then: sudo dnf install xstyle (apt / pacman)Or only the one of xstyle, with its setup script (no clone needed). It registers the package repository (gh-pages branch) so the system package manager can install the packages:
- Detect the distribution from
/etc/os-release(rpm,deborarchbased). rpm: add/etc/yum.repos.d/xstyle.repoand import the GPG key.deb: add the GPG key in/etc/apt/keyrings/xstyle.gpg, the source in/etc/apt/sources.list.d/xstyle.list, thenapt-get update.arch: add the GPG key to the pacman keyring (pacman-key --add+--lsign-key), the[xstyle]repository in/etc/pacman.conf(SigLevel = Required), thenpacman -Sy.- With
--installonly: install the packagexstyle(--prefor the unstable one).
wget -qO- https://raw.githubusercontent.com/TsukiNi22/xstyle/main/setup.sh | bash -s -- --installor with curl:
curl -fsSL https://raw.githubusercontent.com/TsukiNi22/xstyle/main/setup.sh | bash -s -- --install| Argument | Effect |
|---|---|
--no-sudo |
Run without sudo (the script must already run as root) |
--install |
Also install the package (by default only the mirror & GPG key are setup) |
--pre |
Select the pre-release/unstable package (xstyle-pre) |
-h, --help |
Display the usage |
xstyle # check the current directory (recursive), every known language
xstyle -r src include # only these directories (recursive with -r)
xstyle src/core/Engine.cpp # one file
xstyle -S # only the summary (counters by severity and by rule)
xstyle --rtk # compact output for an AI (5x fewer tokens): no color, no source, one line per issue
xstyle -s major # only the major and unforgivable issues
xstyle -m force,manual # only these fix levels (auto, force, ask, manual), comma separated
xstyle -c CPP-THIS,LU # only these rules (code, prefix or pattern: CPP, LU-*, G-TAB)
xstyle -i G-TODO,CPP-AUTO # every rule except these
xstyle -l cpp,rs # only the C++ and Rust files (-t: only the most used language)
xstyle --ignore-path 'tests/**:CPP-AUTO' # rules ignored on some paths only (GLOB[:CODES], ; separated)
xstyle --exclude-from paths.txt # the -e patterns of a file (one per line)
xstyle --no-gitignore # also the files ignored by git (skipped by default)
xstyle --show-ignored # also list the issues silenced (comment, path, rule), not only their count
xstyle --no-inline-ignore # audit: no suppression comment, no .xignore, no [[path]] of .xconfig
xstyle --add-ignore -c CPP-AUTO # write xstyle: ignore CPP-AUTO on the lines of these issues (-n to preview)
xstyle --fix # fix everything that can be fixed
xstyle --fix CPP-NULL,G-TRAILING src # fix only these rules, only in src
xstyle --fix --force # also the [force-fix] ones (can change the behavior: check with -n first)
xstyle --fix --dangerous-force # also the [danger-fix] ones: guessed (types from the usage...), can be wrong
xstyle --fix --header default # missing file headers with the XARTANIA banner (none | default | <text>), no question
xstyle -f -n -c CPP -r src/core # preview (dry run) of the C++ fixes of one directory
xstyle -o report.md # report in this file (.txt, .md or .json), nothing in the terminal
xstyle -x CPP-THIS # explain a rule, -L lists every rule
xstyle --diff # only the lines changed since HEAD (staged + not staged, new files)
xstyle --diff-ref main # only the lines changed since a branch / tag / commit
xstyle --staged --fix # only the staged lines (pre-commit hook)
xstyle --fix --commit # fix, then commit the fixed files: chore(style): apply the xstyle fixes (...)
xstyle --fix --commit-all --message "chore(core): ..." # fix + commit every tracked change with the fixes
xstyle --libutils-check # is the libutils skill reference up to date? (exit 0 yes, 1 no)
xstyle --r34 # I have read the Terms and Conditions of Rule 34, I accept them: R34 is not displayed-
Paths: files or directories given as bare arguments; with no path the current directory is scanned recursively. Hidden folders,
build*,cmake-build-*,third_party,extern,vendor,node_modules... and thegenerated_*files are skipped, so are the files ignored by git (--no-gitignorechecks them; a file given as argument is always checked) and the paths of the.xignorefiles;-e build,*.gen.hppexcludes more (folder name, path prefix or glob), see Ignoring rules and files. -
Fix level of every issue, right after its code (
Fixcolumn of the table below,fixfield of the JSON):Tag Fixed by Meaning [auto-fix]--fixsafe, the behavior can't change (spaces, includes order, nullptr,[ ]->[[ ]]when equivalent...)[force-fix]--fix --forcecan change the behavior: set -euo pipefail(a failing command now stops the script),encoding="utf-8"(a file in another encoding now fails),[ a -o b ]/ unquoted patterns, a comment replaced; preview with-n[danger-fix]--fix --dangerous-force(implies--force)guessed, can be wrong: Python types guessed from the usage / the name / a local variable, T | None(Python 3.10+),static_castof a C pointer cast (reinterpret_castneeded if it doesn't compile)[ask-fix]--fix+ a questionthe missing file header: banner [n]one,[d]efault(XARTANIA) or[t]ext+ description, per file (upper case answer: same for the next files);--header none|default|<text>and--header-desc "..."answer without question (CI, no terminal: skipped)[manual]by hand needs a decision a tool can't take (a type to write, a name to choose, a code to rewrite with libutils...) Python type hints, per parameter / return:
- certain (
[auto-fix]): a literal default (level=2->level: int = 2),-> Nonewithout anyreturn value/yield, everyreturnof the same certain type: literal, display ([...]list,{...}dict / set,(a, b)tuple), builtin (len()int,str(),isinstance()bool...), stdlib (os.path.join()str,os.path.exists()bool...),not/is/in(bool),"text" + x(str); - guessed (
[danger-fix]): from the usage in the body (x.split()str,x.append()list,x.items()dict,open(x)str,range(x)int), from the name (is_*/verbosebool,*_path/namestr,count/sizeint), a local variable assigned once (parts = line.split(",")thenreturn parts), comparisons==/<(bool, can be overloaded), methods on an unknown value (x.strip()str),T | None; - unknown (
[manual], listed as "by hand"): anything else; a stub (...,raise NotImplementedError) or a generator is never typed.
- certain (
-
Filter by level:
-m auto,force,dangerous,ask,manual(one or several,forced/dangeraccepted) keeps only those issues, in the display, the counters, the report and--fix(xstyle --fix --force -m autoapplies only the safe fixes). -
Templates: a file with
{{NAME}}placeholders is not valid code yet, only the generic rules are checked there. -
Fix: the fixes are applied in passes (a fix can reveal another issue:
[[nodiscard]]->_nodiscard->#define _Attributemissing -> added), only the fixable rules (yesin the table) are touched, the logic never. Review the result withgit diff. -
AI mode (
--rtk, orXSTYLE_RTK=1): what an assistant needs and nothing else: a legend line,>fileonce, thenline:col CODE severity fix message => fix|hintper issue (the message / hint shared by every issue of a rule written once in* CODE ...lines at the end),fixed N: CODExK, one= N issues ...summary line, errors on one plain line. No color, no hyperlink, no source line, no table. The skills and theCLAUDE.mdfiles run xstyle this way. -
Hyperlinks: the locations are OSC 8 links in the terminal (
--link file, default), orvscode://links (--link vscode, opens the file at the line),--no-color/NO_COLORfor plain text. -
Changed lines (
--diff,--diff-ref,--staged): only the issues on the lines changed in git (whole file issues when the file changed), with no path the changed files themselves; the fixes follow the same filter. -
Commit (
--commit,--commit-all, with--fix): the message ischore(style): apply the xstyle fixes (N issues)with one line per rule (or--message).--commitonly takes the files that had no change before the fixes (their own changes would end up in the commit, they are listed and left),--commit-alltakes every tracked change too. Never with--dry-run. -
Exit status:
0clean,1issues left (from--fail-on <severity>, default every severity),255error. The mandatory rule (R34) is never counted: not in the exit status, the totals,--fail-onnor the pre-commit hook. -
Environment:
XSTYLE_CODES,XSTYLE_IGNORE,XSTYLE_IGNORE_PATH,XSTYLE_SEVERITY,XSTYLE_EXCLUDE,XSTYLE_LIBUTILS,XSTYLE_LINK,XSTYLE_REPORTgive the default of the flag of the same name;XSTYLE_R34=1is--r34. They win over the.xconfigof the project, the command line wins over both.
R34 is the only rule of the severity mandatory: Rule 34: if it exists, there is porn of it. No exceptions. It is a
reminder, not a style rule:
- it is displayed once per run, for the whole project, with a green link to the article of the rule
(https://en.wikipedia.org/wiki/Rule_34), and in the
--rtkoutput as a! R34 ...line; - it is never counted: not in the totals (its own
mandatoryrow in the summary), the exit status,--fail-onnor the hook;-sdoes not hide it,-c/-i/-mselect it like any other rule; - it is acknowledged (not displayed any more) by the integer 34, or r34 (any case) in an identifier, a string
or a comment of a checked file, by a file named R34.md in the directory where xstyle is run, by the flag
--r34or byXSTYLE_R34=1; xstyle --fix --forcewritesR34.md(a long explanation of the rule: statement, origin, spread, interpretation), which acknowledges it; an existingR34.mdis never replaced;xstyle -x R34explains it.
In a comment of the file (Markdown: in a <!-- --> comment); without a code every rule is silenced there, a code can be
a prefix or a pattern (CPP, LU-*), a reason after the codes starts with a lower case word or a parenthesis:
| Comment | Silences |
|---|---|
xstyle: ignore [CODE,...] |
this line |
xstyle: ignore-next [N] [CODE,...] |
the next line (the next N lines) |
xstyle: off [CODE,...] ... xstyle: on [CODE,...] |
the lines between (up to the end of the file without on; on alone closes every open region) |
xstyle: ignore-file [CODE,...] |
the whole file |
xstyle: skip-file |
the file is not checked nor counted |
A comment that silences nothing any more is reported by G-UNUSED-IGNORE (removed by --fix; an off region loses its
on too). The rules that are off (libutils), R34 and the comments silencing G-UNUSED-IGNORE itself are never reported; only a
comment naming it (xstyle: ignore G-UNUSED-IGNORE) silences it, never a comment of every rule.
By path, a .xignore file in any directory of the project (read from the project root down to the file, like a
.gitignore): one pattern per line, # comments, * / ? / ** jokers, a pattern with a / is relative to the
directory of the .xignore (else a name at any depth), name/ matches directories only, !pattern includes again (the
last matching line wins). A line ending with :CODE,... does not exclude the paths: it ignores these rules there.
# .xignore
third_party_copy/ # not checked at all
*.gen.hpp
!keep.gen.hpp
tests/**:CPP-AUTO,G-TODO # still checked, these rules ignoredProject configuration, .xconfig (TOML; the closest one from the working directory up to the project root): the
default of the flags (the environment and the command line win, ignore is added to -i), exclude / ignore-path
patterns relative to its directory, and [[path]] tables:
# .xconfig
severity = "minor" # -s
fail-on = "major" # -F
ignore = ["CPP-AUTO"] # -i (added)
lang = ["cpp", "py"] # -l
libutils = "auto" # -u
gitignore = true # false: --no-gitignore
inline-ignore = true # false: --no-inline-ignore
exclude = ["third/**"] # like a .xignore line
ignore-path = ["examples/*:G-TODO"]
[[path]]
match = ["tests/**", "bench/**"]
ignore = ["CPP-FUNC-LENGTH", "CPP-UNCHECKED-RETURN"]
[[path]]
match = "generated/"
exclude = trueKeys: code, ignore, severity, fail-on, lang, mode, libutils, top, link, header, header-desc, r34,
gitignore, inline-ignore, exclude, ignore-path; an unknown key or a wrong value stops xstyle with <file>:<line>.
Flags: -i CODES (every path), --ignore-path 'GLOB[:CODES];...' (relative to the working directory, no codes:
every rule), -e PATTERNS / --exclude-from FILE (paths skipped), --no-gitignore, --no-inline-ignore (audit: the
comments, the .xignore files and the [[path]] tables are not read; the flags and the other keys of .xconfig stay).
Adopting xstyle on old code: --add-ignore writes xstyle: ignore CODE,... at the end of the line of every issue
left (after -c / -s / -m / --diff; -n previews), in the comment of the language (//, #, --, ;). Never on
a line ending in a string, a here-document or a \ continuation, an empty line, a line that already has a directive,
nor for a whole file issue; a comment that would silence nothing (it removes the issue itself, like a trailing
whitespace) is taken back. Markdown, JSON and YAML files are left as they are.
The issues silenced by a comment, a rule by path or -i are counted (Ignored 3 issue(s) silenced (comment 1, path 2), | ignored 3 (...) in --rtk, ignored in the JSON report), --show-ignored lists them.
std::cout << "\033[1m"; // xstyle: ignore LU-ANSI
// xstyle: ignore-next 2 CPP-AUTO
auto lambda = [](int x) {return x * 2;};
auto other = [](int x) {return x * 3;};
// xstyle: off CPP-ONELINER-ALIGN (table aligned by hand)
// ...
// xstyle: on
// xstyle: ignore-file CPP-GUARD-MISSING (no guard on purpose)The LU-* rules are enabled when libutils is installed (/usr/include, /usr/local/include,
~/.local/include or CPATH) and used by the project (find_package(utils) / utils::utils in the root
CMakeLists.txt, or utils.hpp included); --libutils on|off forces them. Inside libutils itself they are off.
- includes: one root
<utils/utils.hpp>preceded by the#define _Sectionof every section used (detected from theutils::<section>::names and the attribute macros of the file), never a libutils header one by one; [[nodiscard]],[[maybe_unused]],alignas(...)... -> the libutils macros (_nodiscard,_unused,_alignas...);- deprecated names -> new names, read from the
_migrationaliases of the installed headers, plus the names libutils v4.0.0 removed (isloaded()->isLoaded(),utils::network::socket::is_ip->utils::network::is_ip,setStyle->set_style,fixed_string->FixedString...: a v3 code moved to v4 is told what to write); - code that libutils already gives: standard exceptions,
argvparsed by hand, raw ANSI sequences, BSD sockets,pipe/fork/epoll/shm_open/dlopen, thread pools, degree / radian conversions, base64, verbose flags, string distances (hint with the libutils class to use).
| Language | Files | Rules |
|---|---|---|
| C++ | .cpp .cc .cxx .hpp .hh .hxx .ipp .tpp .inl .h |
generic + CPP-* + LU-* (libutils installed and used) |
| C | .c (+ .h of a project without C++ sources) |
generic + C-* (the layout rules shared with the C++ under their own C- code, then the C rules) |
| Assembly (NASM x86-64) | .asm .nasm .s .S |
generic + ASM-* (a GAS file, AT&T or .intel_syntax: ASM-HEADER + generic only) |
| Rust | .rs |
generic + RS-* (tests: #[cfg(test)] module, tests/, benches/, examples/ excepted for unwrap / panic) |
| Python | .py |
generic + PY-* |
| Shell | .sh .bash |
generic + SH-* |
| Lua, JS / TS, CMake | .lua, .js .mjs .ts .tsx .jsx, CMakeLists.txt .cmake |
generic |
| Makefile, YAML | Makefile .mk, .yml .yaml |
generic (no indentation by 4, Makefile recipe tabs allowed) |
| JSON, Markdown | .json, .md |
generic (Markdown: trailing spaces allowed) |
Any other file is skipped when a directory is scanned; given explicitly, it gets the basic generic rules.
Severity: unforgivable > major > minor > negligible; mandatory is outside this scale (displayed, never counted).
Languages: * = every file checked.
| Code | Severity | Fix | Languages | Rule |
|---|---|---|---|---|
R34 |
mandatory | force | * | Rule 34: if it exists, there is porn of it. No exceptions (R34) |
G-CRLF |
major | auto | * | Windows line endings (CRLF), use LF |
G-TAB |
major | auto | * | Tab used for the indentation, use 4 spaces (except Makefile recipes) |
G-TRAILING |
minor | auto | * | Trailing whitespace |
G-EMPTY-LINES |
minor | auto | * | Two or more consecutive empty lines, one is the maximum |
G-EOF-NEWLINE |
negligible | auto | * | No newline at the end of the file |
G-EOF-EMPTY |
negligible | auto | * | Empty lines at the end of the file |
G-TODO |
minor | - | * | TODO / FIXME / XXX tag, describe the limitation in a normal comment instead |
G-UNUSED-IGNORE |
minor | auto | * | Suppression comment (xstyle: ignore / ignore-next / ignore-file / off) that silences nothing, remove it |
G-INDENT |
negligible | - | cpp,c,py,sh,lua,js,rs,cmake | Indentation that is not a multiple of 4 spaces |
CPP-USING-NAMESPACE |
unforgivable | - | cpp | using namespace, always write the fully qualified names |
CPP-GUARD-MISSING |
major | auto | cpp | Header without include guard (#ifndef NAME_H / #define NAME_H) |
CPP-PRAGMA-ONCE |
minor | auto | cpp | #pragma once instead of the include guard NAME_H |
CPP-GUARD-NAME |
minor | auto | cpp | Include guard not named after the file (Name.hpp -> NAME_H) |
CPP-ENDIF-COMMENT |
negligible | auto | cpp | Guard #endif without its /* NAME_H */ comment |
CPP-PREPRO-INDENT |
negligible | auto | cpp | #if block not at the indent of the code around with its content one level more (directives: 4 per #if / guard level) |
CPP-HEADER |
minor | ask | cpp | Missing file header (cpp-class scripts/header.py) |
CPP-HEADER-FILE |
negligible | auto | cpp | @file of the header is not the name of the file |
CPP-NULL |
major | auto | cpp | NULL instead of nullptr |
CPP-C-CAST |
major | auto | cpp | C cast, use static_cast (only (void) is allowed) |
CPP-AUTO |
major | - | cpp | auto, write the type (allowed: iterators, structured bindings) |
CPP-USING-STD |
major | - | cpp | using std::x, always write std::x |
CPP-TYPEDEF |
minor | auto | cpp | typedef, use using Name = Type |
CPP-BRACE-FUNCTION |
major | auto | cpp | Function opening brace on the signature line, it goes on its own line |
CPP-BRACE-OWN-LINE |
major | auto | cpp | Opening brace of a class / namespace / control block on its own line, it goes on the same line |
CPP-ELSE-LINE |
minor | auto | cpp | else / catch not on the closing brace line (} else {) |
CPP-KEYWORD-SPACE |
minor | auto | cpp | No space between if / for / while / switch / catch and the parenthesis |
CPP-PAREN-SPACE |
negligible | auto | cpp | Space inside the parentheses of a control statement |
CPP-COLON-SPACE |
negligible | auto | cpp | Space before ':' of a range-for, an inheritance or an enum base |
CPP-PTR-REF |
minor | auto | cpp | & / * glued to the name instead of the type (const T& name, char* buf) |
CPP-VOID-PARAM |
minor | auto | cpp | Empty parameter list, write (void) |
CPP-THIS |
minor | auto | cpp | Member accessed without this-> |
CPP-NAMESPACE-NESTED |
minor | - | cpp | Nested namespace blocks, use namespace a::b { |
CPP-NAMESPACE-COMMENT |
negligible | auto | cpp | Namespace block without // namespace start / // namespace end |
CPP-NAMESPACE-INDENT |
minor | - | cpp | Content of a namespace indented (it is not) |
CPP-INCLUDE-ORDER |
minor | auto | cpp | Include order: personal libs (+ defines), project, external; longest name first |
CPP-CLASS-NAME |
major | - | cpp | Class / struct / enum not in PascalCase |
CPP-MEMBER-NAME |
minor | - | cpp | Class data member not named _camelCase |
CPP-MACRO-NAME |
minor | - | cpp | Macro not in UPPER_SNAKE (or _lower for attribute / section macros) |
CPP-ONE-LINER |
negligible | auto | cpp | One-liner body not written {statement}; (an empty one: { /* Nothing */ };) |
CPP-EMPTY-BODY |
minor | auto | cpp | Empty constructor / destructor / operator of a class on several lines (one line: sig: init { /* Nothing */ }; // comment) |
CPP-ONELINER-ALIGN |
negligible | auto | cpp | One-liner functions of a group not aligned tight: their { right after the longest signature + 1 (lengths far apart: one column per level of 2+ lines) |
CPP-INIT-COLON |
minor | auto | cpp | Init list on the line of its constructor: its : glued to the ) (Name(int a): _a{a}) |
CPP-ACCESS-ORDER |
negligible | - | cpp | public before private / protected in a class |
CPP-SINGLE-STATEMENT |
minor | - | cpp | Single statement function defined in the .cpp, define it inline in the header |
CPP-DOXYGEN |
minor | - | cpp | Doxygen comment (@brief, @param, ///, /**), short plain comments only |
CPP-UNCHECKED-RETURN |
minor | - | cpp | Result of a function returning a value ignored (free functions of the project, libc / POSIX): use it or cast the call to (void) |
CPP-INCLUDE-COMMENT |
minor | - | cpp | Include of a header without its trailing comment listing what is used |
CPP-COMMENT-ALIGN |
negligible | auto | cpp | Trailing comments of an include block not aligned on one column |
CPP-EMPTY-SECTION |
minor | auto | cpp | Section separator / class block with nothing linked to it |
CPP-CLASS-BLOCK |
minor | - | cpp | Declaration in the wrong class block: Pre-Function = declared only (body in the .cpp), Function = defined in the header, Constructor / Destructor = theirs, data members before the blocks (Operator: free) |
CPP-ORPHAN-GROUP |
negligible | auto | cpp | /* group */ label with nothing under it |
C-GUARD-MISSING |
major | auto | c | Header without include guard (#ifndef NAME_H / #define NAME_H) |
C-PRAGMA-ONCE |
minor | auto | c | #pragma once instead of the include guard NAME_H |
C-GUARD-NAME |
minor | auto | c | Include guard not named after the file (name.h -> NAME_H) |
C-ENDIF-COMMENT |
negligible | auto | c | Guard #endif without its /* NAME_H */ comment |
C-PREPRO-INDENT |
negligible | auto | c | #if block not at the indent of the code around with its content one level more (directives: 4 per #if / guard level) |
C-HEADER |
minor | ask | c | Missing file header (XARTANIA banner, none or a text: asked by --fix, like the C++) |
C-HEADER-FILE |
negligible | auto | c | @file of the header is not the name of the file |
C-BRACE-FUNCTION |
major | auto | c | Function opening brace on the signature line, it goes on its own line |
C-BRACE-OWN-LINE |
major | auto | c | Opening brace of a struct / union / enum / control block on its own line, it goes on the same line |
C-ELSE-LINE |
minor | auto | c | else not on the closing brace line (} else {) |
C-KEYWORD-SPACE |
minor | auto | c | No space between if / for / while / switch and the parenthesis |
C-PAREN-SPACE |
negligible | auto | c | Space inside the parentheses of a control statement |
C-PTR-REF |
minor | auto | c | * glued to the name instead of the type (char* buf, like the C++) |
C-VOID-PARAM |
minor | auto | c | Empty parameter list, write (void) |
C-INCLUDE-ORDER |
minor | auto | c | Include order: personal libs (+ defines), project, external; longest name first |
C-MACRO-NAME |
minor | - | c | Macro not in UPPER_SNAKE (or _lower for attribute / section macros) |
C-DOXYGEN |
minor | - | c | Doxygen comment (@brief, @param, ///, /**), short plain comments only |
C-INCLUDE-COMMENT |
minor | - | c | Include of a header without its trailing comment listing what is used |
C-COMMENT-ALIGN |
negligible | auto | c | Trailing comments of an include block not aligned on one column |
C-EMPTY-SECTION |
minor | auto | c | Section separator with nothing linked to it |
C-ORPHAN-GROUP |
negligible | auto | c | /* group */ label with nothing under it |
C-UNCHECKED-RETURN |
minor | - | c | Result of a function returning a value ignored (functions of the project, libc / POSIX): use it or cast the call to (void) |
C-TYPE-NAME |
major | - | c | struct / union / enum not in snake_case ending with _s / _u / _e, typedef not ending with _t, enum value not in UPPER_SNAKE |
C-FUNC-NAME |
minor | - | c | Function, parameter or variable not in snake_case (global const: UPPER_SNAKE allowed) |
C-PTR-CHECK |
minor | - | c | Pointer parameter of a non static function dereferenced (p->, p[, *p) before being checked (if (!ptr) return KO;) |
C-FUNC-LENGTH |
minor | - | c | Function body longer than 40 lines of code (empty and comment lines not counted) |
C-NESTING |
minor | - | c | Control blocks (if / for / while / switch / do / else) nested more than 4 levels deep (a bare { } is not a level) |
ASM-HEADER |
minor | ask | asm | Missing file header (the C / C++ one in ; comments: XARTANIA banner, none or a text, asked by --fix) |
ASM-HEADER-FILE |
negligible | auto | asm | @file of the header is not the name of the file |
ASM-SECTION-ORDER |
minor | - | asm | Sections not in the order .data, .rodata, .bss, .text |
ASM-SYMBOL-DECL |
minor | - | asm | extern after a section, global not at the start of section .text, global without its label, extern never used |
ASM-INDENT |
minor | auto | asm | Indentation: section / function label at 0, their content at 4, a local label at its block level and its content (up to its last backward jump) one level more |
ASM-COMMENT-ALIGN |
negligible | auto | asm | Trailing ; comments of consecutive lines not aligned on one column |
ASM-CASE |
negligible | auto | asm | Mnemonic, register, size or directive not in lower case (MOV RAX -> mov rax) |
ASM-LABEL-NAME |
minor | - | asm | Label not in snake_case (local: .snake_case); a static function (not global) starts with _, a global one never does (_start excepted) |
ASM-LOCAL-LABEL |
minor | - | asm | Label only jumped to from its function: make it local (.name) |
ASM-CONST-NAME |
minor | - | asm | equ / %define / %assign / %macro name not in UPPER_SNAKE |
ASM-DATA-NAME |
minor | - | asm | Data label (.data / .rodata / .bss) not in snake_case or named like a register |
ASM-REG-COMMENT |
minor | force | asm | Function label without the comment of its registers (; in: rdi, rsi | out: rax), written from the registers read / written with --force |
ASM-FALLTHROUGH |
major | - | asm | Function falling through into the next one (its last instruction is not ret / jmp / the exit syscall) |
ASM-CALLEE-SAVED |
major | - | asm | Global function changing rbx, rbp or r12-r15 without push / pop (System V ABI) |
ASM-FRAME |
major | - | asm | push rbp without pop rbp / leave before a ret, or pop rbp / leave without push rbp |
ASM-FRAME-UNUSED |
negligible | - | asm | Stack frame (push rbp / mov rbp, rsp) of a function using no stack: no other push / pop, no call, no [rbp] / [rsp], rsp unchanged |
ASM-SYSCALL-COMMENT |
minor | auto | asm | mov rax, N of a syscall without the comment of its name (; write), written by --fix |
ASM-ZERO-XOR |
negligible | force | asm | mov reg, 0: xor reg, reg (shorter; the flags change: --force) |
CMAKE-SECTION-ORDER |
minor | - | cmake | Sections not in the cmake-style order |
CMAKE-BANNER |
negligible | auto | cmake | Section banner not '# ' + 25 '=' |
CMAKE-COMPILER-ORDER |
major | force | cmake | set(CMAKE_CXX_COMPILER) after project(): ignored, it goes before |
CMAKE-GLOB-SOURCES |
major | - | cmake | Sources collected with file(GLOB), list them in set(SRC ...) |
CMAKE-UNREGISTERED |
major | force | cmake | Source file of src/ missing from set(SRC ...) |
LU-INCLUDE |
major | auto | cpp | libutils header included directly, use #define _Section + <utils/utils.hpp> |
LU-BARE-INCLUDE |
major | auto | cpp | <utils/utils.hpp> without any #define _Section before it |
LU-SECTION |
minor | auto | cpp | libutils section used without its #define before <utils/utils.hpp> |
LU-ATTRIBUTE |
minor | auto | cpp | Standard attribute with a libutils macro equivalent ([[nodiscard]] -> _nodiscard) |
LU-MIGRATION |
major | auto | cpp | Deprecated libutils name (migration alias), use the new name |
LU-EXCEPTION |
major | - | cpp | Standard exception thrown, use utils::exception::ErrorException |
LU-ARGS |
minor | - | cpp | Arguments parsed by hand, use utils::arguments::ArgParser |
LU-ANSI |
minor | - | cpp | Raw ANSI escape sequence, use utils::iomanip |
LU-SOCKET |
minor | - | cpp | Raw BSD socket, use utils::network (TCPSocket, Server, Client) |
LU-SYSCALL |
minor | - | cpp | Raw pipe / dup / fork / epoll / shm / dlopen, use utils::encapsulation |
LU-THREADS |
minor | - | cpp | Hand made thread pool, use utils::pool::Cluster or utils::system::Scheduler |
LU-ANGLE |
minor | - | cpp | Degree / radian conversion by hand, use utils::math::trigo |
LU-BASE64 |
minor | - | cpp | Hand made base64, use utils::smanip::codec::Base64Codec |
LU-VERBOSE |
minor | - | cpp | Hand made verbose flag, use utils::verbose (set_verbose, onBasicVerbose) |
LU-DISTANCE |
minor | - | cpp | Hand made string distance, use utils::algorithms::c2dmp |
PY-WILDCARD-IMPORT |
major | - | py | from x import *, import the names explicitly |
PY-BARE-EXCEPT |
major | - | py | Bare except:, catch the exceptions expected |
PY-TYPE-HINTS |
minor | auto | py | Function without type hints (added when certain: literal defaults, None / literal returns) |
PY-PRINT-ERROR |
minor | auto | py | print(..., file=stderr), use stderr.write |
PY-OPEN-ENCODING |
minor | force | py | open() of a text file without encoding="utf-8" |
RS-UNWRAP |
major | - | rs | .unwrap() outside of the tests, propagate with ? (and a context) or handle the error |
RS-PANIC |
major | - | rs | panic! / process::exit in a library file, todo! / unimplemented! left anywhere |
RS-GLOB-IMPORT |
major | - | rs | use path::, import the names explicitly (super:: and preludes excepted) |
RS-NAMING |
minor | - | rs | fn / variables snake_case, types PascalCase, const / static UPPER_SNAKE |
RS-UNSAFE |
minor | - | rs | unsafe block without a // SAFETY: comment explaining why it is sound |
RS-PRINT-ERROR |
minor | auto | rs | Error printed with println!, use eprintln! (stderr) |
RS-DBG |
minor | - | rs | dbg! left in the code |
SH-SHEBANG |
minor | - | sh | Script without shebang (#!/bin/bash) |
SH-STRICT |
minor | force | sh | Bash script without set -euo pipefail |
SH-TEST |
negligible | auto | sh | [ ] test in a bash script, use [[ ]] |
make # Configure & build into build/
export BUILD_DIR=build
cmake -S . -B $BUILD_DIR -DCMAKE_BUILD_TYPE=Debug # Debug build (-g -ggdb3)
cmake -S . -B $BUILD_DIR -DCMAKE_BUILD_TYPE=Asan # AddressSanitizer build
cmake --build $BUILD_DIR --target release # Debug, Asan & Optimized builds
cmake --build $BUILD_DIR --target package_release # RPM / DEB / Arch packages of every variant (build/*.rpm, *.deb, *.pkg.tar.zst)
cmake --build $BUILD_DIR --target get_unregistered_files # .cpp files missing from the SRC / SRC_SHARED lists
./xstyle --rtk -r src include tests CMakeLists.txt # xstyle stays clean on itself (checked by the CI)| Path | Content |
|---|---|
src/xstyle/ |
Sources: main.cpp (entry), Core.cpp (arguments, run), Checker.cpp, Reporter.cpp, Rules.cpp, check/ (one file per family of rules) |
include/xstyle/ |
Headers |
assets/fonts/ansi_shadow.flf |
Banner font of the file headers (--header), embedded at build time (build/generated/xstyle/Font.hpp) |
tests/xstyle/ |
Unit tests (GoogleTest) + command line tests (ctest) |
cmake/package/ |
CMake package config and the CPack scripts (Arch packages) |
docs/ |
Documentation site (docs/site/: Markdown sources + generators, built pages in docs/) and the project graph |
Note
Every new .cpp must be added to the SRC (executable only) or SRC_SHARED (executable and tests) list of the CMakeLists.txt (get_unregistered_files lists the missing ones).
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON
cmake --build build --parallel $(nproc) # ./unit_tests at the root
(cd build && ctest --output-on-failure)The shared hook (.githooks/pre-commit) runs xstyle on the staged lines at each git commit and refuses a major (or worse) issue.
git config core.hooksPath .githooks # once per new clone
git commit --no-verify # skip the hook once (or XSTYLE_HOOK=0 git commit ...)
xstyle --fix --staged # fix what can be, then git add -uDispatch (CI/CD): runs on every push (branchmainor tagv*, not for*.md/*.txt/docs/only changes) and decides what to trigger from the ref / commit messageUnit Tests (CI): builds and runs the unit tests, always first in theunit-testsimageBuild (CI): only builds the project in theciimage, checks the outputs and runs xstyle on its own sources (--fail-on major), without producing packagesBuild - Packages (CI/CD): builds the packages (RPM/DEB/Arch, in theciimage), signs them and publishes them on thegh-pagesrepositoryRelease - GitHub (CD): creates the GitHub release of a tag from its section of theCHANGELOG.md, once the packages are publishedDocs - Pages (CD): copiesdocs/on thegh-pagesbranch on every push changing it (https://tsukini22.github.io/xstyle/docs/)Sync Packages (CD)(ongh-pages): rebuilds the metadata and signatures of the package repository after a manual push on the branch
Note
Build (CI) only runs when Dispatch (CI/CD) decides not to build the packages, to check that the code still compiles.
Important
The workflows need the repository variable RUNNER (gh variable set RUNNER --body <runner>), the containers ghcr.io/tsukini22/ci, unit-tests, package, git, the secrets GPG_PRIVATE_KEY (base64), GPG_KEY_ID, GPG_PASSPHRASE to sign and publish the packages, and DOCKER_IMAGE_REPO_TOKEN (fine-grained token shared by libutils, brain and xstyle: Contents read and write on docker-image) to notify docker-image.
Tip
A commit containing [ignore] skips the whole CI.
The pre-release of the packages (<package_name>-pre) is triggered by:
- a tag with a suffix, matching
vx.x.x-<suffix>(ex:v1.0.1-pre,x=major,minor,fix) - or a commit containing
[build]
Note
Only the 5 last versions of each -pre package are kept in the package repository, every release is kept.
The release of the packages (channel stable) and the GitHub release are only triggered by a tag matching exactly vx.x.x (ex: v1.0.0), whose section must exist in the CHANGELOG.md.
A pre-release tag also gets a GitHub release (marked pre-release), with its own ## [vx.x.x-pre] section or the ## [pre-release] one.
Dispatch (CI/CD) notifies the docker-image repository (repository_dispatch xstyle-released, job notify-docker-image) after the packages are published, to rebuild the ci and mingw64-ci images (and their unit-tests images) with the new packages:
- on every package build (release or pre-release)
- or on a commit containing
[release]