Skip to content

Commit ae8b1cf

Browse files
GaspardKiriraGaspardKirira
committed
docs(cli): complete command help output
1 parent 08a3465 commit ae8b1cf

4 files changed

Lines changed: 319 additions & 211 deletions

File tree

‎src/commands/BuildCommand.cpp‎

Lines changed: 58 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -3524,68 +3524,96 @@ namespace vix::commands::BuildCommand
35243524
out << " dev-ninja Debug build in build-ninja\n";
35253525
out << " release Release build in build-release\n\n";
35263526

3527-
out << "Options:\n";
3528-
out << " --preset <name> Use a build preset: dev, dev-ninja, release\n";
3529-
out << " --build-target <name> Build a specific CMake target, for example all or vix\n";
3530-
out << " -j, --jobs <n> Number of parallel build jobs\n";
3531-
out << " -d, --dir <path> Project directory\n";
3532-
out << " --clean Remove local build directories and configure again\n";
3533-
out << " --fast Exit early when Ninja says the build is already up to date\n";
3534-
out << " --no-cache Disable Vix cache shortcuts\n";
3535-
out << " --no-status Disable Ninja progress status\n";
3536-
out << " --no-up-to-date Disable Ninja dry-run up-to-date detection\n";
3537-
out << " -q, --quiet Minimal output\n";
3538-
out << " -v, --verbose Show detailed build information\n";
3539-
out << " --cmake-verbose Show raw CMake configure output\n";
3540-
out << " -h, --help Show this help\n\n";
3527+
out << "Project:\n";
3528+
out << " [source.cpp] Build one C++ source file directly\n";
3529+
out << " -d, --dir <path> Project directory\n";
3530+
out << " --dir=<path> Same as --dir <path>\n\n";
3531+
3532+
out << "Build:\n";
3533+
out << " --preset <name> Use a preset: dev, dev-ninja, release\n";
3534+
out << " --preset=<name> Same as --preset <name>\n";
3535+
out << " --build-target <name> Build a specific CMake target\n";
3536+
out << " --build-target=<name> Same as --build-target <name>\n";
3537+
out << " -j, --jobs <n> Number of parallel build jobs\n";
3538+
out << " --jobs=<n> Same as --jobs <n>\n";
3539+
out << " --clean Remove local build directories and configure again\n";
3540+
out << " --fast Use fast no-op detection when possible\n";
3541+
out << " --explain Explain why files or targets rebuild\n";
3542+
out << " --no-cache Disable Vix cache shortcuts\n";
3543+
out << " --no-status Disable Ninja progress status\n";
3544+
out << " --no-up-to-date Disable Ninja dry-run up-to-date detection\n\n";
35413545

35423546
out << "Output:\n";
3543-
out << " --bin Export the built executable to the project root\n";
3544-
out << " --out <path> Export the built executable to a specific path\n\n";
3547+
out << " --bin Export the built executable to the project root\n";
3548+
out << " --out <path> Export the built executable to a specific path\n";
3549+
out << " --out=<path> Same as --out <path>\n\n";
35453550

35463551
out << "Tooling:\n";
3547-
out << " --launcher <mode> Compiler launcher: auto, none, sccache, ccache\n";
3548-
out << " --linker <mode> Linker mode: auto, default, mold, lld\n\n";
3552+
out << " --launcher <mode> Compiler launcher: auto, none, sccache, ccache\n";
3553+
out << " --launcher=<mode> Same as --launcher <mode>\n";
3554+
out << " --linker <mode> Linker mode: auto, default, mold, lld\n";
3555+
out << " --linker=<mode> Same as --linker <mode>\n\n";
35493556

35503557
out << "Cross-compilation:\n";
3551-
out << " --target <triple> Cross-compilation target triple\n";
3552-
out << " --sysroot <path> Sysroot for the cross toolchain\n";
3553-
out << " --targets List detected cross toolchains on PATH\n\n";
3558+
out << " --target <triple> Cross-compilation target triple\n";
3559+
out << " --target=<triple> Same as --target <triple>\n";
3560+
out << " --sysroot <path> Sysroot for the cross toolchain\n";
3561+
out << " --sysroot=<path> Same as --sysroot <path>\n";
3562+
out << " --targets List detected cross toolchains on PATH\n\n";
35543563

35553564
out << "Linking and dependencies:\n";
3556-
out << " --static Request static linking\n";
3557-
out << " --with-sqlite Enable SQLite support\n";
3558-
out << " --with-mysql Enable MySQL support\n\n";
3565+
out << " --static Request static linking\n";
3566+
out << " --with-sqlite Enable SQLite support\n";
3567+
out << " --with-mysql Enable MySQL support\n\n";
3568+
3569+
out << "Logs and output:\n";
3570+
out << " -q, --quiet Minimal output\n";
3571+
out << " -v, --verbose Show detailed build information\n";
3572+
out << " --cmake-verbose Show raw CMake configure output\n";
3573+
out << " -h, --help Show this help\n\n";
3574+
3575+
out << "CMake passthrough:\n";
3576+
out << " -- [cmake args...] Pass extra arguments to CMake configure\n\n";
35593577

35603578
out << "Environment variables:\n";
3561-
out << " VIX_BUILD_HEARTBEAT=0 Disable configure/build heartbeat\n";
3562-
out << " VIX_BUILD_HEARTBEAT=1 Force heartbeat when no output is produced\n";
3563-
out << " VIX_GRAPH_EXECUTOR=0 Disable graph target executor\n";
3564-
out << " VIX_LOG_LEVEL=debug Show deeper diagnostic output\n\n";
3579+
out << " VIX_BUILD_HEARTBEAT=0 Disable configure/build heartbeat\n";
3580+
out << " VIX_BUILD_HEARTBEAT=1 Force heartbeat when no output is produced\n";
3581+
out << " VIX_GRAPH_EXECUTOR=0 Disable graph target executor\n";
3582+
out << " VIX_LOG_LEVEL=debug Show deeper diagnostic output\n";
3583+
out << " VIX_LOG_LEVEL=trace Show trace-level diagnostic output\n\n";
35653584

35663585
out << "Examples:\n";
35673586
out << " vix build\n";
35683587
out << " vix build -v\n";
35693588
out << " vix build --fast\n";
35703589
out << " vix build --clean\n";
3590+
out << " vix build --explain\n";
35713591
out << " vix build --preset release\n";
3592+
out << " vix build --preset=release\n";
35723593
out << " vix build --build-target all\n";
35733594
out << " vix build --build-target vix -v\n";
3595+
out << " vix build --build-target=vix\n";
35743596
out << " vix build -j 8\n";
3597+
out << " vix build --jobs=8\n";
35753598
out << " vix build --launcher ccache --linker mold\n";
3599+
out << " vix build --launcher=ccache --linker=mold\n";
35763600
out << " vix build --with-sqlite\n";
35773601
out << " vix build --with-mysql\n";
35783602
out << " vix build --preset release --static\n";
35793603
out << " vix build --target aarch64-linux-gnu\n";
3580-
out << " vix build --preset release --target aarch64-linux-gnu\n";
3604+
out << " vix build --target=aarch64-linux-gnu\n";
3605+
out << " vix build --sysroot /opt/sysroot\n";
3606+
out << " vix build --targets\n";
35813607
out << " vix build --bin\n";
35823608
out << " vix build --out dist/app\n";
3609+
out << " vix build --out=dist/app\n";
35833610
out << " vix build main.cpp\n";
35843611
out << " vix build main.cpp --bin\n";
35853612
out << " vix build main.cpp --out app\n";
35863613
out << " vix build main.cpp --with-sqlite --out app\n";
35873614
out << " vix build main.cpp --target x86_64-windows-gnu --out app.exe\n";
3588-
out << " vix build --linker lld -- -DVIX_SYNC_BUILD_TESTS=ON\n\n";
3615+
out << " vix build --linker lld -- -DVIX_SYNC_BUILD_TESTS=ON\n";
3616+
out << " VIX_GRAPH_EXECUTOR=0 vix build --build-target vix\n\n";
35893617

35903618
out << "Logs:\n";
35913619
out << " build-dev/configure.log\n";

‎src/commands/DevCommand.cpp‎

Lines changed: 111 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -63,30 +63,121 @@ namespace vix::commands::DevCommand
6363
std::ostream &out = std::cout;
6464

6565
out << "Usage:\n";
66-
out << " vix dev [name] [options] [-- app-args...]\n\n";
66+
out << " vix dev [target] [options] [-- compiler/linker flags] [--run <args...>]\n\n";
6767

6868
out << "Description:\n";
69-
out << " Developer-friendly entrypoint that configures, builds and runs a Vix.cpp\n";
70-
out << " application in dev mode with auto-reload.\n";
71-
out << " Internally, this is equivalent to calling `vix run` with `--watch` enabled\n";
72-
out << " (for both single-file scripts and CMake-based projects).\n\n";
73-
74-
out << "Options:\n";
75-
out << " --force-server Force classification as 'dev server'\n";
76-
out << " --force-script Force classification as 'script'\n";
77-
out << " --watch, --reload Enable hot reload (enabled by default in dev)\n";
78-
out << " -j, --jobs <n> Number of parallel compile jobs\n";
79-
out << " --log-level <level> Override log verbosity (trace, debug, info, warn, error, critical)\n";
80-
out << " --verbose Shortcut for debug logs\n";
81-
out << " -q, --quiet Only show warnings and errors\n\n";
69+
out << " Start a C++ project or script in development mode.\n";
70+
out << " vix dev builds the target, runs it when possible, watches file changes,\n";
71+
out << " and rebuilds or restarts automatically.\n\n";
72+
73+
out << "Targets:\n";
74+
out << " current project vix dev\n";
75+
out << " project directory/name vix dev api\n";
76+
out << " single C++ file vix dev server.cpp\n";
77+
out << " manifest file vix dev app.vix\n\n";
78+
79+
out << "Project behavior:\n";
80+
out << " application project build, run, watch, restart on changes\n";
81+
out << " library project build, watch, rebuild on changes\n";
82+
out << " single C++ file compile, run, watch, rebuild on save\n\n";
83+
84+
out << "Project options:\n";
85+
out << " -d, --dir <path> Project directory\n";
86+
out << " --dir=<path> Same as --dir <path>\n";
87+
out << " --preset <name> Configure/build preset, default: dev-ninja\n";
88+
out << " --preset=<name> Same as --preset <name>\n";
89+
out << " --run-preset <name> Run preset name\n";
90+
out << " --run-preset=<name> Same as --run-preset <name>\n";
91+
out << " -j, --jobs <n> Number of parallel build jobs\n";
92+
out << " --jobs=<n> Same as --jobs <n>\n";
93+
out << " --clean Clean/reconfigure before starting dev mode\n";
94+
out << " --replay Record runs under .vix/runs/\n\n";
95+
96+
out << "Runtime arguments and environment:\n";
97+
out << " --cwd <path> Run the program from this working directory\n";
98+
out << " --cwd=<path> Same as --cwd <path>\n";
99+
out << " --env <K=V> Add or override one environment variable\n";
100+
out << " --env=<K=V> Same as --env <K=V>\n";
101+
out << " --args <value> Add one runtime argument, repeatable\n";
102+
out << " --args=<value> Same as --args <value>\n";
103+
out << " --run <args...> Runtime args for script mode\n\n";
104+
105+
out << "Watch mode:\n";
106+
out << " --watch Enabled by default in vix dev\n";
107+
out << " --reload Alias for --watch\n";
108+
out << " --force-server Treat the program as a long-running server\n";
109+
out << " --force-script Treat the program as a short-lived script\n\n";
110+
111+
out << "Script mode:\n";
112+
out << " --auto-deps Auto-add includes from .vix/deps/*/include\n";
113+
out << " --auto-deps=local Same as --auto-deps\n";
114+
out << " --auto-deps=up Search deps in parent folders too\n";
115+
out << " --san Enable ASan and UBSan\n";
116+
out << " --ubsan Enable UBSan only\n";
117+
out << " --tsan Enable ThreadSanitizer only\n";
118+
out << " --with-sqlite Enable SQLite support\n";
119+
out << " --with-mysql Enable MySQL support\n";
120+
out << " --local-cache Use local .vix-scripts cache\n\n";
121+
122+
out << "Documentation:\n";
123+
out << " --docs Enable OpenAPI/docs for this run\n";
124+
out << " --no-docs Disable OpenAPI/docs for this run\n";
125+
out << " --docs=<0|1|true|false> Explicitly control OpenAPI/docs\n\n";
126+
127+
out << "Output and logging:\n";
128+
out << " --clear <auto|always|never> Clear terminal before runtime output\n";
129+
out << " --clear=<auto|always|never> Same as --clear <mode>\n";
130+
out << " --no-clear Alias for --clear=never\n";
131+
out << " --log-level <level> trace, debug, info, warn, error, critical, off\n";
132+
out << " --log-level=<level> Same as --log-level <level>\n";
133+
out << " --verbose Alias for --log-level=debug\n";
134+
out << " -q, --quiet Alias for --log-level=warn\n";
135+
out << " --log-format <format> kv, json, json-pretty\n";
136+
out << " --log-format=<format> Same as --log-format <format>\n";
137+
out << " --log-color <mode> auto, always, never\n";
138+
out << " --log-color=<mode> Same as --log-color <mode>\n";
139+
out << " --no-color Alias for --log-color=never\n";
140+
out << " -h, --help Show this help\n\n";
141+
142+
out << "Compiler/linker flags:\n";
143+
out << " -- [flags...] In script mode, pass flags to the compiler\n";
144+
out << " Example: vix dev server.cpp -- -O2 -lssl\n\n";
145+
146+
out << "Important:\n";
147+
out << " vix dev already enables watch mode.\n";
148+
out << " For script runtime args, use --run or --args.\n";
149+
out << " Everything after -- is treated as compiler/linker flags.\n\n";
82150

83151
out << "Examples:\n";
84-
out << " vix dev # run current app with auto-reload\n";
85-
out << " vix dev api # run 'api' app in dev mode\n";
86-
out << " vix dev server.cpp # script mode with auto-rebuild on save\n";
87-
out << " vix dev server.cpp -- --port 8080\n";
88-
out << " vix dev server.cpp --force-server # treat it as a long-lived server\n";
89-
out << " vix dev tool.cpp --force-script # treat it as a CLI tool\n\n";
152+
out << " vix dev\n";
153+
out << " vix dev api\n";
154+
out << " vix dev --dir ./examples/blog\n";
155+
out << " vix dev --preset dev-ninja\n";
156+
out << " vix dev --clean\n";
157+
out << " vix dev --reload\n";
158+
out << " vix dev --force-server api\n";
159+
out << " vix dev --force-script tool.cpp\n";
160+
out << " vix dev api --args --port --args 8080\n";
161+
out << " vix dev api --cwd ./runtime\n";
162+
out << " vix dev api --env PORT=8080\n";
163+
out << " vix dev main.cpp\n";
164+
out << " vix dev main.cpp --run hello 123\n";
165+
out << " vix dev main.cpp --args hello --args 123\n";
166+
out << " vix dev main.cpp --with-sqlite\n";
167+
out << " vix dev main.cpp --with-mysql\n";
168+
out << " vix dev main.cpp --san\n";
169+
out << " vix dev main.cpp -- -O2 -DNDEBUG\n";
170+
out << " vix dev app.vix\n";
171+
out << " vix dev app.vix --args --port --args 8080\n\n";
172+
173+
out << "Environment variables:\n";
174+
out << " VIX_DOCS 0 or 1\n";
175+
out << " VIX_LOG_LEVEL trace, debug, info, warn, error, critical, off\n";
176+
out << " VIX_LOG_FORMAT kv, json, json-pretty\n";
177+
out << " VIX_COLOR auto, always, never\n";
178+
out << " VIX_STDOUT_MODE line\n";
179+
out << " VIX_CLI_CLEAR auto, always, never\n";
180+
out << " VIX_SHOW_ENV_HINT=1 Show .env hint when .env.example exists\n\n";
90181

91182
return 0;
92183
}

0 commit comments

Comments
 (0)