building it
msvc and vs2022, no cmake anywhere
mirrored from
window/cpp/BUILD.md, which is the only copy of this text. edits made here are overwritten the next time the site builds
this is the hand wiring doc for P1.1. no cmake anywhere, no generated project files, you click these
together once n they stay clicked. an agent is not allowed to touch a .vcxproj or a .sln, so this doc
is the handover
read it top to bottom the first time, its written in the order you do it
what youre building
four projects in one solution, three static libs n an exe
| project | kind | output | what it is |
|---|---|---|---|
blend2d | static lib | blend2d.lib | the vendored third party renderer plus asmjit, built from source we control |
window.core | static lib | window.core.lib | core, present, host, render, scene, svg. does not draw a widget |
window.widgets | static lib | window.widgets.lib | the concrete controls n their default paints |
window.test | exe | window.test.exe | the test runner n the scratch app, links all three |
the dependency direction is one way n it is the whole point of the split
window.test -> window.widgets -> window.core -> blend2dwindow.core referencing anything in window.widgets is a build break we want, thats P1.1s done
criteria doing its job. the abi/ folder gets a fifth project (a dll) in phase 6, that is step 7 below
before you start
- vs2022 with the desktop development with c++ workload, msvc v143 n the windows 11 sdk (
10.0.26100.0is on this box,10.0.19041.0is the older one, take the newer) - the vendored source sitting at
extern/blend2d/nextern/asmjit/, seeDEPS.md. if those folders are empty, do that first, nothing here builds without them
there is a mutation runner at ../tools/mutate.py, which breaks one known value
in a header n reports whether any check noticed. reach for it before calling a new check done, a green
check can be passing for a reason that has nothing to do with the code n this is what tells you
step 1, the solution
- file, new, project, blank solution, named
window, locationD:\projects\projects\window\cpp, n untick place solution and project in the same directory so you land oncpp\window.slnn nothing else beside it
every project after this gets added into that solution, n vs will want to make each one its own folder,
cpp\window.core\window.core.vcxproj. let it, n put the module folders inside it, so
cpp\window.core\core\, cpp\window.core\render\ n the rest. a project owning the files under its own
directory is what vs assumes everywhere, add existing item lands in the right place by default, n the
.vcxproj carries no ..\ at all
corrected 2026-08-15, this used to say the module folders stay at cpp\ n the projects point outside
their own directory. they were moved in, n the four .vcxproj n the sheet were corrected with them
so the shape you end up with is
cpp\
window.sln
window.props
blend2d\blend2d.vcxproj
window.core\window.core.vcxproj core\ dump\ present\ host\ render\ scene\ svg\
window.widgets\window.widgets.vcxproj controls\
window.test\window.test.vcxproj tests\
abi\ probes\ extern\abi\ has no project until phase 6, probes\ is never in one, each probe carries its own cl.exe line
on every project vs creates, delete the pch.h, pch.cpp, framework.h n the sample .cpp it drops
in, n set c/c++, precompiled headers to Not Using Precompiled Headers. we do not use them, n the
sample files break the build the moment you delete them without switching the setting off
step 2, the settings every project shares
do this once as a property sheet rather than four times by hand
- view, other windows, property manager, right click the solution, add new property sheet, name it
window.props, save it atcpp\window.props - drag it onto all four projects, under both
Debug | x64nRelease | x64 - every setting below goes in the sheet, n a project only overrides what its own section says
open the sheet, set the configuration selector to all configurations n x64 before you type
| page | field | value |
|---|---|---|
| general | windows sdk version | 10.0.26100.0 |
| general | platform toolset | Visual Studio 2022 (v143) |
| general | c++ language standard | ISO C++20 (/std:c++20) |
| general | c language standard | Default |
| general | output directory | $(SolutionDir)bin\$(Platform)_$(Configuration)\ |
| general | intermediate directory | $(SolutionDir)build\$(Platform)_$(Configuration)\$(ProjectName)\ |
| c/c++, general | additional include directories | $(SolutionDir);$(SolutionDir)window.core;$(SolutionDir)window.widgets;$(SolutionDir)extern\blend2d |
| c/c++, general | warning level | /W4 |
| c/c++, general | treat warnings as errors | Yes (/WX) |
| c/c++, general | multi processor compilation | Yes (/MP) |
| c/c++, general | debug information format | Program Database (/Zi) |
| c/c++, preprocessor | preprocessor definitions | WIN32_LEAN_AND_MEAN;NOMINMAX;UNICODE;_UNICODE;BL_STATIC;%(PreprocessorDefinitions) |
| c/c++, code generation | runtime library | Multi-threaded (/MT) in release, Multi-threaded Debug (/MTd) in debug |
| c/c++, language | conformance mode | Yes (/permissive-) |
| c/c++, language | enable c++ modules | No |
| linker, system | subsystem | Console (/SUBSYSTEM:CONSOLE) |
five of those are load bearing n worth the sentence
BL_STATICon everything, blend2ds headers switch their declarations between dllimport n plain on that define, so a consumer that misses it links against import stubs that do not exist n you get a wall of unresolvedbl*externals- the two project roots as include dirs are what make a cross module include read
#include "scene/control.h"from anywhere in the tree, no relative..\..\anywhere. the modules live under their project now, so$(SolutionDir)alone no longer reaches them n$(SolutionDir)window.coreis what turns the module folder name into the include prefix.$(SolutionDir)stays on the list forabi\, which sits at the root until phase 6 gives it a project $(SolutionDir)extern\blend2dis the blend2d include root n it has nosrcon the end, 0.21 dropped thesrc/folder n put everything underblend2d/at the repo root, so we include it as#include <blend2d/blend2d.h>. anything on the web telling you to putsrcon the path is describing 0.12 or older, seeDEPS.md/MTnot/MD, static crt, bc the phase 6 dll ships next to an ahk script n a static crt means no redist to chase on someone elses machine. all four projects must agree, mixing them is the classicLNK2038mismatch/WXis on, thats P1.1s criteria. it comes back off for the blend2d project only, see below/Ziin release too, a pdb costs nothing at runtime n a release only crash with no symbols is a wasted afternoon
then per configuration, with the selector on debug, x64
| page | field | value |
|---|---|---|
| c/c++, optimization | optimization | Disabled (/Od) |
| c/c++, code generation | basic runtime checks | Both (/RTC1) |
| c/c++, preprocessor | add | _DEBUG |
| linker, debugging | generate debug info | Generate Debug Information (/DEBUG) |
n on release, x64
| page | field | value |
|---|---|---|
| c/c++, optimization | optimization | Maximum Optimization (/O2) |
| c/c++, optimization | whole program optimization | Yes (/GL) |
| c/c++, preprocessor | add | NDEBUG |
| linker, optimization | link time code generation | Use Link Time Code Generation (/LTCG) |
| linker, debugging | generate debug info | Generate Debug Information (/DEBUG) |
_DEBUG is the debug guard finn-style uses, n msvc defines it for you off /MTd anyway, its listed so
the intent is written down
step 3, the blend2d project
this one is third party source, so it plays by different rules to ours
- add, new project, static library, name it
blend2d - attach
window.propslike the others, then override these four on the project itself
| page | field | value | why |
|---|---|---|---|
| c/c++, general | warning level | /W3 | not our code, not our warnings |
| c/c++, general | treat warnings as errors | No | a third party warning must never stop our build |
| c/c++, general | additional include directories | $(SolutionDir)extern\blend2d;$(SolutionDir)extern\asmjit\src;%(AdditionalIncludeDirectories) | it needs asmjits headers, we do not |
| c/c++, language | c++ language standard | ISO C++17 (/std:c++17) | 17 is the floor blend2d states n what its own cmake asks for. c++20 changes enough (char8_t, rewritten operator==) that theres no reason to take the risk on code we did not write |
corrected 2026-08-15 once the source was actually on disk, the line above used to read
$(SolutionDir)extern\asmjit\src n that path does not exist. asmjit denested its src/ too, so both
roots are the same shape now, extern\blend2d n extern\asmjit, n the headers include as
<asmjit/asmjit.h>. also worth knowing, this version ships no _avx512.cpp at all, so
BL_BUILD_OPT_AVX512 is a dispatcher ceiling with nothing under it rather than a set of files to flag
different standards across static libs in one binary is fine here, blend2ds linked object code is a c abi n the c++ side of it is header only inline wrappers
the sources
- right click the project, add, existing item, n take every
.cppunderextern\blend2d\blend2d\, recursively, then every.cppunderextern\asmjit\src\asmjit\the same way - nothing from
extern\blend2d\blend2d-testing\, thats upstreams own test n demo tree, it is not part of the library - then remove every file with
_testin its name, from both. thats what blend2ds own cmake does, it splits anything matching_test.cppor_test_<ext>.cppinto a separate test target, n on 0.12 that was 52 files of 174, so its not a rounding error - leave the arm files (
*_asimd*.cpp,simdarm_*) in, they are guarded internally n compile to nothing on x64, which is exactly what cmake does with them
the per file flags, the fiddly bit
blend2d compiles a handful of files at a higher instruction set than the rest n dispatches to them at runtime. cmake does that with a per source property n we have to do it by hand, select the files in solution explorer, right click, properties. the rule is the filename suffix
| files | page | field | value |
|---|---|---|---|
*_avx.cpp | c/c++, code generation | enable enhanced instruction set | /arch:AVX |
*_avx2.cpp, *_avx2fma.cpp | c/c++, code generation | enable enhanced instruction set | /arch:AVX2 |
*_avx512.cpp | c/c++, code generation | enable enhanced instruction set | /arch:AVX512 |
*_avx2.cpp, *_avx512.cpp | c/c++, preprocessor | preprocessor definitions, add | BL_TARGET_OPT_POPCNT;BL_TARGET_OPT_BMI2 |
*_avx2fma.cpp | c/c++, preprocessor | preprocessor definitions, add | BL_TARGET_OPT_POPCNT;BL_TARGET_OPT_BMI2;BL_TARGET_OPT_FMA |
*_sse3.cpp | c/c++, preprocessor | preprocessor definitions, add | __SSE3__ |
*_ssse3.cpp | c/c++, preprocessor | preprocessor definitions, add | __SSSE3__ |
*_sse4_1.cpp | c/c++, preprocessor | preprocessor definitions, add | __SSE4_1__ |
*_sse4_2.cpp | c/c++, preprocessor | preprocessor definitions, add | __SSE4_2__ |
*_sse2.cpp | nothing, sse2 is implicit on x64 msvc |
always keep %(PreprocessorDefinitions) on the end of a per file define list or you drop everything the
property sheet set. the __SSE*__ ones exist bc msvc, unlike every other compiler, defines no macro for
sse3 n up, so blend2d defines them itself to keep its own #ifs portable
the project wide defines it also needs
on the blend2d project, c/c++, preprocessor, preprocessor definitions, add these to what the sheet already gives it
BL_STATIC
BL_BUILD_OPT_AVX512
ASMJIT_EMBED
ASMJIT_STATIC
ASMJIT_NO_STDCXX
ASMJIT_NO_FOREIGN
ASMJIT_ABI_NAMESPACE=abi_bl
%(PreprocessorDefinitions)every one of those is lifted straight out of the CMakeLists.txt sitting in the vendored copy, so if
something here ever looks wrong, that file is the source of truth n this doc is the reading of it
BL_BUILD_OPT_AVX512is the ceiling of the runtime dispatcher, not a requirement on the cpu running it. blend2ds cmake sets it unconditionally on x86 n x64, every path below it is still built n the one that runs is picked off cpuid at startupASMJIT_ABI_NAMESPACE=abi_blis not optional, it is how blend2d keeps its private asmjit from colliding with any other asmjit in the same process, n if we ever link one, a mismatch here is a silent odr violation rather than a link errorASMJIT_NO_FOREIGNdrops every non host backend, i.e. it only builds the x86 emitter, smaller n faster to compileASMJIT_NO_STDCXXkeeps asmjit off the c++ runtime, which is what lets blend2d ship without oneASMJIT_EMBEDnASMJIT_STATICsay asmjit is being compiled into another library rather than being one, so it exports nothing n expects no import stubs.EMBEDimpliesSTATICin asmjits own build, both are listed here bc we are not running that build n a define that is already implied costs nothing
one optional tweak worth taking
set the blend2d project alone to /O2 in the debug config, n leave the basic runtime checks off for
it. we never step into blend2d, an unoptimised rasteriser with /RTC1 on it is genuinely painful to sit
through, n our own code stays fully debuggable. its two fields on one project
step 4, window.core
- add, new project, static library, name it
window.core, attach the sheet, no overrides - the folders
core\,present\,host\,platform\,render\,scene\,svg\live under the project folder, add them as filters n add their files as they get written - linker inputs, none. a static lib does not link, it just archives objects. every system lib gets named on the exe, not here
on the last point, you can put dwrite.lib n friends in a static libs linker input page n vs will
record them, but the honest place is the exe n phase 6s dll, so keep them there n keep one list
step 5, window.widgets
- add, new project, static library, name it
window.widgets, attach the sheet, no overrides - add the
controls\folder, which lives under the project folder - project, add, reference, tick
window.core. this is what carries the include paths n the link order through automatically
do not add a reference the other way. if you ever find yourself wanting one, something that belongs in
scene/ has been written in controls/
step 6, window.test
- add, new project, console application, name it
window.test, attach the sheet - project, add, reference, tick
window.corenwindow.widgets. with link library dependencies on (it is, by default) that alone links all three.libfiles, blend2d included through the chain - linker, input, additional dependencies, add the system libs
user32.lib
gdi32.lib
dwrite.lib
%(AdditionalDependencies)P1.16 landed n these three did NOT go on this list, they are named by the one file that needs them
instead, #pragma comment(lib, ...) at the top of window.core\present\presenter_dcomp.cpp, same as
render\font_dwrite.cpp already does for dwrite.lib
d3d11.lib
dxgi.lib
dcomp.libthe directive rides in the .obj, through window.core.lib, n the linker honours it when it pulls that
object out, so every consumer of the static lib gets them with nothing to remember. if a future project
ever links window.core n cannot find them, this is the paragraph that explains where they come from
blend2d itself needs nothing beyond the default libs, it is on kernel32 n nothing else on windows
- set it as the startup project, right click, set as startup project
the manifest, P1.33
P1.33 landed n it did NOT need this, no project file was touched for it. per monitor v2 is declared at
runtime instead, gui::declare_dpi_v2() in window.core\host\dpi.h, which host_t::create calls before
the first window exists. that was the honest way round for a lib, window.core cannot put a manifest
on a host process it did not build, so a consumer that forgot one would otherwise get the blurry path with
nothing to tell them
the manifest is still the better answer for an exe you own, bc it applies before a single line of our
code runs. so if you ever want one here, it goes on window.test n on nothing else, linker, manifest file, dpi awareness set to Per Monitor High DPI Aware, n the two do not fight, declare_dpi_v2 sees
awareness is already v2 n takes an early return
what you must NOT do is set it to anything other than per monitor v2. a manifest wins, so a System Aware
one silently overrules the runtime call, declare_dpi_v2 comes back false n every window in the process
goes back to being lied to about which monitor it is on
step 7, window.abi, the dll (P1.23)
the fifth project, the one abi\ has been waiting on. it is a dll, it links both static libs, n
it is what an ahk script loads
this one is WRITTEN n in the solution as of 2026-09-05, abi\window.abi.vcxproj, guid
{A1B2C3D4-0005-...0005}, n both configs build clean. finn okayed writing this one by hand as a new
project, which the never touch a vcxproj rule otherwise covers. so the clicking below is the record
of what it is set to rather than a thing to do, n it is what you check against if it ever drifts
- add, new project, dynamic-link library, name it
window.abi, let vs put it atcpp\window.abi\then move the project file intocpp\abi\n fix the solution path, so the module folder rule holds n the project owns the files under its own directory. or make the project first n point it atabi\, whichever vs fights you less on - delete the sample files it drops in (
dllmain.cppincluded, there is no DllMain here) n set precompiled headers toNot Using, same as every other project - attach
window.props, then override these on the project itself
| page | field | value | why |
|---|---|---|---|
| general | configuration type | Dynamic Library (.dll) | it is the one project that is not a static lib or the exe |
| c/c++, preprocessor | preprocessor definitions, add | GUI_ABI_BUILD;%(PreprocessorDefinitions) | flips GUI_API to dllexport, abi.h defines it too so a build never depends on this line, it is here so the intent is written down |
| linker, input | additional dependencies | user32.lib;gdi32.lib;dwrite.lib;%(AdditionalDependencies) | the same three the exe names, the d3d ones ride in on the #pragma comment in window.core |
| linker, system | subsystem | Windows (/SUBSYSTEM:WINDOWS) | a dll has no console, the sheet says console bc the exe wants one |
-
project, add, reference, tick
window.core,window.widgetsnblend2d, all threecorrected 2026-09-05, this used to say blend2d comes through the chain n it does not.
window.core.vcxprojcarries noProjectReferenceat all, so nothing pulls blend2d in behind it, which is exactly whywindow.testnames all three. tick the third one or you get the wall of unresolvedbl*symbols the trap list at the bottom describes -
add the sources,
abi\abi.cppabi\abi_host.cppabi\abi_scene.cppabi\abi_theme.cpp, n the two headersabi\window_abi.habi\abi.h -
rtti stays ON (the default), the abi asks a control what it is with a
dynamic_cast, seeabi.h
the output lands beside the exe, bin\x64_Debug\window.abi.dll n the .lib import stub next to it,
n a script loads the dll by that path. /MT is what makes that work on a box with no redist, see
the sheet
P1.41 landed 2026-09-11 n it IS a second project, which is the opposite of what this paragraph predicted, so here is why it went the other way
abi\window.abi.vcxprojbuildswindow.abi.dll, the shipping one, nabi\window.abi.tools.vcxprojbuildswindow.abi.tools.dll, the same lib plus the inspection surface- neither one owns the source list.
abi\abi.shared.propscarries every source, every reference n the golden header check, n both import it, so the thing the old paragraph was afraid of, two projects drifting apart, is stopped by there being nothing in either to drift - the tools project adds exactly one
ClCompile,tools\abi_tools.cpp, n that one line is the whole split - a define was the wrong answer n that is the correction worth reading. a define is a switch
somebody can get wrong, set in the wrong config, inherited off a sheet nobody read, or left on by a
copy pasted project, n every one of those ships an inspection surface to a caller who should not have
one. a file the release project never LISTS cannot end up in the release dll at all, so the split is
file selection n there is no
GUI_ABI_TOOLSanywhere test_abi_tools_splitinwindow.testreads both export tables back n proves it, seeabi\tools\README.md
proving it
gui_abi_version() returning 1 off a DllCall is the smoke test, n a script that creates a desc,
makes a host off it, sets a bare control as the root, pumps once n destroys the lot with every call
returning 0 is the whole of P1.23s done criteria walked. the wrapper lib (P1.25) is what turns that
into something a person would write
that walk is written n it lives at probes\abi-smoke.c, run it with probes\build-abi-smoke.bat
once the solution is built. it is compiled as c, which is the point, it fails the moment something
c++ shaped leaks into window_abi.h. all 30 checks green 2026-09-05 against both the hand built
dll n the project built one, so P1.23s done criteria are walked n passed
proving it, P1.1s done criteria
before the criteria, the smoke test, bc a solution that builds with nothing in it proves nothing. drop
this in tests\main.cpp n run it, it links blend2d for real (BLImages ctor is a symbol out of the lib,
not a header inline) n it prints the version so a future version bump is visible the second it happens
#include <blend2d/blend2d.h>
#include <cstdio>
//
// the P1.1 smoke test, proves the four projects link n blend2d is really in there
//
int main()
{
BLImage img(64, 64, BL_FORMAT_PRGB32);
printf("blend2d %d.%d.%d, image %dx%d\n"
, BL_VERSION >> 16, (BL_VERSION >> 8) & 0xFF, BL_VERSION & 0xFF
, img.width(), img.height());
return 0;
}it should print blend2d 0.21.2, image 64x64. if it prints anything else, the vendored copy is not the
one DEPS.md pins
P1.1 is done when all five hold, so walk them
- build, batch build, tick all four projects in both
Debug | x64nRelease | x64, build, clean, no warnings, no errors window.corereferences nothing inwindow.widgets, check by eye now, n it stays true bc there is no reference edge pointing that way- the test exe links both n runs, i.e.
window.test.exestarts n exits 0 - no cmake file exists in the tree,
extern/blend2d/CMakeLists.txtis the one exception n it is vendored upstream text we do not run, do not delete it, deleting files inside a vendored copy is what makes the next upstream merge a mess - x86 n arm64 are gone, open build, configuration manager, delete every platform except x64 n every configuration except debug n release. an untested config is a lie waiting to be discovered
all five walked n passed 2026-08-15. a clean rebuild of both configs is green with no warnings, n both
bin\x64_Debug\window.test.exe n the release one print blend2d 0.21.2, image 64x64 n exit 0
build.bat, the one line version
cpp\build.bat [Debug|Release] builds the solution with both build traps already handled, i.e. it points
TEMP n TMP at a dir it knows is writable, n it builds the sln n never a project. it exists bc
those two cost every fresh session the same twenty minutes otherwise
build.bat Debug
build.bat Releaseit is a convenience n not the source of truth, everything above is still what the projects are actually set to. vs itself needs none of it
the things that will bite
LNK2038 mismatch detected for RuntimeLibrary, one project is on/MDn the rest on/MT, or a config got added after the sheet was attached. fix the odd one out, dont fix it by moving the others- a wall of unresolved
bl*symbols,BL_STATICis missing on whichever project is doing the calling MSB8027two or more files with the name ofx.cpp, msbuild flattens object names into one$(IntDir)so two sources sharing a basename write the same.objn the second one wins. blend2d n asmjit both ship acore\string.cppn it cost us aLNK1120, 12 unresolved externalson everybl_string_*symbol. the fix is anObjectFileNameof$(IntDir)asmjit\on the asmjit copy, i.e. c/c++, output files, object file name, n the warning is the only thing that tells you, so never let one sit. after fixing it deletebuild\x64_Debug\blend2d\before rebuilding, the stale wrong.objis up to date as far as msbuild is concerned n it will link the bad one again/WXfiring on windows sdk headers, do not lower the warning level to fix it, wrap the include in#pragma warning(push)npopat the one site, or add the specific warning number to c/c++, advanced, disable specific warnings with a comment saying which header made us- the release build failing where debug is clean, usually
/GLplus/LTCGsurfacing an odr problem or an uninitialised read. turn/GLoff long enough to confirm, then fix the real thing n turn it back on - adding a new
.cppn forgetting to add it to a project, msbuild has no globbing, so a file exists on disk n silently is not compiled. if a symbol is unresolved n the code is definitely there, this is why
macos, the make build
the mac has no solution, cpp/Makefile builds the same neutral sources with clang, the macos half of
platform/ in place of the win32 one, and the quartz presenter and coretext fonts in place of dxgi and
dwrite. no cmake and no xcode project, just the command line tools
make -j10
make -j10 run
make -j10 app
make CONFIG=Release -j10
make clean- outputs land in
bin/macos_<cfg>/, objects inbuild/macos_<cfg>/, both already gitignored makebuilds both the bare binary andwindow.demo.app, the bundle is the binary pluswindow.demo/Info.plist, ad hoc signed, so the dock and menu bar show a real name.openit to launch,runstays on the bare binary so its stdout lands in the terminalmake xcodewriteswindow.xcodeprojfor debugging in xcode, blend2d, window.core, window.widgets, the demo and the abi dylib, with the same flags. it reads its source lists OUT of this Makefile, so the Makefile stays the one list and a new source means rerun it. it is gitignored, never hand edit it- blend2d and asmjit build from the vendored source in about 10s, the x86 only sources compile to nothing
make abibuildslibwindow.abi.dylib, the c abi for a lua or plain c caller,install_name @rpath/libwindow.abi.dyliband only thegui_*exports leave it. it diffswindow_abi.hagainst the golden copy first, the twin of the msbuildAbiGoldenHeader.make abi-toolsis the tools surface as its own dylib, andmake abi-smokebuildsprobes/abi-smoke-mac.cagainst it, run by hand bc it opens a window- window.test is windows only for now, the runner leans on the win32 presenters
- a new core source goes in
CORE_SRC(plain c++) orCORE_MM(objective c++), a win32 only file goes in neither
the vcxproj side of the split, for the record, window.core compiles platform\win32\host_win32.cpp,
os_win32.cpp and pump_win32.cpp in place of the old host\pump.cpp, and none of the .mm files or
presenter_quartz ever go in the solution