Skip to content

FAQ ​

Why is my project rebuilding everything on every run? ​

Four common causes, in order of likelihood:

  1. You changed Compiler: or flags. HelpMake invalidates the entire per-compiler obj/ directory when it detects a toolchain or flag change. Check build/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.

  2. Your .d files are missing or corrupted. Header tracking relies on depfiles. If build/HelpMake/<compiler>/obj/main.d is missing, main.cpp recompiles. Run hm --verbose and look for Warning: Could not open dependency file.

  3. 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:

    bash
    hm -b --debug 2>&1 | grep -i "newer than"

    The debug output names the header that triggers the rebuild.

  4. You're running hm --clean in CI or a script. --clean deletes build/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:

bash
shopt -s globstar
g++ -std=c++20 src/**/*.cpp -o app -Iinclude

In cmd and PowerShell it never works. In g++ itself, it's just a literal filename.

Inside HelpMake.txt, ** works regardless of shell:

txt
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:

  • -ZigCpp invokes zig c++ - C++ mode, links against Zig's bundled libc++, uses -x c++-header for PCH
  • -ZigCC invokes zig cc - C mode, links against Zig's bundled libc, uses -x c-header for 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:

text
g++ -c a.cpp b.cpp c.cpp -o app

That 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:

text
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:

cpp
#include "pch.hpp"    // ← must be first
#include <iostream>   // ← this comes after

If any #include precedes pch.hpp, MSVC emits:

text
fatal error C1010: unexpected end of file while looking for precompiled header

HelpMake 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:

txt
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:

bash
hm -b --config native
hm -b --config portable

The 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:

  1. Run hm --clean to remove all objects
  2. Run hm -b once and let it build with the selected compiler
  3. Don't manually copy .o files between build/HelpMake/gcc/obj/ and build/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? ​

bash
hm -b --verbose

Every compile and link command prints:

text
[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.exe

Use --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:

cpp
#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? ​

CommandDeletes
hm --cleanbuild/HelpMake/ (objects, logs, PCH, deps)
hm --clean-gcmgcm.cache/ (GCC module cache)
hm --clean-allBoth

--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)

txt
Compiler: gcc
Version: std=c17
InputFiles { src/*.c }

Option 2: Zig CC

txt
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::Compiler interface in include/hm/toolchain/compiler.hpp. Contributing requires:
  1. Subclass hm::Compiler with your toolchain's flag shapes
  2. Register it in makeCompiler() in src/toolchain/toolchain.cpp
  3. Add a -YourName flag in src/cli/build.cpp if it deserves a shortcut
  4. 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::

txt
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:

txt
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:

bash
rm -rf build/HelpMake/dep/<name>
hm -b --config <your-config>

How do I generate a build.ninja file? ​

bash
hm --gen ninja
ninja

See 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::

txt
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:

txt
Config: test-math {
    Test: true
    Output: build/test-math.exe
    InputFiles { test/math.cpp }
}

Then:

bash
hm test

hm 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:

bash
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:

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 .git contents for a few seconds after clone
  • A background git process - tasklist | findstr git on Windows, ps aux | grep git on 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:

bash
rm build/HelpMake/<comp>/.buildid
hm -b

Can I build a project with no config file? ​

Yes. hm -b in a directory with no HelpMake.txt still builds. Every field is inferred:

bash
cd your-project
hm -b

HelpMake 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:

HeaderFlag (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:

txt
Kind: static

Non-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:

bash
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:

txt
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 hm command you ran
  • The contents of HelpMake.txt (redact anything private)
  • The --verbose output 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.

Released under the MIT License.