diff --git a/docs/how-to/emergencies/update-a-dependency-in-published-packages.md b/docs/how-to/emergencies/update-a-dependency-in-published-packages.md index c9818ce2d0d..10baf11d71d 100644 --- a/docs/how-to/emergencies/update-a-dependency-in-published-packages.md +++ b/docs/how-to/emergencies/update-a-dependency-in-published-packages.md @@ -19,7 +19,7 @@ packages built will have the correct dependencies. For example, let's assume that we are changing a dependency in `sympy-feedstock` from: -```recipe title="meta.yaml (old)" +```recipe title="The recipe (prior to update)" build: number: 2 # ... @@ -31,7 +31,7 @@ requirements: to: -```recipe title="meta.yaml (new)" +```recipe title="The recipe (updated)" build: number: 3 # ... diff --git a/docs/maintainer/adding_pkgs.mdx b/docs/maintainer/adding_pkgs.mdx index 95812fd8637..101eb3d32bb 100644 --- a/docs/maintainer/adding_pkgs.mdx +++ b/docs/maintainer/adding_pkgs.mdx @@ -551,7 +551,7 @@ requirements: - libawesome 1.1.* ``` -For more information on pinning, please refer to [Pinned dependencies](pinning_deps.md#pinned-deps). +For more information on pinning, please refer to [Pinned dependencies](pinning_deps.mdx). diff --git a/docs/maintainer/guidelines.md b/docs/maintainer/guidelines.md index 193488c340e..7c7bbbd0df3 100644 --- a/docs/maintainer/guidelines.md +++ b/docs/maintainer/guidelines.md @@ -207,7 +207,7 @@ Recommended: 1. Source should be obtained from a URL that provides a stable tarball (same SHA over time). Git or other SVC repositories should only be used as a last resort. -2. Host requirements contained in the [conda-forge pinnings](pinning_deps.md#pinned-deps) should be _name-only_; i.e. they do not specify a separate version. +2. Host requirements contained in the [conda-forge pinnings](pinning_deps.mdx) should be _name-only_; i.e. they do not specify a separate version. 3. Runtime requirements are not pinned too strictly without justification. Thanks to repodata patches, we can afford to be optimistic about lower or upper bounds instead of single-version pins: `>=1.4.2,<1.5` is better than `==1.4.2`. 4. The package should place its files under standard locations (e.g. executables under `$PREFIX/bin`), unless justification is provided. @@ -245,4 +245,4 @@ Recommended: 1. SONAMEs follow naming recommendations given by upstream. 2. If ABI compatibility is important for the package, `run_exports` are set accordingly. - See [Pinned dependencies](pinning_deps.md#pinned-deps) and the [conda-build docs](https://docs.conda.io/projects/conda-build/en/stable/resources/define-metadata.html#export-runtime-requirements) for more information. + See [Pinned dependencies](pinning_deps.mdx) and the [conda-build docs](https://docs.conda.io/projects/conda-build/en/stable/resources/define-metadata.html#export-runtime-requirements) for more information. diff --git a/docs/maintainer/infrastructure.mdx b/docs/maintainer/infrastructure.mdx index 97b31cb70d0..26e1c1e02dc 100644 --- a/docs/maintainer/infrastructure.mdx +++ b/docs/maintainer/infrastructure.mdx @@ -159,9 +159,9 @@ Hosts the global pinnings for conda-forge, and the ongoing migrations. Package-wide dependency pins are defined in [conda_build_config.yaml](https://github.com/conda-forge/conda-forge-pinning-feedstock/blob/main/recipe/conda_build_config.yaml) in the [conda-forge/conda-forge-pinning-feedstock](https://github.com/conda-forge/conda-forge-pinning-feedstock). -For more information on conda-forge wide package pins, please refer to [Globally pinned packages](pinning_deps.md#globally-pinned-packages). +For more information on conda-forge wide package pins, please refer to [Globally pinned packages](pinning_deps.mdx#globally-pinned-packages). -Please open a [PR](../glossary.md#pr) and/or an issue there, if you think a pin needs to be advanced. For more information on updating globally pinned packages, please refer to [Updating package pins](pinning_deps.md#update-pins). +Please open a [PR](../glossary.md#pr) and/or an issue there, if you think a pin needs to be advanced. For more information on updating globally pinned packages, please refer to [Updating package pins](pinning_deps.mdx#updating-package-pins). #### conda-forge-repodata-patches @@ -646,7 +646,7 @@ can be specified as arguments to the `compiler(...)` macro: The authoritative source of the current compilers and versions for various languages and platforms is the [conda_build_config.yaml](https://github.com/conda-forge/conda-forge-pinning-feedstock/blob/main/recipe/conda_build_config.yaml) file in the [conda-forge/conda-forge-pinning-feedstock](https://github.com/conda-forge/conda-forge-pinning-feedstock) repository -as described in [Globally pinned packages](pinning_deps.md#globally-pinned-packages). +as described in [Globally pinned packages](pinning_deps.mdx#globally-pinned-packages). The default C and C++ compilers are GCC on Linux, Clang on macOS and VS2022 on Windows. Clang can also be used as the compiler on Linux and Windows. diff --git a/docs/maintainer/knowledge_base.mdx b/docs/maintainer/knowledge_base.mdx index a81fdf8d2e0..9aefe1060ee 100644 --- a/docs/maintainer/knowledge_base.mdx +++ b/docs/maintainer/knowledge_base.mdx @@ -2214,7 +2214,7 @@ There are several kinds of migrations, which you can read about in [Making Migra To propose a migration in one or more pins, the migrator issues a PR into the pinning feedstock using a yaml file expressing the changes to the global pinning file in the migrations folder. Once the PR is merged, the dependency graph is built. After that, the bot walks through the graph, migrates all the nodes (feedstocks) one by one, and issues PRs for those feedstocks. -Usually, the bot generates these migrations automatically. However, when a pin is first made or added, one may need to be added by hand. To do this, you can follow the steps mentioned in [Updating package pins](pinning_deps.md#update-pins). +Usually, the bot generates these migrations automatically. However, when a pin is first made or added, one may need to be added by hand. To do this, you can follow the steps mentioned in [Updating package pins](pinning_deps.mdx#updating-package-pins). The way migrations proceed are: diff --git a/docs/maintainer/maintainer_faq.md b/docs/maintainer/maintainer_faq.mdx similarity index 97% rename from docs/maintainer/maintainer_faq.md rename to docs/maintainer/maintainer_faq.mdx index cc8d5f61c42..c9bb2640824 100644 --- a/docs/maintainer/maintainer_faq.md +++ b/docs/maintainer/maintainer_faq.mdx @@ -2,6 +2,8 @@ title: 'FAQ' --- +import { RecipeTabs } from "@site/src/components/RecipeTabs"; + # FAQ @@ -133,12 +135,24 @@ ImportError: libGL.so.1: cannot open shared object file: No such file or directo If you saw this error while building a package in your feedstock, add the Linux host dependency `libgl-devel`, provided by the [libglvnd-feedstock](https://github.com/conda-forge/libglvnd-feedstock). + + ```recipe requirements: host: - libgl-devel # [linux] + +``` + +```recipe +requirements: + host: + - if: linux + then: libgl-devel ``` + + Other OpenGL API variants such as `libegl-devel`, `libgles-devel`, `libglx-devel`, and `libopengl-devel` are also available, and will automatically add non-development `run_exports` dependencies. If you are seeing this error after installing a package locally, then you are missing an [OpenGL](https://en.wikipedia.org/wiki/OpenGL) provider in your system dependencies. This is more likely to happen in headless systems with no graphics (servers, Docker images, etc). To fix it, you must install a provider like [Mesa](https://www.mesa3d.org/) with your system package manager, for example (check your distro documentation for exact packages): @@ -164,12 +178,24 @@ Available platform plugins are: eglfs, minimal, minimalegl, offscreen, vnc, webg This comes from the CI environment being headless and can be fixed by adding the `QT_QPA_PLATFORM=offscreen` [environment variable](https://docs.conda.io/projects/conda-build/en/stable/user-guide/environment-variables.html#inherited-environment-variables). The variable can either be added directly to the test command or provided in the [meta.yaml](../adding_pkgs#the-recipe-recipeyaml-or-metayaml) like so: + + ```recipe build: script_env: - QT_QPA_PLATFORM=offscreen + +``` + +```recipe +build: + script: + env: + QT_QPA_PLATFORM: offscreen ``` + + @@ -196,7 +222,7 @@ In case your issue is longer or you would like to contact us privately, feel fre A feedstock is generally considered abandoned when the maintainer isn't around anymore and doesn't merge new PRs or answer any issues. If that is the case, you can add yourself to the team by using the [@conda-forge-admin, please add user @username](../infrastructure#conda-forge-admin-please-add-user-username) command. -If the maintainer doesn't merge it after roughly a week, [contact conda-forge/core](#mfaq-contact-core) to have it merged. +If the maintainer doesn't merge it after roughly a week, [contact conda-forge/core](#how-can-i-contact-conda-forgecore) to have it merged. Once added, you have full rights to the feedstock and can continue its maintenance. :::note diff --git a/docs/maintainer/pinning_deps.md b/docs/maintainer/pinning_deps.mdx similarity index 90% rename from docs/maintainer/pinning_deps.md rename to docs/maintainer/pinning_deps.mdx index fd59c3e81cf..5fdb8289099 100644 --- a/docs/maintainer/pinning_deps.md +++ b/docs/maintainer/pinning_deps.mdx @@ -2,14 +2,14 @@ title: 'Pinned dependencies' --- +import { RecipeTabs } from "@site/src/components/RecipeTabs"; + # Pinned dependencies - - ## Globally pinned packages @@ -31,6 +31,16 @@ Pinning of packages are handled by the same configuration file and conda-build. E.g. + + +```recipe +requirements: + host: + - gmp 6.1.* + run: + - gmp 6.1.* +``` + ```recipe requirements: host: @@ -39,8 +49,12 @@ requirements: - gmp 6.1.* ``` + + Should be replaced by + + ```recipe requirements: host: @@ -52,10 +66,25 @@ requirements: - gmp ``` +```recipe +requirements: + host: + - gmp + # most libraries will automatically add the corresponding runtime requirement using + # a so-called "run-export" from the gmp build pulled into the host environment. + # In that case you can leave out the following run-requirement: + run: + - gmp +``` + + + The run-export mechanism (see below) additionally ensures the correct version constraints (corresponding to the expected API/ABI stability of `gmp`) are added, so a recipe with an unpinned `gmp` dependency in the host environment will, in the end, work as follows: + + ```recipe requirements: host: @@ -64,6 +93,16 @@ requirements: - gmp >={{ version_from_global_pinning }},<{{ next_version_with_breaking_changes }} ``` +```recipe +requirements: + host: + - gmp ${{ version_from_global_pinning }}.* + run: + - gmp >=${{ version_from_global_pinning }},<${{ next_version_with_breaking_changes }} +``` + + + When there's a new ABI version of gmp (say 7.0), then conda-forge-pinning will be updated. A re-rendering of a package using gmp will change. Therefore to check that a recipe needs to be rebuilt for updated pinnings, you only need to check if the package needs a rerender. ::: @@ -85,20 +124,30 @@ to run requirements. If you need to remove a pinning in rare cases like linking the package statically or if the package is used with `dlopen` instead of linking, then you can do, + + ```recipe build: ignore_run_exports: - gmp + +``` + +```recipe +build: + ignore_run_exports: + by_name: + - gmp ``` + + ::: There is additional documentation on this pinning scheme in [the conda docs](https://docs.conda.io/projects/conda-build/en/stable/resources/variants.html#build-variants). - - ## Specifying run_exports The `run_exports` feature can be used to specify the versions that are [ABI](../glossary.md#abi) compatible with the built version. This leads to higher flexibility of choosable packages, without breakages due to incompatibilities. @@ -126,8 +175,6 @@ Once the pins are updated, via a migration yaml, then all the packages that are - - ## Updating package pins Changing global pins requires rerendering all packages that depend on the package with the changed pin. Doing this manually @@ -147,7 +194,7 @@ be added by hand. To do this, follow these steps: - Remove the migrator yaml for the completed migration - If the version of the package is pinned in the global conda_build_config.yaml, this PR should also: - Update the version in conda_build_config.yaml - - Bump the version in meta.yaml to the current date + - Bump the version in the recipe to the current date Details of how the migration yaml is setup are provided in an [example](https://github.com/conda-forge/conda-forge-pinning-feedstock/tree/main/recipe/migrations/example.exyaml) and documentation [here](https://github.com/conda-forge/conda-forge-bot/blob/main/README.md#making-migrators). diff --git a/docs/user/faq.md b/docs/user/faq.md index 4a81e2b4ce2..1d519a5b059 100644 --- a/docs/user/faq.md +++ b/docs/user/faq.md @@ -171,7 +171,7 @@ If your package breaks ABI with a version bump, here are a few steps you can tak - Add a PR to pin the old version in `conda-forge-pinning` (if not already present) - Open a migrator following [CFEP-09](https://github.com/conda-forge/cfep/blob/main/cfep-09.md) -To read more on how to specify `run_exports`, see [Specifying run_exports](../maintainer/pinning_deps.md#run-exports). +To read more on how to specify `run_exports`, see [Specifying run_exports](../maintainer/pinning_deps.mdx#specifying-run_exports). Some of the examples you can see for reference, where broken packages are fixed by: - [Replacing an existing pin that was incorrect](https://github.com/conda-forge/conda-forge-repodata-patches-feedstock/pull/217). diff --git a/scripts/sphinx_markdown_to_docusaurus.py b/scripts/sphinx_markdown_to_docusaurus.py index 4b1a4529500..b16d3e52464 100644 --- a/scripts/sphinx_markdown_to_docusaurus.py +++ b/scripts/sphinx_markdown_to_docusaurus.py @@ -18,12 +18,12 @@ "/docs/user/how_to_get_help.md", "/docs/user/talks.md", "/docs/maintainer/index.md", - "/docs/maintainer/infrastructure.mdx", - "/docs/maintainer/adding_pkgs.mdx", + "/docs/maintainer/infrastructure.md", + "/docs/maintainer/adding_pkgs.md", "/docs/maintainer/updating_pkgs.md", "/docs/maintainer/pinning_deps.md", "/docs/maintainer/conda_forge_yml.md", - "/docs/maintainer/knowledge_base.mdx", + "/docs/maintainer/knowledge_base.md", "/docs/maintainer/maintainer_faq.md", "/docs/orga/index.md", "/docs/orga/guidelines.md",