Skip to content

#319/carla 0.9.16 windows build guide and doc build cleanup - #320

Open
yunlishao-vibe wants to merge 1 commit into
dev_v0.9.0from
docs/carla_0916_build_guide
Open

#319/carla 0.9.16 windows build guide and doc build cleanup#320
yunlishao-vibe wants to merge 1 commit into
dev_v0.9.0from
docs/carla_0916_build_guide

Conversation

@yunlishao-vibe

Copy link
Copy Markdown
Contributor

Summary

The CARLA 0.9.16 Windows build guide

doc/Carla_0916_Windows_building.md, written from a build actually carried out at tag
0.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 passed
it through a variable), so the compiler changes and most of the 0.9.15 workarounds stop
applying. The guide covers:

  • the five patches the tree needs to build at all — a trailing-backslash quote escape that
    silently breaks cd in 7 installer scripts, a bootstrap.bat vc141 call against a
    msvc-14.3 default, python -m build's isolated venv, and an MSVC ICE plus a COFF
    section-limit overflow on boost 1.84;
  • two Windows shell traps — driving the build from Git Bash breaks vcvars64.bat, and
    launching from PowerShell breaks bootstrap.bat via an inherited environment variable;
  • that make setup and make PythonAPI exit 0 while having failed, so artifacts must
    be checked rather than return codes.

It also documents that make package does not work — UE 4.26's AutomationTool crashes
(0xC0000005) under the VS2022 toolchain 0.9.16 requires — and that the way around it is
to launch through the engine's UE4Editor.exe, the way CARLA itself does
(BuildCarlaUE4.bat:205), which loads uncooked content. That path is verified: 25 NPCs
spawned 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.

  • Removed doc/Carla_0915_Windows_Fixes.md. It is a 1.5 KB PDF with a .md
    extension whose entire content is the string "Placeholder for Carla 0915 Windows
    Fixes"
    . Sphinx reads it as source and emits undecodable-character warnings on it.
  • Filled in doc/index.rst. Eight documents existed in the tree but appeared in no
    toctree, 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.
  • Renamed FIXS_message flow.mdFIXS_message_flow.md — a space in a Sphinx
    docname is fragile. Nothing referenced the old name.
  • Fixed seven URL-encoded image paths in CarMakerDoc.md (img%2Fimg/) that left
    those images broken in the rendered docs.
  • Cross-linked the 0.9.15 guide, the 0.9.16 guide and CARLAdoc.md so a reader lands
    on the right one, and corrected Util/InstallerWinUtil/InstallersWin.

Sphinx warnings 51 → 31, orphans 8 → 0.

One thing worth knowing

Building the docs on Windows segfaults, part-way through writing output... and
sometimes surfacing first as a nonsense TypeError from inside Sphinx or markdown-it. It
is 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 is
written up in ContributionGuide.md so 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

  • Python version: 3.10.11 (CARLA build), 3.10.11 + Sphinx 7.4.7 (docs)
  • CARLA: 0.9.16 (tag), Unreal Engine 4.26 CARLA fork, Visual Studio 2022 / MSVC 14.43

Checklist

  • Code compiles/runs as expected — docs build clean; the 0.9.16 build and server launch are the subject of the guide and were both carried out
  • Tests pass locally — Sphinx build succeeds, 0 orphans
  • Documentation is updated (if applicable)
  • Issue linked above

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant