Sources and corrections

This page exists because documentation is only useful if you can check it. Every technical claim on this site traces to something listed here. Where we could not verify something, it appears below as an open question rather than quietly on a page as though it were settled.

How this site is written

Three rules, and they are not aspirational; the build fails if the last one is broken:

• Nothing appears on a page that is not sourced here. Claims about tools, build stages, data formats and requirements come from the repository or the FlightGear wiki, with the date they were checked.
• Nothing is invented. No build time, command invocation or error message appears unless it was produced by a build someone actually ran. The figures and command lines on this site come from the one recorded below; where a claim is still unverified, the page says so instead of guessing.
• Every image is output. The site began with eleven labelled placeholder slots; none survive, and the build now fails if one reappears. Each picture on this site was produced by a run described below; the terrain renders, the mesh diagram, the land-cover decode.

Where the facts come from

Where the project’s own documentation disagrees with itself

Nine places where the repository, the README and the wiki give different answers, four of which were settled by building the tools. The full list, with what to do about each, is on TerraGear and the alternatives; it lives there rather than here because knowing which tool to use is the question that sends people looking.

The short version: the build system, the version control, whether a GUI exists, which toolchain to use, the airport tool’s name, an ogr-decode rename that never happened, dead data-source links, a how-to dated 1999, and three different answers to where the source lives.

Open questions for the TerraGear team

There were eight. Building the tools settled four of them. The land-cover build then opened a fifth, which is the usual direction of travel: answering a question about a toolchain tends to produce a better one. These five are what a build cannot answer, because they are decisions rather than facts.

1. Which branch should a newcomer build? next is the only actively developed one, but the wiki still says scenery/ws2.0, which has not moved since April 2023. One of the two should change.
2. Is the repository README still considered current? It documents an autogen.sh build that the tree does not contain, and README.SimGear is dated 2001.
3. Should there be tagged releases? A tag a guide can name would keep documentation correct as the branch moves.
4. Should the GitHub mirror be archived or updated? Its April 2022 date is the first thing most searchers see, and it reads as an abandoned project.
5. Which land-cover sources does the project recommend? OpenStreetMap and Natural Earth both work; the open question is which the project considers canonical for published scenery, and with what mapping from source classes to TerraGear area types.

Four things found across the two builds are worth reporting upstream rather than only recording here: the <chrono> regression on next, the gzip hang in genapts, the chop.idx race; all three described in Common errors and fixes; and the tile row tg-construct builds outside the requested box, which is on the second-region page. The fourth is a performance finding rather than a defect, and may turn out to be deliberate.

Keeping this current

Most of what is below describes a moving target: a branch that compiles today may not next month. Upstream watch carries dated reports on the repository’s state, so any claim here can be checked against when it was last true.

The build these numbers come from

On 23 August 2026 the toolchain was built from source and run end to end on one 1°×1° square (N37W123, San Francisco Bay) producing 44 scenery files. Every timing, memory figure, file count and command line in the guides comes from that run.

Three defects were found and are reported as observed, with the exact output each one produced: TerraGear’s next branch has not compiled since 2026-06-18 because a commit removed an #include that is still needed; genapts loops forever on a gzipped apt.dat despite advertising support for one; and genapts corrupts a shared index file when run with more than about four threads, exiting 139 and leaving a partial set of airports behind. Details are in Common errors and fixes and Hardware and build times.

Corrected by the second build

Building a second square found one thing this site had wrong and one it had emphasised wrongly. Both are now fixed on the pages that carried them:

• “genapts scans all 34,074 airports, and that fixed cost is why --airport= exists.” The scan is real; the cost is not. A bounding box containing no airport at all completes in 0.55 s, and that is the whole read of 106 MB. The 19.7 seconds on the first square were the 31 airports in it. --airport= is worth using because building airports is expensive. Corrected on genapts, apt.dat and build times.
• “243 of the 286 seconds went on tiles outside the square.” Withdrawn: it was mine and it was wrong. The timings came from gaps between consecutive lines in a build log written by ten threads, where the gap measures the wait for another thread rather than the cost of a tile. Patching the tiles away changed the wall clock from 286 s to 291 s. The tiles are real and are still worth removing; the cost was not.

Two attempts to work around the second one both failed and are written up as failures on the second-region page, because a fix that does not work is worth more written down than quietly dropped.

What is not verified

Stated plainly so nothing here is mistaken for fact:

• One machine, three squares. The timings are measurements, not benchmarks, and different hardware will move them. San Francisco, then N49E007 in Rheinland-Pfalz, then S23E017 in Namibia: chosen to disagree with each other as much as one machine allows. What travelled and what did not. Three points are still not a curve.
• Land cover has been decoded on three squares, from OpenStreetMap and Natural Earth, using ten area types on the first and fourteen on the others. The third is desert with almost nothing mapped in it, which showed the mapping fails safely rather than wrongly, but a place needing area types none of the three needed, rice paddy or mangrove or irrigated desert, is still untested.
• Structure, not semantics. The output was walked against SimGear’s own reader and every file parses cleanly (how, and what that does and does not prove). That says the files are well-formed, not that the terrain inside them is correct.
• One version of FlightGear, one viewpoint. The output was loaded and rendered in FlightGear 2020.3.16 (Debian’s package) on software OpenGL, and it draws correctly: with a control render on empty scenery to show what the tools contributed. It has not been tried on a newer FlightGear, on real hardware, or from any position other than over KSFO.
• No native Windows or macOS build has been confirmed, and this site has not attempted one. What is confirmed is the container route, because it is the one everything here was produced with: what it needs and what it costs.

Corrections

Corrections are welcome, especially where this site is the one that has it wrong. Corrections and additions belong on the project issue tracker, and anything that changes a page will be reflected here with a new checked date.