Start explanations on "compiler concepts"

[mgorny]

PR Checklist:

• note any issues closed by this PR with closing keywords
• if you are adding a new page under docs/ or community/, you have added it to the sidebar in the corresponding _sidebar.json file
• put any other relevant information below

Fixes Quansight-Labs/conda-ecosystem-sta-mgmt#67

Per @jaimergp 's suggestions.

[netlify]

✅ Deploy Preview for conda-forge-previews ready!

Name	Link
🔨 Latest commit	444802f
🔍 Latest deploy log	https://app.netlify.com/projects/conda-forge-previews/deploys/6977c443ff960b0008ff9de5
😎 Deploy Preview	https://deploy-preview-2701--conda-forge-previews.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 64 Accessibility: 96 Best Practices: 100 SEO: 89 PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[h-vetinari]

This is an amazing start, thanks a lot @mgorny!

I left one big comment about (potentially) increasing the scope here a tad, especially around the existence/role of symbols. I'd also like to explain the sysroot a bit more. It's fine to leave some of that to other PRs, this one's already pretty hefty, but feel free to keep going.

For the environment stuff (+cross-compilation) I have a certain pedagogy in mind, if you want I can prepare a draft of that based on what you wrote up here. I'd like to split that out though

[h-vetinari]

I'd kinda prefer to make a distinction between "Build system generators" / "Build orchestrators" / "Build management tools" (CMake etc.) and "Build systems" / "Build executors" (ninja etc.).
Open to other naming suggestions, as long as we can somehow keep them separate (perhaps with an admission that CMake etc. are often called build systems when that distinction is irrelevant).

[mgorny]

Yeah, it's a complex topic. That said, I'd avoid uncommon terms like "orchestrators"; if only because this would mean we're inventing new nomenclature (never heard anyone talking about "build orchestrator".

Overall, I've tried to bunch them all together because there are many different ways in which people use them: a Makefile can either be a simple output of a "generator", or a full-fledged build system with lots of GNU extensions to make it work. Also, at least cmake and meson seem to be aiming towards hiding the underlying builder as an implementation detail: cmake --build, meson compile).

[mgorny]

I see that CMake and Meson both call themselves a "build system". GNU makes describes itself as a "tool which controls the generation of executables and other non-source files of a program from the program's source files." Wikipedia seems to arbitrarily talk of "software development tools", "build automation tools".

[h-vetinari]

Let's turn this into a short section

Suggested change

	Projects usually adapt one of the existing build systems, such as GNU autotools, CMake or Meson.
	These build systems in turn generate Makefiles, Ninja build scripts or project files for IDEs to use
	and perform the actual build.
	## Build executor
	The build orchestrator usually does not execute the actual commands itself, but calls a dedicated
	build executor such Ninja, make, etc. Orchestrators may support generating instructions for several
	build executors, or different executors per platform. Projects often have a preferred executor.
	In almost all cases, build orchestrator and build orchestrator can be considered as if they were
	acting as a single unit.

[mgorny]

For the environment stuff (+cross-compilation) I have a certain pedagogy in mind, if you want I can prepare a draft of that based on what you wrote up here. I'd like to split that out though

Note that there's also https://conda-forge.org/docs/maintainer/understanding_conda_forge/cross-compilation/ with some overlap.

[jaimergp]

Such a great read, @mgorny! Thanks for the write up. I left some comments as a non-expert who has only had limited contact with this contact through (intuition-driven at best) practice. 🙏

[mgorny]

I've tried to add a bit of explanation of interface/implementation and API/ABI split. I have consulted the pypackaging docs, but tried to keep things much shorter and simpler.

[mgorny]

Okay, I think this is ready for another review. I've tried to cover most of your suggestions, while keeping it reasonably focused. Still a bit on the edge over talking a bit more about the filesystem hierarchy. I've also managed to integrate the Python part while keeping it reasonably generic and treating various aspects of Python as examples of arch-dep/indep and ABI. I've also removed the bits considered out of scope.

[h-vetinari]

I think this PR is excellent work, and it would likely be more helpful to just get it merged as a baseline, and continue any remaining points in follow-ups.

Thank you very much @mgorny!