window

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

projectkindoutputwhat it is
blend2dstatic libblend2d.libthe vendored third party renderer plus asmjit, built from source we control
window.corestatic libwindow.core.libcore, present, host, render, scene, svg. does not draw a widget
window.widgetsstatic libwindow.widgets.libthe concrete controls n their default paints
window.testexewindow.test.exethe 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  ->  blend2d

window.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.0 is on this box, 10.0.19041.0 is the older one, take the newer)
  • the vendored source sitting at extern/blend2d/ n extern/asmjit/, see DEPS.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, location D:\projects\projects\window\cpp, n untick place solution and project in the same directory so you land on cpp\window.sln n 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 at cpp\window.props
  • drag it onto all four projects, under both Debug | x64 n Release | 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

pagefieldvalue
generalwindows sdk version10.0.26100.0
generalplatform toolsetVisual Studio 2022 (v143)
generalc++ language standardISO C++20 (/std:c++20)
generalc language standardDefault
generaloutput directory$(SolutionDir)bin\$(Platform)_$(Configuration)\
generalintermediate directory$(SolutionDir)build\$(Platform)_$(Configuration)\$(ProjectName)\
c/c++, generaladditional include directories$(SolutionDir);$(SolutionDir)window.core;$(SolutionDir)window.widgets;$(SolutionDir)extern\blend2d
c/c++, generalwarning level/W4
c/c++, generaltreat warnings as errorsYes (/WX)
c/c++, generalmulti processor compilationYes (/MP)
c/c++, generaldebug information formatProgram Database (/Zi)
c/c++, preprocessorpreprocessor definitionsWIN32_LEAN_AND_MEAN;NOMINMAX;UNICODE;_UNICODE;BL_STATIC;%(PreprocessorDefinitions)
c/c++, code generationruntime libraryMulti-threaded (/MT) in release, Multi-threaded Debug (/MTd) in debug
c/c++, languageconformance modeYes (/permissive-)
c/c++, languageenable c++ modulesNo
linker, systemsubsystemConsole (/SUBSYSTEM:CONSOLE)

five of those are load bearing n worth the sentence

  • BL_STATIC on 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 unresolved bl* 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.core is what turns the module folder name into the include prefix. $(SolutionDir) stays on the list for abi\, which sits at the root until phase 6 gives it a project
  • $(SolutionDir)extern\blend2d is the blend2d include root n it has no src on the end, 0.21 dropped the src/ folder n put everything under blend2d/ at the repo root, so we include it as #include <blend2d/blend2d.h>. anything on the web telling you to put src on the path is describing 0.12 or older, see DEPS.md
  • /MT not /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 classic LNK2038 mismatch
  • /WX is on, thats P1.1s criteria. it comes back off for the blend2d project only, see below
  • /Zi in 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

pagefieldvalue
c/c++, optimizationoptimizationDisabled (/Od)
c/c++, code generationbasic runtime checksBoth (/RTC1)
c/c++, preprocessoradd_DEBUG
linker, debugginggenerate debug infoGenerate Debug Information (/DEBUG)

n on release, x64

pagefieldvalue
c/c++, optimizationoptimizationMaximum Optimization (/O2)
c/c++, optimizationwhole program optimizationYes (/GL)
c/c++, preprocessoraddNDEBUG
linker, optimizationlink time code generationUse Link Time Code Generation (/LTCG)
linker, debugginggenerate debug infoGenerate 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.props like the others, then override these four on the project itself
pagefieldvaluewhy
c/c++, generalwarning level/W3not our code, not our warnings
c/c++, generaltreat warnings as errorsNoa third party warning must never stop our build
c/c++, generaladditional include directories$(SolutionDir)extern\blend2d;$(SolutionDir)extern\asmjit\src;%(AdditionalIncludeDirectories)it needs asmjits headers, we do not
c/c++, languagec++ language standardISO 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 .cpp under extern\blend2d\blend2d\, recursively, then every .cpp under extern\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 _test in its name, from both. thats what blend2ds own cmake does, it splits anything matching _test.cpp or _test_<ext>.cpp into 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

filespagefieldvalue
*_avx.cppc/c++, code generationenable enhanced instruction set/arch:AVX
*_avx2.cpp, *_avx2fma.cppc/c++, code generationenable enhanced instruction set/arch:AVX2
*_avx512.cppc/c++, code generationenable enhanced instruction set/arch:AVX512
*_avx2.cpp, *_avx512.cppc/c++, preprocessorpreprocessor definitions, addBL_TARGET_OPT_POPCNT;BL_TARGET_OPT_BMI2
*_avx2fma.cppc/c++, preprocessorpreprocessor definitions, addBL_TARGET_OPT_POPCNT;BL_TARGET_OPT_BMI2;BL_TARGET_OPT_FMA
*_sse3.cppc/c++, preprocessorpreprocessor definitions, add__SSE3__
*_ssse3.cppc/c++, preprocessorpreprocessor definitions, add__SSSE3__
*_sse4_1.cppc/c++, preprocessorpreprocessor definitions, add__SSE4_1__
*_sse4_2.cppc/c++, preprocessorpreprocessor definitions, add__SSE4_2__
*_sse2.cppnothing, 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_AVX512 is 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 startup
  • ASMJIT_ABI_NAMESPACE=abi_bl is 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 error
  • ASMJIT_NO_FOREIGN drops every non host backend, i.e. it only builds the x86 emitter, smaller n faster to compile
  • ASMJIT_NO_STDCXX keeps asmjit off the c++ runtime, which is what lets blend2d ship without one
  • ASMJIT_EMBED n ASMJIT_STATIC say asmjit is being compiled into another library rather than being one, so it exports nothing n expects no import stubs. EMBED implies STATIC in 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.core n window.widgets. with link library dependencies on (it is, by default) that alone links all three .lib files, 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.lib

the 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 at cpp\window.abi\ then move the project file into cpp\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 at abi\, whichever vs fights you less on
  • delete the sample files it drops in (dllmain.cpp included, there is no DllMain here) n set precompiled headers to Not Using, same as every other project
  • attach window.props, then override these on the project itself
pagefieldvaluewhy
generalconfiguration typeDynamic Library (.dll)it is the one project that is not a static lib or the exe
c/c++, preprocessorpreprocessor definitions, addGUI_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, inputadditional dependenciesuser32.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, systemsubsystemWindows (/SUBSYSTEM:WINDOWS)a dll has no console, the sheet says console bc the exe wants one
  • project, add, reference, tick window.core, window.widgets n blend2d, all three

    corrected 2026-09-05, this used to say blend2d comes through the chain n it does not. window.core.vcxproj carries no ProjectReference at all, so nothing pulls blend2d in behind it, which is exactly why window.test names all three. tick the third one or you get the wall of unresolved bl* symbols the trap list at the bottom describes

  • add the sources, abi\abi.cpp abi\abi_host.cpp abi\abi_scene.cpp abi\abi_theme.cpp, n the two headers abi\window_abi.h abi\abi.h

  • rtti stays ON (the default), the abi asks a control what it is with a dynamic_cast, see abi.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.vcxproj builds window.abi.dll, the shipping one, n abi\window.abi.tools.vcxproj builds window.abi.tools.dll, the same lib plus the inspection surface
  • neither one owns the source list. abi\abi.shared.props carries 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_TOOLS anywhere
  • test_abi_tools_split in window.test reads both export tables back n proves it, see abi\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 | x64 n Release | x64, build, clean, no warnings, no errors
  • window.core references nothing in window.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.exe starts n exits 0
  • no cmake file exists in the tree, extern/blend2d/CMakeLists.txt is 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 Release

it 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 /MD n 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_STATIC is missing on whichever project is doing the calling
  • MSB8027 two or more files with the name of x.cpp, msbuild flattens object names into one $(IntDir) so two sources sharing a basename write the same .obj n the second one wins. blend2d n asmjit both ship a core\string.cpp n it cost us a LNK1120, 12 unresolved externals on every bl_string_* symbol. the fix is an ObjectFileName of $(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 delete build\x64_Debug\blend2d\ before rebuilding, the stale wrong .obj is up to date as far as msbuild is concerned n it will link the bad one again
  • /WX firing on windows sdk headers, do not lower the warning level to fix it, wrap the include in #pragma warning(push) n pop at 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 /GL plus /LTCG surfacing an odr problem or an uninitialised read. turn /GL off long enough to confirm, then fix the real thing n turn it back on
  • adding a new .cpp n 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 in build/macos_<cfg>/, both already gitignored
  • make builds both the bare binary and window.demo.app, the bundle is the binary plus window.demo/Info.plist, ad hoc signed, so the dock and menu bar show a real name. open it to launch, run stays on the bare binary so its stdout lands in the terminal
  • make xcode writes window.xcodeproj for 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 abi builds libwindow.abi.dylib, the c abi for a lua or plain c caller, install_name @rpath/libwindow.abi.dylib and only the gui_* exports leave it. it diffs window_abi.h against the golden copy first, the twin of the msbuild AbiGoldenHeader. make abi-tools is the tools surface as its own dylib, and make abi-smoke builds probes/abi-smoke-mac.c against 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++) or CORE_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

On this page