Move your engine pin
Your project pins Labrador: external/labrador is a submodule, and your repository records the
one commit of it you build against. Nothing moves that pin for you. To move the pin to a newer
release, follow the steps below in order. Each one checks something before the next relies on it,
and until step 7 nothing is recorded, so going back is one line. It
takes about 20 minutes, most of it reading, and the build after it a few minutes.
This page is for a project in Git. If your project came from the
starter ZIP and external\labrador is a plain folder, follow
Move a starter project to a newer Labrador instead, or first
Put your project in Git.
The commands are for the x64 Native Tools Command Prompt in your project’s folder:
cd /d C:\dev\mygameThe examples move from v0.1.0 to v0.2.0, and the output shown is from that move. Use your own
pin, which step 1 shows, and the tag you are moving to. Before you start, commit or undo any
change you have not recorded, so that git status says nothing to commit, working tree clean:
Save and undo changes with Git shows how.
-
Fetch the engine’s tags and choose one.
Terminal window git -C external/labrador fetch --tagsgit -C external/labrador describe --tagsgit -C external/labrador tag --list "v*" --sort=-v:refnamefetchdownloads what Labrador’s repository has that your copy does not, which takes a few seconds. It prints nothing when there is nothing new. Otherwise it printsFrom https://github.com/matt439/Labradorand a line for each new release, such as:Output * [new tag] v0.2.0 -> v0.2.0describenames your current pin andtag --listlists the releases, newest first:Output v0.1.0v0.2.0v0.1.0The first line is your pin. If it is longer, such as
v0.2.0-214-g47be5a3, your pin is not a release: it is 214 commits afterv0.2.0, at the commit whose name starts47be5a3. Read CHANGES.md from that release’s heading in step 2.Move to a release tag rather than to
master: a tag’s notes and its CHANGES.md heading say what it holds, andmastercan change under you. Moving several releases at once is one move: choose the newest, and read every release between in step 2.If
fetchsaysfatal: unable to access 'https://github.com/matt439/Labrador.git/': Could not resolve host: github.com, the machine could not reach GitHub; check the connection and run it again.describeandtag --liststill work without it, but list only the releases you had. -
Read CHANGES.md between the two. Every change a game can see between two releases is an entry there, under the newer release’s heading, with what to do about it where there is something to do. These lines write the new release’s copy to a file and list its headings:
Terminal window git -C external/labrador show v0.2.0:CHANGES.md > "%TEMP%\CHANGES-v0.2.0.md"findstr /b /c:"## " /c:"### " /c:"#### " "%TEMP%\CHANGES-v0.2.0.md"Output ## The rule## Entries## v0.2.0 (2026-10-25)#### Add a browser build to the Get Started project#### Keep a debug build running where there is no audio endpoint#### Keep a scene's collision objects in the order they were added#### Re-point sprites and animations by a resolved sheet pair#### Name every key, so a game can save a binding and read it back#### Windows 10 version 1607 is the floor#### Keep the client size in a per-monitor-aware process#### Let F10 and Alt alone be keys, not the system menu#### Keep a hidden window hidden when it changes full screen## v0.1.0 (2026-10-13)### Backfill: from 4cefb68 to 65116c3#### Moving a pin from 4cefb68, in short...The entries to read are those under every release heading above your pin’s, here the nine under
## v0.2.0. Releases afterv0.2.0head each entry with###and its date, such as### 2026-10-29 - Keep a Win32 window shown through full screen. Open the file to read them:Terminal window notepad "%TEMP%\CHANGES-v0.2.0.md"In Notepad, Ctrl+F finds a heading. Each entry says what kind of change it is in its first lines. A source break means code that compiled before may not compile after, and names the old spelling and the new; a behaviour change means the game compiles as before and does something different. Many entries end with Nothing to migrate or No migration is needed. Note the ones that ask something of you for step 6; Update your code for a newer Labrador has copyable boxes for the source breaks a starter project meets. Numbers such as
SM-57in an entry are the owner’s references to other records, not things for you to do.The same file is on GitHub at the new tag, for example CHANGES.md at v0.2.0, which shows it formatted.
If
git showsaysfatal: invalid object name 'v0.2'., the tag is misspelt, here missing its last.0: check it against step 1’s list. -
Compare the engine’s manifest with yours. vcpkg reads only your
vcpkg.json, so a dependency the engine adds, or abuiltin-baselineit moves, reaches your build only when you copy it across. First see whether the engine’s changed between the two releases:Terminal window git -C external/labrador --no-pager diff v0.1.0 v0.2.0 -- vcpkg.jsonOutput diff --git a/vcpkg.json b/vcpkg.jsonindex 0b32861..7b9e002 100644--- a/vcpkg.json+++ b/vcpkg.json@@ -1,6 +1,6 @@{"name": "labrador",- "version-string": "0.1.0",+ "version-string": "0.2.0","dependencies": [{"name": "directxtk",A
-line is the old release’s and a+line the new one’s; the rest is shown around them. Here onlyversion-stringchanged, so there is nothing to copy, and you can go on to step 4. If it prints nothing, the file did not change at all.If the diff shows another line changing, compare the new file with yours:
Terminal window git -C external/labrador show v0.2.0:vcpkg.jsontype vcpkg.jsonMake yours match by these rules, in Notepad (
notepad vcpkg.json):- Your
dependenciesare the engine’s, withoutlodepng, which only the engine’s own tests use; withdoctestif your project has tests, as every project made sincev0.2.0does; and with any library you added yourself. Copy an entry the engine gained, with its{ }andfeaturesif it has them, into your list, and put a comma after the entry before it. - Your
builtin-baselineis the engine’s, exactly: copy its 40 characters between the quotation marks. - Leave your
nameandversion-stringas they are.
The
vcpkg.jsonStart your own project shows is derived from this site’s revision, not from your pin, so compare with the engine’s file at the tag, not with that page. Step 6’s configure checks the result: a missing comma stops it with an error namingvcpkg.jsonand the line. - Your
-
See what changed in the template. Your
gamefolder began as a copy ofsamples/minimal, and your project’s own files as copies of the files in the engine’swebsite/src/walkthrough/. A copy is yours: nothing updates it. The sample’s README keeps a list, newest first, of the changes to it that a copy taken before them would want. Write the part of it that is new between your tag and the new one to a file, and open it:Terminal window git -C external/labrador --no-pager diff v0.1.0 v0.2.0 -- samples/minimal/README.md > "%TEMP%\template-changes.txt"notepad "%TEMP%\template-changes.txt"The new entries are the lines that start
+- **, each dated, such as+- **2026-10-25.** Tests, from the start.The+only marks them as new. Each names the files it changes. To see which files changed in all, with how many lines each:Terminal window git -C external/labrador --no-pager diff --stat v0.1.0 v0.2.0 -- samples/minimal website/src/walkthroughOutput samples/minimal/CMakeLists.txt | 90 +++++++++++++++++++++--samples/minimal/README.md | 73 ++++++++++++++++++-samples/minimal/main.cpp | 107 ++++++++++++++++++++++++++--samples/minimal/rules/motion.cpp | 37 ++++++++++samples/minimal/rules/motion.h | 53 ++++++++++++++samples/minimal/states/hello_state.cpp | 59 ++++-----------samples/minimal/states/hello_state.h | 15 ++--samples/minimal/tests/motion_tests.cpp | 48 +++++++++++++samples/minimal/web/shell.html | 2 +-website/src/walkthrough/CMakePresets.json | 47 +++++++++++-website/src/walkthrough/README.md | 84 ++++++++++++++++++++--website/src/walkthrough/ci.yml | 73 +++++++++++++++++++website/src/walkthrough/game-CMakeLists.txt | 105 ++++++++++++++++++++++++++-website/src/walkthrough/release-files.txt | 24 +++++++website/src/walkthrough/root-CMakeLists.txt | 9 ++-15 files changed, 748 insertions(+), 78 deletions(-)None of these is needed to build against the new tag unless CHANGES.md says so. Take the entries you want and leave the rest. Each template file is one of yours:
Template file, in external/labradorYour file website/src/walkthrough/CMakePresets.jsonCMakePresets.jsonwebsite/src/walkthrough/root-CMakeLists.txtCMakeLists.txtwebsite/src/walkthrough/game-CMakeLists.txtgame\CMakeLists.txtwebsite/src/walkthrough/gitignore.txt.gitignorewebsite/src/walkthrough/ci.yml.github\workflows\ci.yml, which a starter project has, and another project if it took it from Check your game in CIsamples/minimal/...game\..., but with#include "game/...where the template has#include "samples/minimal/...The folder’s
README.mdandrelease-files.txtare not copied into a project: the first describes the folder, and the second lists what a release build installs.To take one file’s change, here
CMakePresets.json, which atv0.2.0gained test presets and the browser build’s presets, first find out whether you ever changed your copy, by comparing it with the template at your old tag:Terminal window git -C external/labrador show v0.1.0:website/src/walkthrough/CMakePresets.json > "%TEMP%\template-old.txt"fc CMakePresets.json "%TEMP%\template-old.txt"Output Comparing files CMakePresets.json and C:\USERS\YOU\APPDATA\LOCAL\TEMP\TEMPLATE-OLD.TXTFC: no differences encounteredwith your own user name in the path. No differences means your file is still the template’s, so the new template’s can replace it:
Terminal window git -C external/labrador show v0.2.0:website/src/walkthrough/CMakePresets.json > "%TEMP%\template-new.txt"copy /y "%TEMP%\template-new.txt" CMakePresets.jsoncopyprints1 file(s) copied.If the firstfclisted differences instead, those are your own changes, and replacing the file would lose them. See what the release changed, and make the same edits in your file with Notepad:Terminal window fc "%TEMP%\template-old.txt" "%TEMP%\template-new.txt"Move a starter project to a newer Labrador shows how to read
fc’s output. A source file ingamealways differs from the template in its#includelines; compare the template’s two versions, as in this last box, and make the change it shows. Large entries, such as Tests, from the start atv0.2.0, touch many files; leave one you cannot follow, since nothing needs it. -
Check out the new tag.
Terminal window git -C external/labrador checkout v0.2.0Output Previous HEAD position was c369e8b Version releases now, and say how a public name leavesHEAD is now at 1e60fb2 Prepare v0.2.0The engine folder now holds the new release.
git statusshowsmodified: external/labrador (new commits), with any file you changed in steps 3 and 4, until step 7 records them.If it says
error: Your local changes to the following files would be overwritten by checkout:, with a file name,Please commit your changes or stash them before you switch branches.andAborting, a file inside the engine was changed, and nothing was checked out. The engine is not yours to edit; this puts it back as your pin has it, and then the checkout works:Terminal window git -C external/labrador restore . -
Configure, build and run your tests.
Terminal window cmake --preset x64-debugcmake --build --preset x64-debugctest --preset x64-debugConfigure installs whatever a changed baseline or a new dependency needs, and ends
-- Build files have been written to:and your build folder. The build compiles the engine again, 55 steps fromv0.1.0tov0.2.0, which took 5 seconds on a fast desktop, and endsLinking CXX executable game\MyGame.exe. Then run the game and check it:Terminal window out\build\x64-debug\game\MyGame.exeIts window opens with your game as it was before the move; the template’s says
Hello from the engine.. Try what your game does, then quit as it quits: the template’s asksReally quit?on Escape, and Enter answers yes and closes the window, which gives you the prompt back.A project started before
v0.2.0has no tests. Without test presets,ctest --presetstops withCMake Error: No such test preset in C:/dev/mygame: "x64-debug"; with the presets of step 4 and still no tests, it printsNo tests were found!!!. Neither is a failure of the move. Add tests with the template list’s Tests, from the start entry, or Add a rule and a test.The build applies the engine’s compiler settings to your code as well,
/W4 /WXamong them, so a warning a newer engine header causes in your code stops it, as any other warning would. When the build fails:- Find the first error, as Read a build error shows. An
error naming something CHANGES.md renamed or removed, such as
'mattmath': is not a class or namespace name, is a source break: Update your code for a newer Labrador has the edits. - An error you cannot trace to an entry, or an engine file that fails: go back, as below, and report it in Labrador’s issues with the two tags and the first error.
Keep the settings, which come from
labrador_settingsand are the same walls the engine’s own code builds behind. Buildx64-releasetoo if you ship it. - Find the first error, as Read a build error shows. An
error naming something CHANGES.md renamed or removed, such as
-
Commit the pin, with whatever you changed to match it:
Terminal window git add external/labrador CMakePresets.jsongit commit -m "Move Labrador to v0.2.0"Name every file you changed in steps 3, 4 and 6 after
git add, or usegit add .to take them all.git addmay printwarning: in the working copy of 'CMakePresets.json', LF will be replaced by CRLF the next time Git touches it: a file written bygit show, as in step 4, has the line ends Git stores, and the warning says only that Git will write it back the Windows way. It is harmless.git commitprints:Output [main 27ed059] Move Labrador to v0.2.02 files changed, 47 insertions(+), 2 deletions(-)git submodule statusthen names the new release in brackets, andgit statussaysnothing to commit, working tree clean. If your project is on GitHub,git statusalso saysYour branch is ahead of 'origin/main' by 1 commit.until you send it there withgit push, and then GitHub’s CI builds the new pin.
Go back to your old pin
Section titled “Go back to your old pin”Before step 7, nothing is recorded. Check out your old tag again, put back the files you changed in steps 3 and 4, and configure and build:
git -C external/labrador checkout v0.1.0git restore CMakePresets.jsoncmake --preset x64-debugcmake --build --preset x64-debugThe checkout prints Previous HEAD position was 1e60fb2 Prepare v0.2.0 and
HEAD is now at c369e8b ..., and git status is clean again. Name every file you changed after
git restore, or git restore . for all of them.
After step 7, take the commit back with a new one, then put the engine folder at the pin it records:
git revert --no-edit HEADgit submodule update[main 6b9049f] Revert "Move Labrador to v0.2.0" Date: Sat Oct 31 07:51:56 2026 +1000 2 files changed, 2 insertions(+), 47 deletions(-)Submodule path 'external/labrador': checked out 'c369e8b9dde6f17502029955d11e97dc6d1da376'The Date: line, with your date and time, may be there or not; either is fine. Between the two
lines, git status shows modified: external/labrador (new commits):
git revert puts back what the commit records, but leaves the engine folder as it is until
git submodule update checks out the recorded commit. Then configure and build as above. If the
pin commit is not the newest, use its short name from git log --oneline in place of HEAD.
Take back a commit says more about git revert.
A teammate takes the new pin
Section titled “A teammate takes the new pin”Someone who already has your project, you included on another machine, takes the commit and then the engine it names:
git pullgit submodule update --init --recursiveFrom https://github.com/you/mygame 1646a04..27ed059 main -> origin/mainUpdating 1646a04..27ed059Fast-forward CMakePresets.json | 47 ++++++++++++++++++++++++++++++++++++++++++++++- external/labrador | 2 +- 2 files changed, 47 insertions(+), 2 deletions(-)Submodule path 'external/labrador': checked out '1e60fb26c4fdfcd1582c35c6862d8a06cc4c9b09'The first line names the repository the commit came from, with your own user name and
repository’s name in place of you/mygame; the second says your copy of main moved from the
old commit to the new one. git pull alone moves the record but not the engine folder, so git status shows
(new commits) until the second line runs. --init also downloads the engine on a clone made
without --recurse-submodules, whose external\labrador is an empty folder and whose
git submodule status line starts with -; there it prints
Submodule 'external/labrador' (https://github.com/matt439/Labrador.git) registered for path 'external/labrador'
and Cloning into first. A new clone gets everything at once with
git clone --recurse-submodules and the repository’s address.
The reference at your pin
Section titled “The reference at your pin”This site’s API reference is generated
from the headers at the revision named at the foot of each page. When your pin is older, the
headers under external/labrador/engine are the reference for the engine you build. Their
comments are the same text the reference publishes.
The compiler
Section titled “The compiler”The newest compiler known to build Labrador is MSVC 19.51 (Visual Studio 2026, toolset 14.51):
19.51.36260 on GitHub’s windows-latest runner and 19.51.36256 on the owner’s machine, on
2026-10-25. Labrador’s CI does not pin a compiler. It builds on whatever windows-latest has,
so a new MSVC reaches the engine’s checks when the runner image takes it. A newer compiler can
warn about something an older one did not, and under warnings as errors that stops the build.
If it is the engine’s own code that stops, report it in
Labrador’s issues, and stay on your current compiler until a
release fixes it.
Run the engine’s own tests at your pin
Section titled “Run the engine’s own tests at your pin”Your build does not build Labrador’s tests: they are left out when the engine is not the top-level project. To check that the engine at your pin passes its own tests on your machine, configure the submodule as a project of its own:
cd external\labradorcmake --preset x64-debugcmake --build --preset x64-debugctest --preset x64-debugcd ..\..It builds into external\labrador\out\build\x64-debug, apart from your project’s out folder,
and reads the engine’s own vcpkg.json there, so it does not touch your build. The engine
ignores its out folder, so the submodule stays clean in git status. It builds every test,
benchmark and sample, which takes several minutes and needs the same prompt and fxc your
build does. Every entry should pass.
What has been checked
Section titled “What has been checked”The procedure was first followed, as written then, on 2026-10-26: a project made by Start your
own project at v0.1.0 was moved to v0.2.0. Its build had no warnings, and the engine’s own
tests at the pin passed all twenty entries with the project’s git status and the submodule’s
both clean afterwards. That walk found the missing test presets step 6 mentions.
On 2026-10-31 the page as it is now was run, with Git for Windows 2.52.0, on a project made at
v0.1.0 by that release’s own assemble.py and put in Git with the engine as a submodule from
GitHub by Put your project in Git, at
C:\dev\g11-author\pin\mygame. Every box ran in a command prompt and the output quoted is from
it. Step 1’s fetch found nothing new, and printed the [new tag] line, after From https://github.com/matt439/Labrador, once the local v0.2.0 tag had been deleted; the
v0.2.0-214-g47be5a3 form is what describe printed for a submodule at master before its
checkout. Step 3’s diff showed only version-string. Step
4’s first fc found no differences and the new presets were copied in; the fc of the two
templates listed two pairs of blocks, the browser presets and the test presets. Step 5’s refusal was
made by adding a line to the engine’s CHANGES.md, and restore cleared it. Step 6’s configure
ended as quoted, the build ran 55 steps in about 5 seconds, and ctest printed both messages,
before and after the presets; the game, a v0.1.0 template with no --smoke-test, was started
and then stopped by its process number. Its configure that day took 1,162 seconds, sitting at vcpkg’s Detecting compiler hash
line while another project on the machine ran Visual Studio’s vcpkg too; why it waited was not
found. Going back before the commit, the commit, going
back after it with git revert and git submodule update, and the teammate’s git pull and
git submodule update --init --recursive, in clones of a local bare repository standing in for
GitHub, gave the output quoted; after going back, the project configured in 3 seconds and built
53 steps at v0.1.0. fatal: invalid object name was made with v0.2, and the fetch’s Could not resolve host by
fetching from github.con. These
commands ran with output to a file, where Git does not use the pager; the pager was seen in a
console window in the review below.
A second person then followed the page as worded on their own v0.1.0 project, and steps 1 to 7,
the refusal, No tests were found!!!, going back before and after the commit and the teammate’s
two commands gave the output quoted, hashes included. They found four things, since corrected:
step 6 said to run the game without a command; git add in step 7 printed the LF will be replaced warning for CMakePresets.json; git revert printed a Date: line the box had left
out; and git pull printed two lines before Updating. These were run again the same day on a
third v0.1.0 project, made by v0.1.0’s assemble.py and put in Git as before, at
C:\dev\g11-fixer\pin\mygame, with a local bare repository standing in for GitHub and a clone of
it standing in for the teammate: step 6’s configure took 3 seconds and the build 55 steps; the
game opened its window with Hello from the engine., Escape showed Really quit? and
Enter closed it with exit code 0; git add printed the warning quoted; git revert printed
the Date: line; and the teammate’s git pull printed From and the folder of the stand-in
repository, then the main -> origin/main line, then what is quoted. The From line in the box
has a GitHub address in place of that folder: GitHub itself was not used.
A review the same day ran steps 2 to 5’s commands against the tags in a clone of Labrador and got
the output quoted. It added ### to step 2’s findstr, which had listed none of the entries
of a release after v0.2.0, since those are headed ###; for v0.2.0 that adds only the
Backfill line quoted. It also added ci.yml, which the --stat lists, to step 4’s table. In a
console window, a git log --oneline longer than the window stopped with : on its bottom line,
and q gave the prompt back with the lines shown still on screen.
Documentation for Labrador v0.3.0. Built from Labrador 0f4f503 of 2026-11-03.