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).

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]>

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

✅ Deploy Preview for conda-forge-previews ready!

Name	Link
🔨 Latest commit	`d287915`
🔍 Latest deploy log	https://app.netlify.com/projects/conda-forge-previews/deploys/68f13409b59b34000814d2e1
😎 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: 78 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

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

h-vetinari

Thanks for working on this

docs/maintainer/infrastructure.md

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

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

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

@isuruf

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

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

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!

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

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]>

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

mgorny added 3 commits September 12, 2025 19:05

Compilers and Runtimes: start splitting into sections

9358a47

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

27e2ec6

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

Actually rewrite some of the text to fit better

a0d4605

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

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

Fix 404s

b70572e

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

mgorny added 2 commits September 25, 2025 18:40

Partially address the review comments

4948223

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

Include stdlib('m2w64_c')

b96c1e2

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

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

mgorny and others added 2 commits September 26, 2025 09:57

Apply suggestions from code review

52d94f3

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

Address further remarks, fix syntax

e08948e

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

isuruf reviewed Sep 26, 2025

View reviewed changes

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

Replace the MinGW note with a ABI incompat. warning

1a07b50

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

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

mgorny added 3 commits September 30, 2025 14:15

Use regular typesetting for programming language names

5880221

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

Mention that compilers are always build dependencies

5ab795f

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

Replace outdated docs in KB with a reference to infra doc

c393929

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

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 added 2 commits October 2, 2025 20:44

Capitalization and a typo

d45846f

One more

2b5833c

jaimergp approved these changes Oct 2, 2025

View reviewed changes

Apply suggestions from code review

8859350

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

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

Open

5 tasks

Clarify CBC / compiler macro usage

d287915

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

Uh oh!

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

Are you sure you want to change the base?

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

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