Working with jumbo/unity builds in C/C++
austinmorlan.com
austinmorlan.com
1. Merge related cpp and h files together in groups into monolith files, usually in the order of 10-20 source files merged based on my observations - often entire modules will be grouped together. 2. Exclude any individual files from the monolith that have edits since the last change.
It's a nice middle ground, you don't substantially slow down your incremental builds since the files you're editing are still compiled individually, plus you get a fairly substantial improvement in build times.
It's nice in that you can still structure your source in separate cpp/h files will little extra consideration for the unity builds and it mostly "just works" in both unity mode and with regular builds.
Unfortunately you occasionally do have issues with builds that work in unity but not in individual compilation or vice versa (usually due to arcane #include dependency chains) but they're usually easy to fix.
We worked around this by introducing a mandatory pre-merge CI stage that constantly does non-unity builds - but it's costly and not something a small company can often afford (a non-unity build of our UE project is ~20min on a Linux runner, and way more on a Windows one. That adds up fast).
Unreal itself hasn't been non-unity buildable for a very long time. In general IMHO Unity builds are a testament to the failure of the C++ standards committee to realise that modules and the building model should be part of the standard to. The "one file is a translation unity" hasn't been adequate for years IMHO - I honestly appreciate how Rust basically imposed cargo as a standard, it was a hard but sane choice.
> We worked around this by introducing a mandatory pre-merge CI stage that constantly does non-unity builds - but it's costly and not something a small company can often afford (a non-unity build of our UE project is ~20min on a Linux runner, and way more on a Windows one. That adds up fast).
Or you could only build the files that have changed. Even the largest of large files are one minute compiles.
> Unreal itself hasn't been non-unity buildable for a very long time.
Unreal builds in non-unity just fine. There was definitely a time period where it _didn't_, but for the last few years it's been much better than that.
yes, I must admit it's not the end of the world, but it tends to add an extra layer of gotchas on top of our already crufty legacy codebase (millions of lines of code, >100 devs on 3 different platforms). Which is something I'd rather not have to deal with, honestly.
> Or you could only build the files that have changed
In my experience the UBT is somewhat inconsistent with that. I've seen multiple times for instance Mac builds being borked on our main branch because a Windows developer pushed code that built absolutely perfectly on their machine.
> Unreal builds in non-unity just fine. There was definitely a time period where it _didn't_, but for the last few years it's been much better than that.
last time I tried 5.1 refused to build non-unity on Linux. Did they fix it with the version after that?
We target windows, linux, xsx and ps5 and have probably 15-20 programmers making contributions daily and probably only hit maybe one or two of these issues per week, and they rarely get checked in as we get them during our mandatory preflight build during code review, similar to what you describe. We run all the preflight on on-prem machines now so the cost is minimized compared to our former cloud solution.
We did a lot of work to modularize our codebase so maybe that is helping?
Almost definitely the case. We have 100+ devs on a >1M legacy codebase with a lot of cross dependencies, and it's incredibly troublesome without a strict pre-build stage on CI (on premise of course, it's too expensive to run all of that on AWS)
> You can still use header files if you want to, they’re just no longer strictly necessary. You’re free to put struct definitions and function prototypes into a header file if you’d like.
But is it really? not enforcing header files across the codebase means that you'll definitely end up with some inconsistency sooner or later that will be hard to deal with.
> The order that you include the source files in all.c matters. In the above example, bar.c had to be included before foo.c because foo.c used a struct and function that was defined in bar.c.
This is just additional overhead that you don't need while implementing something new.
And in general, this goes against how normally C/C++ codebases are structured, I'm sure I'll be hella confused about a file called `all.c`.
My experience was that there was decent benefit to keeping the .h/.cpp build running. Most 'normal' C++ tools and IDEs are not going to assume you are using a Unity build and tend to choke on it. Even though we never really shipped anything from the non-Unity build, having it around was useful for avoiding 'phantom' errors in the IDE and having static analysis tools work properly.
Details here: https://sqlite.org/amalgamation.html
It's also touted as an easy way to embed sqlite.
Combing many cpp files into a single translation unit is a good idea. More projects should do this. Infact I’d go so far as to say that most non-trivial, popularC++ projects on GitHub could and should probably be boiled down to a single translation unit.
The amount of redundant compiling in C++ is insane. Any project that uses STL is compiling the same crap over and over and over and over and over. Then counting on the linker to deduplicate the billions of cycles of wasted work.
Transitioning existing code to use modules is also not entirely straightforward, though probably no more problematic than introducing unity builds.
A "Unity build" really just means typing #include "foo.cpp" a few times. It's trivial.
Meanwhile, neither Clang nor GCC support standard library modules. They have only partial support for modules themselves. C++ module support is non-existent in almost all build systems. https://en.cppreference.com/w/cpp/compiler_support
The idea of C++ modules is great. It's badly needed. In practice I'm not sure if they're ever going to be genuinely functional and widespread. Which makes me sad. Toy projects don't count.
Yes, it's very late, but progress is being made.
I ignored this article on the front page because of that. Only because it stayed on the front page for several hours did (and because I care about C++ build issues) did I eventually click on it.
Look no further, these builds will give you more than enough issues on any sizable project.
Both WebKit and Chromium support unity/jumbo builds. They combine around 20 source files at a time into a single compilation unit, which provides a reasonable tradeoff - making the full build noticeably faster without overflowing RAM and without making the cost of recompiling after a single change too large. You also get lots of parallelism.
Making a unity / jumbo build work for a project with 10,000+ files and millions of lines of code is not simple at all.
Non-unified builds are still built to make sure there are no unexpected side effects or accidental header file dependencies.
https://firefox-source-docs.mozilla.org/build/buildsystem/un...
https://news.ycombinator.com/item?id=35825683 - Unity builds lurked into the Firefox Build System (2023)
The page that was referenced by that thread has moved, current location is
https://serge-sans-paille.github.io/pythran-stories/how-unit...
For years we rolled our own unity build, but now CMake supports it directly through CMAKE_UNITY_BUILD and CMAKE_UNITY_BUILD_BATCH_SIZE, making it straightforward to enable.
When first enabling it on a large project, you'll run into clashes where different files contain identically-named file-scoped function or variables. Sometimes this reveals copy-pasted code, where the fix is to refactor the duplicate code anyway. Other times you just pick more specific names to avoid the clash.
We find unity build gives a solid 3X build speedup. We haven't eliminated header files, and in fact keep one slow CI job building the code without unity to ensure our code still builds either way.
used to https://groups.google.com/a/chromium.org/g/chromium-dev/c/DP...
Making a unity / jumbo build work for a project with 10,000+ files and millions of lines of code is not simple at all.
Clang uses a 32-bit number to identify AST nodes. If a single translation unit is large enough, it can overflow this and you can get some very weird compilation errors.
Luckily there are unity build tools that do not require manual changes to code and work with normal .h/.cpp files automatically.
The best possibility is if your build system can detect which files have changed and exclude them from unity builds, as this gives you the "slow path" the first time you change a file, but from then on you get the fast path behaviour.
Having 2 units per cpu core in your machine is a much better idea.