help command

implementations/Crafter.Build-Clang.cpp

@@ -852,8 +852,63 @@ void Crafter::EnableWasiBrowserRuntime(Configuration& cfg) {
     cfg.files.push_back(htmlPath);
 }
 
+static void PrintHelp(std::string_view argv0) {
+    std::println(
+R"(Usage:
+  {0} [options] [-- project-args...]    Build the project in the current directory
+  {0} test [test-options] [globs...]    Build and run the project's tests
+  {0} help | -h | --help                Show this help
+
+Loads ./project.cpp (override with --project=<path>), compiles it to a shared
+object, and invokes its CrafterBuildProject() to obtain a Configuration that
+drives the build. Outputs land at bin/<name>-<target>-<march>/, intermediates
+at build/<name>-<target>-<march>/.
+
+Build options:
+  -r                        Run the produced executable after a successful build
+                            (host targets only; libraries cannot be run).
+  -v, --verbose             Verbose progress output.
+  -q, --quiet               Suppress progress output.
+  --project=<path>          Path to the project file (default: ./project.cpp).
+
+Test options (after the `test` subcommand):
+  --list                    Enumerate matching tests without running them.
+  --jobs=<N>                Parallel job count (default: hardware_concurrency).
+  --timeout=<seconds>       Per-test timeout override.
+  --runner=<spec>           Override the test runner for this run. Specs:
+                              local
+                              cmd:<command>             (e.g. cmd:wine)
+                              ssh:<host>[:<remoteDir>]
+                              sshwin:<host>[:<remoteDir>]
+                              wsl[:<remoteDir>]
+  --target=<triple>         Filter to tests whose cfg.target matches; this is
+                            also forwarded to project-args so per-target tests
+                            build for that triple. Default: host triple.
+  <glob>                    One or more name globs to filter tests (e.g. 'Unit*').
+
+Project args:
+  Any flag not consumed above is forwarded verbatim to CrafterBuildProject as
+  part of its `args` span. Project-specific flags (e.g. --target=, custom
+  feature toggles) live there.
+
+Environment:
+  CRAFTER_BUILD_MARCH                  Override -march (default: native).
+  CRAFTER_BUILD_MTUNE                  Override -mtune (default: native).
+  CRAFTER_BUILD_RUNNER_<TARGET>        Default test runner for a target triple.
+                                       Replace '-' and '.' with '_' in the
+                                       triple. CLI --runner= overrides this.
+  CRAFTER_MINGW_DIR                    Override mingw-w64 sysroot auto-detect.
+  LIBCXX_DIR                           Windows libc++ install (MSVC ABI builds).
+
+Exit status:
+  0  success / all non-skipped tests passed
+  1  build failure or one or more tests failed
+)", argv0);
+}
+
 int Crafter::Run(int argc, char** argv) {
     try {
+        std::string_view argv0 = argc > 0 ? argv[0] : "crafter-build";
         fs::path projectFile = "./project.cpp";
         std::vector<std::string_view> projectArgs;
         projectArgs.reserve(argc);
@@ -865,7 +920,10 @@ int Crafter::Run(int argc, char** argv) {
 
         for (int i = 1; i < argc; ++i) {
             std::string_view arg = argv[i];
-            if (arg == "test") {
+            if (arg == "-h" || arg == "--help" || (!runTests && arg == "help")) {
+                PrintHelp(argv0);
+                return 0;
+            } else if (arg == "test") {
                 runTests = true;
             } else if (arg == "-r") {
                 runAfterBuild = true;