Configuring conda-forge.yml¶
You can configure how conda-forge is set up and built via the conda-forge.yml
file that is present in the root directory of a feedstock.
Rerendering the feedstock after you modify this file is usually required and always a good idea (see Rerendering feedstocks).
The next section describes in detail the top-level fields in conda-forge.yml
.
Note that each top-level CI provider field supports the upload_packages
option.
When set to False this will override the default behaviour of attempting to
upload packages to anaconda.org, which can be useful for testing. For example:
azure:
upload_packages: False
Top-level fields¶
appveyor¶
The top-level appveyor
key specifies configurations for the Appveyor
CI service. This is usually read-only and should not normally be manually
modified. Tools like conda-smithy may modify this, as needed.
azure¶
This dictates the behavior of the Azure Pipelines CI service. It is a mapping for Azure-specific configuration options. For example:
azure:
# flag for forcing the building all supported providers
force: False
# toggle for storing the conda build_artifacts directory (including the
# built packages) as an Azure pipeline artifact that can be downloaded
store_build_artifacts: False
# toggle for freeing up some extra space on the default Azure Pipelines
# linux image before running the Docker container for building
free_disk_space: False
# limit the amount of CI jobs running concurrently at a given time
# each OS will get its proportional share of the configured value
max_parallel: 25
Below is an example configuration for setting up a self-hosted Azure agent for Linux:
azure:
settings_linux:
pool:
name: your_local_pool_name
demands:
- some_key -equals some_value
workspace:
clean: all
strategy:
maxParallel: 1
Below is an example configuration for adding a swapfile on an Azure agent for Linux:
azure:
settings_linux:
swapfile_size: 10GiB
To increase the pagefile size on Windows, use this block:
azure:
settings_win:
variables:
SET_PAGEFILE: 'True'
bot¶
This field controls the behavior of the auto-tick
bot which issues
automatic version updates/migrations for feedstocks. The current options are
bot:
# can the bot automerge PRs it makes on this feedstock
automerge: true
# only automerge on successful version PRs, migrations are not automerged
automerge: 'version'
# only automerge on successful migration PRs, versions are not automerged
automerge: 'migration'
# only open PRs if resulting environment is solvable, useful for tightly coupled packages
check_solvable: true
# The bot.inspection key in the conda-forge.yml can have one of six possible values:
inspection: hint # generate hints using source code (backwards compatible)
inspection: hint-all # generate hints using all methods
inspection: hint-source # generate hints using only source code
inspection: hint-grayskull # generate hints using only grayskull
inspection: update-all # update recipe using all methods
inspection: update-source # update recipe using only source code
inspection: update-grayskull # update recipe using only grayskull
# any branches listed in this section will get bot migration PRs in addition
# to the default branch
abi_migration_branches:
- v1.10.x
version_updates:
# use this for packages that are updated too frequently
random_fraction_to_keep: 0.1 # keeps 10% of versions at random
The abi_migration_branches
feature is useful to, for example, add a
long-term support (LTS) branch for a package.
build_platform¶
This is a mapping from the target platform to the build platform for the package
to be built. e.g. the following builds a osx-64
package on the linux-64
build platform using cross-compiling.
build_platform:
osx_64: linux_64
Leaving this field empty implicitly requests to build a package natively. i.e.
build_platform:
linux_64: linux_64
linux_ppc64le: linux_ppc64le
linux_aarch64: linux_aarch64
osx_64: osx_64
osx_arm64: osx_arm64
win_64: win_64
build_with_mambabuild¶
This option, when enabled, configures the conda-forge CI to run a debug build using the mamba
solver. Check this to know more.
build_with_mambabuild:
True
channel_priority¶
This value sets the conda
solver channel priority for feedstock builds.
The default is strict
. Any valid value for the same setting in the .condarc
is
allowed here.
channels¶
This represents the channels to grab packages from during builds and
which channels/labels to push to on anaconda.org after a package
has been built. The channels
variable is a mapping with
sources
and targets
, as follows:
channels:
# sources selects the channels to pull packages from, in order.
sources:
- conda-forge
- defaults
# targets is a list of 2-lists, where the first element is the
# channel to push to and the second element is the label on that channel
targets:
- ["conda-forge", "main"]
choco¶
This parameter allows for conda-smithy to run chocoloatey installs on Windows when additional system packages are needed. This is a list of strings that represent package names and any additional parameters. For example,
choco:
# install a package
- nvidia-display-driver
# install a package with a specific version
- cuda --version=11.0.3
This is currently only implemented for Azure Pipelines. The command that is run is
choco install {entry} -fdv -y --debug
. That is, choco install
is executed
with a standard set of additional flags that are useful on CI.
circle¶
The top-level circle
key specifies configurations for the Circle
CI service. This is usually read-only and should not normally be manually
modified. Tools like conda-smithy may modify this, as needed.
conda_build¶
Settings in this block are used to control how conda build runs and produces artifacts. The currently supported options are
conda_build:
pkg_format: 2 # makes .conda artifacts
pkg_format: None # makes .tar.bz2 artifacts
# controls the compression level for .conda artifacts
# conda-forge uses a default value of 16 since its artifacts
# can be large. conda-build has a default of 22.
zstd_compression_level: 16
conda_forge_output_validation¶
This field must be set to True
for feedstocks in the conda-forge
GitHub
organization. It enables the required feedstock artifact validation as described
in Output Validation and Feedstock Tokens.
docker¶
This is a mapping to docker configuration options. These are relatively self-explanatory. The defaults are as follows:
docker:
executable: docker
image: "condaforge/linux-anvil-comp7"
command: "bash"
interactive: True
github¶
This is mapping of configuration variables for GitHub. The defaults are as follows:
github:
# name of the github organization
user_or_org: conda-forge
# repository name, usually filled in automatically
repo_name: ""
# branch name to execute on
branch_name: main
# branch name to use for rerender+webservices github actions and
# conda-forge-ci-setup-feedstock references
tooling_branch_name: main
idle_timeout_minutes¶
Configurable idle timeout that is either an int or None. Used for packages that don’t have chatty enough builds. Currently only implemented in Travis and Circle.
idle_timeout_minutes: 60
linux¶
The Linux-specific configuration options. This is largely an internal setting. Currently only:
linux:
enabled: False
linux_aarch64¶
The ARM-specific configuration options. This is largely an internal setting. Currently only:
linux_aarch64:
enabled: False
linux_ppc64le¶
The PPC-specific configuration options. This is largely an internal setting. Currently only:
linux_ppc64le:
enabled: False
noarch_platforms¶
Platforms on which to build noarch packages. The preferred default is a
single build on linux_64
.
noarch_platforms: linux_64
To build on multiple platforms, e.g. for simple packages with platform-specific dependencies, provide a list.
noarch_platforms:
- linux_64
- win_64
os_version¶
This key is used to set the OS versions for linux_*
platforms. Valid entries map a linux platform and arch to either cos6
or cos7
. Currently cos6
is the default for linux-64
. All other linux architectures use CentOS 7. Here is an example that enables CentOS 7 on linux-64
builds
os_version:
linux_64: cos7
osx¶
The macOSX-specific configuration options. This is largely an internal setting. Currently only:
osx:
enabled: False
provider¶
The provider
field is a mapping from build platform (not target platform) to CI service.
It determines which service handles each build platform. The following are available as
build platforms:
linux_64
osx_64
win_64
linux_aarch64
linux_ppc64le
The following CI services are available:
azure
circle
travis
appveyor
None
orFalse
to disable a build platform.default
to choose an appropriate CI (only if available)
For example, switching linux_64 & osx_64 to build on Travis CI, with win_64 on Appveyor:
provider:
linux_64: travis
osx_64: travis
win_64: appveyor
Currently, x86_64 platforms are enabled, but other build platforms are disabled by default. i.e. an empty provider entry is equivalent to the following:
provider:
linux_64: azure
osx_64: azure
win_64: azure
linux_ppc64le: None
linux_aarch64: None
To enable linux_ppc64le
and linux_aarch64
add the following:
provider:
linux_ppc64le: default
linux_aarch64: default
If a desired build platform is not available with a selected provider
(either natively or with emulation), the build will be disabled. Use the build_platform
field to manually specify cross-compilation when no providers offer a desired build platform.
recipe_dir¶
The relative path to the recipe directory. The default is:
recipe_dir: recipe
remote_ci_setup¶
This option can be used to override the default conda-forge-ci-setup
package.
Can be given with ${url or channel_alias}::package_name
, defaults to conda-forge
channel_alias if no prefix is given.
remote_ci_setup: "conda-forge-ci-setup=3"
shellcheck¶
Shell scripts used for builds or activation scripts can be linted with shellcheck. This is not enabled by default, but can be enabled like so:
shellcheck:
enabled: True
skip_render¶
This option specifies a list of files which conda smithy will skip rendering.
The possible values can be a subset of .gitignore
, .gitattributes
, README.md
, LICENSE.txt
.
The default value is an empty list [ ], i.e. all these four files will be generated by conda smithy.
For example, if you want to customize .gitignore and LICENSE.txt files on your own, you should have the following configuration.
skip_render:
- .gitignore
- LICENSE.txt
templates¶
This is mostly an internal field for specifying where templates files live. You shouldn’t need it.
test_on_native_only¶
This is used for disabling testing for cross compiling. Default is false
test_on_native_only: True
Note
This has been deprecated in favor of the test top-level field. It is now mapped to test: native_and_emulated
.
test¶
This is used to configure on which platforms a recipe is tested. Default is all
.
test: native_and_emulated
Will do testing only if the platform is native or if there is an emulator.
test: native
Will do testing only if the platform is native.
travis¶
The top-level travis
key specifies configurations for the Travis
CI service. This is usually read-only and should not normally be manually
modified. Tools like conda-smithy may modify this, as needed.
upload_on_branch¶
This parameter restricts uploading access on work from certain branches of the
same repo. Only the branch listed in upload_on_branch
will trigger uploading
of packages to the target channel. The default is to skip this check if the key
upload_on_branch
is not in conda-forge.yml
. To restrict uploads to the
main branch:
upload_on_branch: main
win¶
The Windows-specific configuration options. This is largely an internal setting. Currently only:
win:
enabled: False