docs(infrastructure/compilers): Refactor and reword to improve clarity #2596

mgorny · 2025-09-15T14:01:57Z

PR Checklist:

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

This is an attempt to improve structure of the compiler section in the infrastructure page. Currently it consists of a single long block of text with a tiny subsection at the end, with different concepts being mixed together and different audiences being addressed somewhat simultaneously.

What I've done here is:

Split it into multiple subsections focused on a single topic each.
Let every section focus on a particular audience: feedstock maintainers, users, advanced users, compiler feedstock maintainers.
Include more specific examples.
Document {{ stdlib('c') }} macro.
Split the list of compilers/platforms (which is useful for the more general audience) from the low-level technical details of compiler feedstocks.
Added a few missing bits here and there.
Cross-linked with other bits of documentation.

This is done from the perspective of someone who's relatively new to conda-forge, but not to the more general topic of packaging and compilers, so it's possible I'm missing something (from both perspectives).

netlify · 2025-09-15T14:02:04Z

✅ Deploy Preview for conda-forge-previews ready!

Name	Link
🔨 Latest commit	`12d5133`
🔍 Latest deploy log	https://app.netlify.com/projects/conda-forge-previews/deploys/68f91ef3aa11050008ba9b6f
😎 Deploy Preview	https://deploy-preview-2596--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: 61 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.

jaimergp

Some comments for now! The split is definitely an improvement. In further passes I'd like to start splitting this page a bit further.

Also pinging @h-vetinari and @isuruf for additional comments, if there are any.

Thanks!

docs/maintainer/infrastructure.md

h-vetinari

Thanks for working on this

docs/maintainer/infrastructure.md

mgorny · 2025-09-26T13:50:00Z

Okay, I think I've addressed all the remarks, but you'll probably have some ideas how to improve the wording :-).

docs/maintainer/infrastructure.md

jaimergp · 2025-10-02T18:38:33Z

docs/maintainer/infrastructure.md

+Alternatively, the specific compiler name can be used as an argument to
+the `{{ compiler(...) }}` macro, e.g.:
+
+```yaml
+requirements:
+  build:
+    - {{ compiler('clang') }}
+    - {{ stdlib('c') }}
+```


TIL! Nice. Is this officially supported or more like a nice byproduct of how compiler() works (by adding the _{build_platform} subdir)?

nvm, found my answer in #2596 (comment)

It's supported. If clang_compiler is set in cbc, it's used. Otherwise clang is used.

nvm, found my answer in #2596 (comment)

I cannot find the source of that statement in that thread. If you're basing this on my comment about clang vs. clang-cl, then I was talking about the values of c_compiler: in CBC, not the keys used in the compiler() macro.

TBH, I think {{ compiler('clang') }} is highly confusing and we should not be supporting it at all in official docs. It works by accident because of the way that {{ compiler("foo") }} will work if you set foo_compiler: in CBC and the package-name constructed with <value_of_foo_compiler>_{{ target_platform }} happens to be legit.

It works by accident because of the way that

Actually, it's even worse than that. If you use {{ compiler("foo") }} and there's no foo_compiler: in CBC, conda-build will just construct foo_{{ target_platform }}, which is completely different from the way the compiler() macro usually works. Yes, it's long-standing behaviour, but it's confusing as heck, and we should not encourage it IMO.

If people want a way to select the "official" compilers directly, then that's an OK solution for me. That way we could also do

clang_compiler: - clang # [unix] - clang-cl # [win]

to stay MSVC-compatible on windows by default. (and we might want to use clangxx on unix, so that it's similarly C++ capable, without having to resort to {{ compiler("clangxx") }})

Could you raise a PR to the pinning repo?

Sorry, is "you" me here? And if yes, then are we talking about just clang or more compilers?

I had been addressing Isuru, who was in favour of enabling {{ compiler("gcc") }} and {{ compiler("clang") }}, and probably has opinions on whether we should default to clang or clang-cl on windows, and whether we should just use the C++ variant for both.

But if you, @mgorny, want to help unblock this, I suggest to open a PR to the pinning repo with the following

# enable `{{ compiler("gcc") }}` / `{{ compiler("clang") }}`; make them C++-capable by default gcc_compiler: - gxx clang_compiler: - clangxx # [unix] # stay compatible with MSVC - clang-cl # [win]

Hopefully @isuruf will have time to provide feedback in that PR directly

conda-forge/conda-forge-pinning-feedstock#7849

I've also applied the suggestions I've proposed above. I'll add compiler('clang') usage once/if the pinning PR is merged.

docs/maintainer/infrastructure.md

jaimergp · 2025-10-02T18:47:43Z

I'm very very happy with the results. I think most concerns were addressed, but I'll let this simmer a couple days more in case @isuruf or @h-vetinari have something else to say. Thanks for the awesome work, @mgorny!

h-vetinari

I think there was a misunderstanding about what I meant w.r.t. clang-cl.

h-vetinari · 2025-10-03T18:02:53Z

docs/maintainer/infrastructure.md

+Alternatively, the specific compiler name can be used as an argument to
+the `{{ compiler(...) }}` macro, e.g.:
+
+```yaml
+requirements:
+  build:
+    - {{ compiler('clang') }}
+    - {{ stdlib('c') }}
+```


nvm, found my answer in #2596 (comment)

I cannot find the source of that statement in that thread. If you're basing this on my comment about clang vs. clang-cl, then I was talking about the values of c_compiler: in CBC, not the keys used in the compiler() macro.

TBH, I think {{ compiler('clang') }} is highly confusing and we should not be supporting it at all in official docs. It works by accident because of the way that {{ compiler("foo") }} will work if you set foo_compiler: in CBC and the package-name constructed with <value_of_foo_compiler>_{{ target_platform }} happens to be legit.

docs/maintainer/infrastructure.md

Add entries to enable explicit `compiler('clang')` and `compiler('gcc')` macro usage. As discussed in conda-forge/conda-forge.github.io#2596, these currently work incidentally, but could be used as a convenient method of forcing GCC or Clang for a particular package. This involves a slight change in behavior — whereas previously the implicit behavior would only activate a C compiler, it now activates both C and C++ compilers. Furthermore, `compiler('clang')` defaults to using `clang-cl` on Windows, making the behavior more consistent with the MSVC usage in the default compiler set. There is currently one feedstock (conda-forge/python-poppler-feedstock) that uses `compiler('clang')` and will need to be tested with the change. A quick search reveals no uses of `compiler('gcc')`. Signed-off-by: Michał Górny <[email protected]>

For now, introduce a few sections as a proposed structure and move the relevant paragraphs unchanged into them. Signed-off-by: Michał Górny <[email protected]>

Signed-off-by: Michał Górny <[email protected]>

Co-authored-by: h-vetinari <[email protected]>

Signed-off-by: Michał Górny <[email protected]>

@isuruf

As suggested by @isuruf. Signed-off-by: Michał Górny <[email protected]>

Signed-off-by: Michał Górny <[email protected]>

Co-authored-by: jaimergp <[email protected]>

Signed-off-by: Michał Górny <[email protected]>

mgorny · 2025-10-22T18:14:52Z

Okay, I think it's ready for another review. I've added compiler('clang*') bits now.

mgorny · 2025-10-28T16:14:27Z

@h-vetinari, @isuruf, could you take another look?

mgorny · 2025-10-28T17:34:27Z

Thanks!

mgorny requested a review from a team as a code owner September 15, 2025 14:01

jaimergp reviewed Sep 25, 2025

View reviewed changes

jaimergp moved this to In Progress in STA conda & conda-forge Sep 25, 2025

jaimergp added this to STA conda & conda-forge Sep 25, 2025

jaimergp assigned mgorny Sep 25, 2025

isuruf reviewed Sep 25, 2025

View reviewed changes

docs/maintainer/infrastructure.md Show resolved Hide resolved

h-vetinari reviewed Sep 25, 2025

View reviewed changes

docs/maintainer/infrastructure.md Show resolved Hide resolved

docs/maintainer/infrastructure.md Show resolved Hide resolved

docs/maintainer/infrastructure.md Outdated Show resolved Hide resolved

docs/maintainer/infrastructure.md Show resolved Hide resolved

isuruf reviewed Sep 26, 2025

View reviewed changes

docs/maintainer/infrastructure.md Outdated Show resolved Hide resolved

mgorny requested review from h-vetinari, isuruf and jaimergp September 29, 2025 17:29

jaimergp reviewed Oct 2, 2025

View reviewed changes

docs/maintainer/infrastructure.md Outdated Show resolved Hide resolved

jaimergp reviewed Oct 2, 2025

View reviewed changes

docs/maintainer/infrastructure.md Outdated Show resolved Hide resolved

jaimergp reviewed Oct 2, 2025

View reviewed changes

docs/maintainer/infrastructure.md Outdated Show resolved Hide resolved

jaimergp reviewed Oct 2, 2025

View reviewed changes

docs/maintainer/infrastructure.md Outdated Show resolved Hide resolved

jaimergp reviewed Oct 2, 2025

View reviewed changes

docs/maintainer/infrastructure.md Outdated Show resolved Hide resolved

jaimergp approved these changes Oct 2, 2025

View reviewed changes

h-vetinari requested changes Oct 3, 2025

View reviewed changes

mgorny mentioned this pull request Oct 16, 2025

Add clang_compiler and gcc_compiler convenience entries conda-forge/conda-forge-pinning-feedstock#7849

Merged

5 tasks

mgorny force-pushed the compiler-refactor branch from d287915 to fb0c6fc Compare October 17, 2025 11:53

jaimergp mentioned this pull request Oct 17, 2025

Status Report (2025-10-17) Quansight-Labs/conda-ecosystem-sta-mgmt#45

Open

mgorny force-pushed the compiler-refactor branch from 22f04fc to 3e0ef39 Compare October 21, 2025 13:48

mgorny added 3 commits October 22, 2025 20:13

Compilers and Runtimes: start splitting into sections

f9eb2ff

For now, introduce a few sections as a proposed structure and move the relevant paragraphs unchanged into them. Signed-off-by: Michał Górny <[email protected]>

Start rewriting the parts on using compilers

6d7a555

Signed-off-by: Michał Górny <[email protected]>

Actually rewrite some of the text to fit better

1994b20

Signed-off-by: Michał Górny <[email protected]>

jaimergp and others added 15 commits October 22, 2025 20:13

Fix 404s

9d0ca5e

Partially address the review comments

fd2b868

Signed-off-by: Michał Górny <[email protected]>

Include stdlib('m2w64_c')

c74928a

Signed-off-by: Michał Górny <[email protected]>

Apply suggestions from code review

1e986a5

Co-authored-by: h-vetinari <[email protected]>

Address further remarks, fix syntax

401c11d

Signed-off-by: Michał Górny <[email protected]>

Replace the MinGW note with a ABI incompat. warning

1401a86

As suggested by @isuruf. Signed-off-by: Michał Górny <[email protected]>

Use regular typesetting for programming language names

d9b2a9f

Signed-off-by: Michał Górny <[email protected]>

Mention that compilers are always build dependencies

8001a1b

Signed-off-by: Michał Górny <[email protected]>

Replace outdated docs in KB with a reference to infra doc

41b6886

Signed-off-by: Michał Górny <[email protected]>

Capitalization and a typo

803c3f6

One more

149926e

Apply suggestions from code review

0a2e185

Co-authored-by: jaimergp <[email protected]>

Clarify CBC / compiler macro usage

1efb76d

Signed-off-by: Michał Górny <[email protected]>

Add more info on MinGW compilers

14a771a

Signed-off-by: Michał Górny <[email protected]>

Document compiler('clang*')

12d5133

Signed-off-by: Michał Górny <[email protected]>

mgorny force-pushed the compiler-refactor branch from ea56c8a to 12d5133 Compare October 22, 2025 18:14

mgorny mentioned this pull request Oct 24, 2025

Status Report (2025-10-24) Quansight-Labs/conda-ecosystem-sta-mgmt#47

Open

mgorny requested a review from h-vetinari October 28, 2025 16:13

isuruf merged commit d8113d1 into conda-forge:main Oct 28, 2025
6 checks passed

github-project-automation bot moved this from In Progress to Done in STA conda & conda-forge Oct 28, 2025

mgorny deleted the compiler-refactor branch October 28, 2025 17:34

Uh oh!

Uh oh!

docs(infrastructure/compilers): Refactor and reword to improve clarity #2596

docs(infrastructure/compilers): Refactor and reword to improve clarity #2596

Conversation

mgorny commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for conda-forge-previews ready!

Uh oh!

jaimergp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

h-vetinari left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mgorny commented Sep 26, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

h-vetinari Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

h-vetinari Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jaimergp commented Oct 2, 2025

Uh oh!

h-vetinari left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mgorny commented Oct 22, 2025

Uh oh!

mgorny commented Oct 28, 2025

Uh oh!

Uh oh!

mgorny commented Oct 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

mgorny commented Sep 15, 2025 •

edited

Loading

netlify bot commented Sep 15, 2025 •

edited

Loading

h-vetinari Oct 3, 2025 •

edited

Loading

h-vetinari Oct 14, 2025 •

edited

Loading