Merge pull request #2091 from jaimergp/microarchitectures

Document microarchitecture-optimized builds

docs/glossary.md

@@ -78,3 +78,7 @@ An environment is a tool that helps to keep dependencies required by different p
 ## Recipe
 
 A recipe is a collection of files required to build a conda package. This includes, at minimum, a [`meta.yaml`](maintainer/adding_pkgs.md#the-recipe-meta-yaml) file, but can also include license files, patches, build scripts, test scripts etc. [Learn More](https://docs.conda.io/projects/conda-build/en/stable/resources/define-metadata.html).
+
+## Virtual package
+
+Virtual packages are not real packages that can be downloaded. They are injected by the conda clients at runtime so the solver can consider that metadata as part of the constraints of the problem. By convention, they always start with a double underscore (`__`). Some examples include the type of operating system (Linux, Windows, macOS), or the CUDA version supported by the system (if any). [Learn More](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-virtual.html).

docs/maintainer/knowledge_base.md

@@ -1271,6 +1271,40 @@ which has `openblas` as a dependency and has a symlink from `libblas.so.3` to `l
 BLAS `3.8.0` API.  This means that, at install time, the user can select what BLAS implementation
 they like without any knowledge of the version of the BLAS implementation needed.
 
+### Microarchitecture-optimized builds {#microarch}
+
+conda [virtual packages](../glossary.md#virtual-package) include `__archspec`, which expose the processor architecture to the solver. However, `__archspec` should not be used directly in recipes; instead, users should rely on the [`microarch-level`](https://github.com/conda-forge/microarch-level-feedstock) helper packages (contributed in [staged-recipes#24306](https://github.com/conda-forge/staged-recipes/pull/24306)).
+
+Before learning how to use it, please read these considerations:
+
+- Adding microarchitecture variants can result in too many entries in the build matrix. Do not overuse it.
+- These optimized builds should only be used when the performance improvements are significant.
+- Preferrably, the project should rely on runtime dispatch for arch-specific optimizations.
+- If the package is already too large, consider using smaller outputs for the arch-optimized variants.
+
+To implement microarchitecture-optimized builds in your feedstock, you'll end up with something like:
+
+```yaml title="recipe/conda_build_config.yaml"
+microarch_level:  # [unix and x86_64]
+  - 1  # [unix and x86_64]
+  - 3  # [unix and x86_64]
+  - 4  # [unix and x86_64]
+```
+
+```yaml title="recipe/meta.yaml"
+# ...
+requirements:
+  build:
+    - x86_64-microarch-level {{ microarch_level }}  # [unix and x86_64]
+    - {{ compiler('c') }}
+    # ...
+# ...
+```
+
+That's it. Note that the activation scripts behind the `microarch-level` packages are already injecting the necessary compiler flags for you. Since they also have `run_exports` entries, your
+package will have the necessary runtime requirements to ensure the most adequate variant gets installed. Refer to [this comment](https://github.com/conda-forge/staged-recipes/pull/24306#issuecomment-1800095471) for more information.
+
+
 <a id="knowledge-mpl"></a>
 
 <a id="matplotlib"></a>