FAQ
Why is my project rebuilding everything on every run?
Four common causes, in order of likelihood:
You changed
Compiler:or flags. HelpMake invalidates the entire per-compilerobj/directory when it detects a toolchain or flag change. Checkbuild/HelpMake/<compiler>/obj/- if it's empty and you didn't--clean, that's why. Once rebuilt, subsequent runs with the same flags skip recompilation.Your
.dfiles are missing or corrupted. Header tracking relies on depfiles. Ifbuild/HelpMake/<compiler>/obj/main.dis missing,main.cpprecompiles. Runhm --verboseand look forWarning: Could not open dependency file.A header is being touched on every build. Some code generators rewrite headers with new timestamps even when content is identical. Check which header with:
bashhm -b --debug 2>&1 | grep -i "newer than"The debug output names the header that triggers the rebuild.
You're running
hm --cleanin CI or a script.--cleandeletesbuild/HelpMake/including all objects. Look at your build script.
If all four are ruled out, run hm -b --debug --rebuild once, then hm -b --debug. The second build should show Skip (up to date) for every file. If not, paste the output in a GitHub issue.
Why does changing Compiler: trigger a full rebuild?
Because object files from different compilers are not link-compatible. g++ objects contain symbols mangled for libstdc++; zig c++ objects contain symbols mangled for libc++. Linking them together either fails with hundreds of undefined references, or (worse) links but crashes.
HelpMake prevents this by construction: each compiler writes to build/HelpMake/<compiler>/obj/. When you switch compilers, the new obj/ is empty, so every file recompiles. This is intentional, not a bug.
You can safely mix toolchains across configs, because each config picks its own compiler and gets its own object tree. You cannot mix them within a single config.
Why doesn't src/**/*.cpp work when I pass it to g++ directly?
Because ** is not shell globbing. In bash it's only valid with globstar enabled:
shopt -s globstar
g++ -std=c++20 src/**/*.cpp -o app -IincludeIn cmd and PowerShell it never works. In g++ itself, it's just a literal filename.
Inside HelpMake.txt, ** works regardless of shell:
InputFiles {
src/**/*.cpp
}HelpMake expands the glob internally, so it doesn't matter whether you're on Windows cmd, PowerShell, or Linux.
What's the difference between -ZigCpp and -ZigCC?
Both use Zig's LLVM-based toolchain:
-ZigCppinvokeszig c++- C++ mode, links against Zig's bundledlibc++, uses-x c++-headerfor PCH-ZigCCinvokeszig cc- C mode, links against Zig's bundledlibc, uses-x c-headerfor PCH
Use -ZigCpp for .cpp files and -ZigCC for .c files. If you mix extensions in one project, pick whichever handles most of your sources correctly and use .cpp/.c extensions that match.
Why does Kind: static fail with --no-sep?
--no-sep tells HelpMake to pass all sources to the compiler in one shot:
g++ -c a.cpp b.cpp c.cpp -o appThat produces one binary directly, with no intermediate .o files. A static library archive is built from object files, so Kind: static requires separate compilation (each .cpp gets its own .o).
HelpMake rejects this combination with:
Error: 'Kind: static' requires separate compilation. Remove --no-sep.Remove --no-sep for static library builds.
MSVC PCH: "unexpected end of file while looking for precompiled header"
MSVC requires the PCH header to be the first #include in every .cpp file that uses it:
#include "pch.hpp" // ← must be first
#include <iostream> // ← this comes afterIf any #include precedes pch.hpp, MSVC emits:
fatal error C1010: unexpected end of file while looking for precompiled headerHelpMake generates the synthetic pch.cpp with #include "pch.hpp" on the first line, but it cannot reorder your sources. Ensure every .cpp in the project follows the first-include rule, or remove PCH: from the config.
Can I build the same project with different compilers simultaneously?
Yes, using configs:
Compiler: g++
InputFiles { src/*.cpp }
Config: native {
Compiler: clang++
Output: build/native.exe
}
Config: portable {
Compiler: zig c++
Output: build/portable.exe
}Each config has its own compiler and its own object tree (build/HelpMake/gcc/, build/HelpMake/clang/, build/HelpMake/zig-c++/). Build them:
hm -b --config native
hm -b --config portableThe two builds never interfere. Both binaries are produced from the same source.
Why are there "undefined reference to std::__1::basic_string" errors?
You're linking libc++-compiled objects with a libstdc++ linker (or vice versa). Symptom: every error mentions std::__1:: (that's libc++, used by Clang and Zig) or std:: without __1 (that's libstdc++, used by GCC).
Cause: mixing objects from g++ and clang++ / zig c++. HelpMake prevents this by isolating object directories per compiler. If you hit this error:
- Run
hm --cleanto remove all objects - Run
hm -bonce and let it build with the selected compiler - Don't manually copy
.ofiles betweenbuild/HelpMake/gcc/obj/andbuild/HelpMake/clang/obj/
If the error persists after --clean, check your HelpMake.txt for multiple Compiler: directives that might be overriding each other.
How do I see the exact compiler command being run?
hm -b --verboseEvery compile and link command prints:
[HelpMake] Object Command: g++ -std=c++20 -Iinclude -Wall -fdiagnostics-color=always -xc++ -c src/main.cpp -o build/HelpMake/gcc/obj/main.o -MMD
[HelpMake] Link Command: g++ -std=c++20 -Iinclude -Wall build/HelpMake/gcc/obj/main.o -o build/app.exeUse --debug for even more detail (parser trace, config discovery, flag splits).
How do I use HelpMake as a library?
include/HelpMake.hpp provides a hp::HelpMake class:
#include "hp/help.hpp"
int main() {
hp::HelpMake()
.setCompiler("g++")
.setStandard("c++20")
.setOutput("build/app")
.addInputFile("src/*.cpp")
.addInclude("include")
.addFlag("-Wall")
.build();
return 0;
}The API mirrors every HelpMake.txt field. see include/HelpMake.hpp for the full list of setX and addX methods.
What's the difference between --clean, --clean-gcm, and --clean-all?
| Command | Deletes |
|---|---|
hm --clean | build/HelpMake/ (objects, logs, PCH, deps) |
hm --clean-gcm | gcm.cache/ (GCC module cache) |
hm --clean-all | Both |
--clean-gcm is separate because GCC puts gcm.cache/ in the project root, not under build/HelpMake/. Most other toolchains don't need it.
Can HelpMake compile C?
Yes. Two ways:
Option 1: GCC/Clang (C mode)
Compiler: gcc
Version: std=c17
InputFiles { src/*.c }Option 2: Zig CC
Compiler: zig cc
Version: std=c17
InputFiles { src/*.c }The Version: field accepts std=c17, std=c23, etc. HelpMake passes -std=c17 to the compiler.
How do I add a new toolchain?
- the
hm::Compilerinterface ininclude/hm/toolchain/compiler.hpp. Contributing requires:
- Subclass
hm::Compilerwith your toolchain's flag shapes - Register it in
makeCompiler()insrc/toolchain/toolchain.cpp - Add a
-YourNameflag insrc/cli/build.cppif it deserves a shortcut - Document it in
docs/04-toolchains.md
Open a PR - toolchain additions are welcome.
How do I use a third-party dependency?
Use Dependency: name { } and opt in from the config with Depends::
Dependency: stb {
Git: https://github.com/nothings/stb
Tag: master
Include: .
}
Config: app {
Depends: stb
InputFiles { src/main.c }
}See Dependency blocks for all fields. For header-only libraries, Fetch { } is a shorter alternative.
Why does git clone fail on a .tar.gz URL?
Because git clone requires a git repository. A .tar.gz on an HTTP server is not a git repo. Use Url: for tarball deps:
Dependency: lua {
Url: https://www.lua.org/ftp/lua-5.4.6.tar.gz
Build: make -C src posix
Include: src
Link: src/liblua.a
}Url: fetches with curl + extracts with tar/unzip. Git: fetches with git clone. They are not interchangeable.
Why does my dependency fail with "file COPY cannot find"?
The dep directory exists but its contents are incomplete - usually an interrupted clone or a corrupt shallow fetch. The cache check trusts whatever's on disk, so a broken clone gets silently used. Force a fresh fetch:
rm -rf build/HelpMake/dep/<name>
hm -b --config <your-config>How do I generate a build.ninja file?
hm --gen ninja
ninjaSee Generators. Not all features are supported by the Ninja generator - PCH, PreBuild/PostBuild, Copy and Fetch are warned and skipped. Use hm -b for the full feature set.
How do I write a cross-platform HelpMake.txt?
Use platform conditionals. Prefix any line with win:, linux:, mac:, unix:, x64:, arm64::
Compiler: g++
Output: build/app
win: Output: build/app.exe
linux: Output: build/app
Flags {
-Wall
win: /W4
linux: -Wextra -fPIC
x64: -march=native
}One file, works on Windows, Linux, and macOS. See Platform conditionals.
How do I run tests?
Mark the configs you want to test with Test: true:
Config: test-math {
Test: true
Output: build/test-math.exe
InputFiles { test/math.cpp }
}Then:
hm testhm test builds every config with Test: true and runs the resulting binary. Exit code 0 if all tests return 0, 1 if any returns non-zero or fails to build. Configs run alphabetically.
See Testing for output format, --verbose / --quiet behavior, and the failures block.
Why does my build report "command line too long" or truncate arguments?
Windows caps CreateProcessA at 32,767 characters. hm handles this by writing arguments to build/HelpMake/<comp>/<baseName>.rsp and passing @file.rsp to the compiler - this kicks in automatically for any link command over 30,000 chars.
If you see build failures on a project with 300+ files and the error message mentions an unrecognized flag or a missing source, check whether the response file is being used:
hm -b --verbose 2>&1 | grep "response file"If nothing prints and the project has 500+ files, the threshold is being missed - file a bug.
See Response files.
Why does Clang fail with "malloc.h: redefinition of '_MarkAllocaS'"?
This happens when Clang is passed -fmodules on a project using C++20 modules. -fmodules is Apple Clang's module system (Xcode, #import), not C++20 modules. It forces every #include to be treated as a module unit, which breaks on MSYS2 headers that use static inline functions.
hm gates -fmodules on comp->name() == "gcc". If it's leaking through to Clang, check your HelpMake.txt:
Flags {
-fmodules # ← remove this
}Or if your config manually sets it, remove it - Clang needs no extra flag for C++20 modules.
Why does --clean fail with "Access is denied"?
git clone (used by Fetch { } and Dependency { }) marks .git/objects/pack/*.idx and .pack as read-only on Windows. A naive remove_all throws filesystem_error: Access is denied on read-only files.
Since 12.2.0, hm --clean clears the read-only bit before deletion, so this should work. If it still fails:
- An editor or git GUI has the project open - close VS Code, Fork, SourceTree, GitKraken, etc.
- Antivirus scan in progress - Windows Defender scans new
.gitcontents for a few seconds after clone - A background
gitprocess -tasklist | findstr giton Windows,ps aux | grep giton Unix
Retry after closing them. hm --clean --verbose prints each path as it's removed, so you can see which file was stuck.
Why does every build say "Build flags changed, invalidating objects"?
Fixed in 12.2.0. The .buildid file didn't capture -fmodules, so any config with Modules { } recomputed its effective flags on every build and trivially "detected a change." Now .buildid captures the full effective command (binary + subcommand + version + -fmodules + flags), and only invalidates when that actually changes.
If you still see it on every build after 12.2.0, delete the stale marker once:
rm build/HelpMake/<comp>/.buildid
hm -bCan I build a project with no config file?
Yes. hm -b in a directory with no HelpMake.txt still builds. Every field is inferred:
cd your-project
hm -bHelpMake detects the compiler from source extensions, runs <compiler> -dumpversion for the standard, walks src/ (or .) for sources, follows #include "..." for companion .cpp files, scans <...> includes for link flags, checks for main( to decide executable vs static, and reads Cargo.toml / go.mod / package.json / CMakeLists.txt / main.* / directory name for the output.
Every detection warns under Info: so you can see exactly what was inferred. See Auto-detection.
Why did HelpMake add -pthread automatically?
You have #include <thread>, <mutex>, <atomic>, <condition_variable>, <future>, or <pthread.h> somewhere in your sources. The link flag detection reads every #include <...> line and adds the corresponding flag:
| Header | Flag (GCC/Clang) |
|---|---|
<thread> / <mutex> / <atomic> / <condition_variable> / <future> / <pthread.h> | -pthread |
<cmath> / <math.h> | -lm |
<dlfcn.h> | -ldl |
<zlib.h> | -lz |
<curl/curl.h> | -lcurl |
<openssl/ssl.h> | -lssl -lcrypto |
<SDL2/SDL.h> | -lSDL2 |
<GLFW/glfw3.h> | -lglfw |
<GL/gl.h> | -lGL |
<GL/glew.h> | -lGLEW |
<gtest/gtest.h> | -lgtest -lgtest_main |
<fmt/core.h> | -lfmt |
<sqlite3.h> | -lsqlite3 |
<expat.h> | -lexpat |
Only angle-bracket includes trigger the flag — #include "pthread.h" (a local file) is ignored, and so is any include inside a comment (/* #include <pthread.h> */).
On MSVC, POSIX-only flags are skipped; only the .lib equivalents (zlib.lib, libcurl.lib, SDL2.lib, etc.) are added. Existing flags are never duplicated.
To disable it, pin the flags explicitly: Flags { -Wall -O2 }. Anything you write wins over auto-detection.
For the full table including MSVC equivalents, see Auto-detection.
Why did HelpMake mark my library as executable?
autoKind scans every C-family source for an entry-point function — main, WinMain, wmain, or _tmain. Comments and string literals are stripped before scanning, so // int main(), /* int main() */, and std::string s = "main(" do not trigger the executable classification. If no source has a valid entry point, HelpMake picks Kind: static and warns.
If your project has a main that the scanner missed (e.g. in a source excluded by InputFiles { }), pin the kind explicitly:
Kind: staticNon-C-family projects (Zig, Go, Rust, Python) always default to executable - those languages don't have the static/executable distinction in the C sense.
How do I disable auto-detection?
Three ways:
1. Pin every field in HelpMake.txt. Anything you write wins over auto-detection.
2. Use --nofile to build from CLI arguments only:
hm -b --nofile -C=g++ -V=std=c++20 -o app src/main.cpp--nofile fully disables auto-detection - the current directory is not scanned for sources, includes, headers, or link flags. It requires -C=<compiler> and at least one input file on the command line, and errors out otherwise.
3. Use --quiet to suppress the warnings if you trust the detection and don't want to see the Info: block.
Why did HelpMake add foo.cpp to my build automatically?
You have #include "foo.hpp" in one of your sources, and foo.cpp exists somewhere in the tree but wasn't listed in InputFiles { }. Companion source detection adds it automatically so you don't have to maintain both a header list and a source list.
To disable, list your sources explicitly:
InputFiles {
src/*.cpp
tools/*.cpp
}User-specified InputFiles { } is never modified by companion detection.
How do I report a bug?
Open an issue on GitHub with:
- The exact
hmcommand you ran - The contents of
HelpMake.txt(redact anything private) - The
--verboseoutput showing the failing command - The log from
build/HelpMake/<compiler>/logs/<output>.txt - Your OS and compiler versions
Reproducible cases get fixed fastest. If you can, minimize the project to the smallest failing example.
