#319/carla 0.9.16 windows build guide and doc build cleanup - #320
Open
yunlishao-vibe wants to merge 1 commit into
Open
#319/carla 0.9.16 windows build guide and doc build cleanup#320yunlishao-vibe wants to merge 1 commit into
yunlishao-vibe wants to merge 1 commit into
Conversation
Adds doc/Carla_0916_Windows_building.md, written from a build actually carried out at tag 0.9.16. 0.9.16 hardcodes the VS2022 toolset, so most of the 0.9.15 workarounds do not carry over; the guide covers the five patches the tree needs, the two Windows shell traps (Git Bash breaks vcvars, PowerShell breaks bootstrap.bat), and the fact that make setup / make PythonAPI exit 0 while failing. It also documents that `make package` does not work - UE 4.26's AutomationTool crashes under VS2022 - and that the way around it is to launch through the engine's UE4Editor.exe, which loads uncooked content. FIXS still targets 0.9.15; migration is tracked in #319. Doc cleanup, all of it discovered by actually building the docs: - Remove doc/Carla_0915_Windows_Fixes.md. It is a 1.5 KB PDF with a .md extension whose entire content is "Placeholder for Carla 0915 Windows Fixes". Sphinx reads it as source and it produces undecodable-character warnings. - Fill in doc/index.rst. Eight documents were in the tree but in no toctree, so they were unreachable from the navigation and Sphinx warned on every one. Orphan count goes 8 -> 0. Adds a "Building from Source" section and completes the XIL Bench and Development sections. - Rename "FIXS_message flow.md" -> FIXS_message_flow.md; a space in a Sphinx docname is fragile. Nothing referenced the old name. - Fix seven URL-encoded image paths in CarMakerDoc.md (img%2F -> img/) that left the images broken in the rendered docs. - Cross-link the 0.9.15 guide, the 0.9.16 guide and CARLAdoc so a reader lands on the right one, and correct Util/InstallerWin -> Util/InstallersWin. - Document in ContributionGuide.md how to build the docs, including that doing so on Windows segfaults from stack exhaustion and how to work around it. Linux and ReadTheDocs are unaffected. Sphinx warnings drop 51 -> 31 and the build no longer has orphans.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The CARLA 0.9.16 Windows build guide
doc/Carla_0916_Windows_building.md, written from a build actually carried out at tag0.9.16(C:\src_ext\CarlaSrc_0_9_16), not from the upstream docs.The reason it needs its own guide rather than a note on the 0.9.15 one: 0.9.16
hardcodes the VS2022 toolset (
Setup.bat --boost-toolset msvc-14.3, where 0.9.15 passedit through a variable), so the compiler changes and most of the 0.9.15 workarounds stop
applying. The guide covers:
silently breaks
cdin 7 installer scripts, abootstrap.bat vc141call against amsvc-14.3default,python -m build's isolated venv, and an MSVC ICE plus a COFFsection-limit overflow on boost 1.84;
vcvars64.bat, andlaunching from PowerShell breaks
bootstrap.batvia an inherited environment variable;make setupandmake PythonAPIexit 0 while having failed, so artifacts mustbe checked rather than return codes.
It also documents that
make packagedoes not work — UE 4.26's AutomationTool crashes(
0xC0000005) under the VS2022 toolchain 0.9.16 requires — and that the way around it isto launch through the engine's
UE4Editor.exe, the way CARLA itself does(
BuildCarlaUE4.bat:205), which loads uncooked content. That path is verified: 25 NPCsspawned with 24 driving under Traffic Manager, four synchronous client sessions, no errors
in the server log.
FIXS still targets 0.9.15. Nothing here changes what FIXS builds against.
Doc cleanup
All of this came out of actually building the docs, which had not been done in a while.
doc/Carla_0915_Windows_Fixes.md. It is a 1.5 KB PDF with a.mdextension whose entire content is the string "Placeholder for Carla 0915 Windows
Fixes". Sphinx reads it as source and emits undecodable-character warnings on it.
doc/index.rst. Eight documents existed in the tree but appeared in notoctree, so they were unreachable from the navigation and Sphinx warned on every one.
Orphan count 8 → 0. Adds a Building from Source section and completes XIL Bench
and Development.
FIXS_message flow.md→FIXS_message_flow.md— a space in a Sphinxdocname is fragile. Nothing referenced the old name.
CarMakerDoc.md(img%2F→img/) that leftthose images broken in the rendered docs.
CARLAdoc.mdso a reader landson the right one, and corrected
Util/InstallerWin→Util/InstallersWin.Sphinx warnings 51 → 31, orphans 8 → 0.
One thing worth knowing
Building the docs on Windows segfaults, part-way through
writing output...andsometimes surfacing first as a nonsense
TypeErrorfrom inside Sphinx or markdown-it. Itis stack exhaustion, not a bad page: docutils recurses deeply per document and Windows
gives the main thread far less stack than Linux, so past a certain number of written
documents the build no longer fits. Adding documents to the toctree is what tipped it over.
Verified by building on a thread with a 64 MB stack, which succeeds cleanly. ReadTheDocs
builds on
ubuntu-22.04(.readthedocs.yml) and is not affected. The workaround iswritten up in
ContributionGuide.mdso the next person does not have to rediscover it.Residual uncertainty: I could not run a Linux Sphinx build here, so "RTD is unaffected"
rests on the platform stack-size difference plus the fact that the base branch already
builds on Windows at 21 written documents. The RTD build on this PR settles it directly.
Related Issues
Relates to #319 (CARLA 0.9.16 investigation and migration — Backlog). Does not close it;
#319 covers the FIXS migration itself, which this PR deliberately does not touch.
Environment
Checklist