Add support for using conda as an environment manager.

.gitignore

@@ -18,7 +18,7 @@ distribute-*
 .coverage
 .coverage.*
 coverage.xml
-venv*
+/venv*
 .vscode/
 .eggs/
 .tox/

changes/596.feature.md

@@ -0,0 +1 @@
+Windows and macOS apps can now use `conda` to manage their Python environments.

docs/en/SUMMARY.md

@@ -59,6 +59,10 @@
 - [Reference](reference/index.md)
     - [Briefcase configuration options](reference/environment.md)
     - [Project configuration options](reference/configuration.md)
+    - [Environment Management](reference/env_management/index.md)
+        - [venv](reference/env_management/venv.md)
+        - [uv](reference/env_management/uv.md)
+        - [Conda](reference/env_management/conda.md)
     - [Command Reference](reference/commands/index.md)
         - [new](reference/commands/new.md)
         - [convert](reference/commands/convert.md)

docs/en/reference/configuration.md

@@ -110,9 +110,10 @@ The contact email address for the person or organization responsible for the pro
 The environment manager to use when creating isolated Python environments and installing requirements. Must be one of:
 
 * `venv` - The `venv` package provided by the Python standard library
-* `uv` - The [uv](https://docs.astral.sh/uv/) environment manager
+* `uv` - The [uv](https://docs.astral.sh/uv/) environment manager (available for macOS, Windows, iOS, and Linux System apps that do *not* use Docker)
+* `conda` - The [Conda](https://docs.conda.io/) environment manager (available for macOS and Windows apps)
 
-Defaults to `venv`.
+Defaults to `venv`. For details on using different environment managers, see the [environment management reference][environment-management].
 
 #### `license_files`
 
@@ -261,9 +262,17 @@ A longer description of the purpose of the application. This description can be
 
 A string describing the minimum OS version that the generated app will support. This value is only used on platforms that have a clear mechanism for specifying OS version compatibility; on the platforms where it *is* used, the interpretation of the value is platform specific. Refer to individual platform guides for details on how the provided value is interpreted.
 
+#### `primary_color`
+
+A hexadecimal RGB color value (e.g., `#008577`) to use as the primary color for the application. This setting is only used if the platform allows color modification, otherwise it is ignored.
+
+#### `primary_color_dark`
+
+A hexadecimal RGB color value (e.g., `#008577`) used alongside the primary color. This setting is only used if the platform allows color modification, otherwise it is ignored.
+
 #### `requirement_installer_args`
 
-A list of strings of arguments to pass to the requirement installer when building the app.
+A list of strings of arguments to pass to the environment manager when installing requirements for the app.
 
 Strings will be automatically transformed to absolute paths if they appear to be relative paths (i.e., starting with `./` or `../`) and resolve to an existing path relative to the app's configuration file. This is done to support build targets where the requirement installer command does not run with the same working directory as the configuration file.
 
@@ -273,72 +282,41 @@ The following examples will have the relative path transformed to an absolute on
 
 ```toml
 requirement_installer_args = ["--find-links", "./wheels"]
-
+```
+```toml
 requirement_installer_args = ["-f", "../wheels"]
 ```
 
 On the other hand, the next two examples avoid it because the string starts with `-`, does not start with a relative path indication (`./` or `../`), or do not resolve to an existing path:
 
 ```toml
 requirement_installer_args = ["-f./wheels"]
-
+```
+```toml
 requirement_installer_args = ["--find-links=./wheels"]
-
+```
+```toml
 requirement_installer_args = ["-f", "wheels"]
-
+```
+```toml
 requirement_installer_args = ["-f", "./this/path/does/not/exist"]
 ```
 
 /// admonition | Supported arguments
 
-The arguments supported in [`requirement_installer_args`][] depend on the requirement installer backend.
-
-The only currently supported requirement installer is `pip`. As such, the list should only contain valid arguments to the `pip install` command.
+The arguments supported in [`requirement_installer_args`][] depend on the [environment manager][environment-management] being used.
 
-Briefcase does not validate the inputs to this configuration, and will only report errors directly indicated by the requirement installer backend.
+Briefcase does not validate the inputs to this configuration, and will report the errors raised by the environment manager.
 
 ///
 
-#### `primary_color`
-
-A hexadecimal RGB color value (e.g., `#008577`) to use as the primary color for the application. This setting is only used if the platform allows color modification, otherwise it is ignored.
-
-#### `primary_color_dark`
-
-A hexadecimal RGB color value (e.g., `#008577`) used alongside the primary color. This setting is only used if the platform allows color modification, otherwise it is ignored.
-
 #### `requires`
 
 A list of packages that must be packaged with this application.
 
 Unlike most other keys in a configuration file, [`requires`][] is a *cumulative* setting. If an application defines requirements at the global level, application level, *and* platform level, the final set of requirements will be the *concatenation* of requirements from all levels, starting from least to most specific.
 
-Any version specifier accepted by the [environment manager][env_manager] is legal. For example, if you're using `venv` or `uv`, the following would be legal:
-
-- Bare package name:
-  ```python
-  requires = ["pillow"]
-  ```
-
-- Package name with version specifier:
-  ```python
-  requires = ["pillow==9.1.0"]
-  ```
-
-- Git repository:
-  ```python
-  requires = ["git+https://github.com/beeware/briefcase.git"]
-  ```
-
-- Local directory:
-  ```python
-  requires = ["mysrc/myapp"]
-  ```
-
-- Local wheel file:
-  ```python
-  requires = ["fullpath/wheelfile.whl"]
-  ```
+The format for specifying requirements is determined by the [environment manager][env_manager] that is in use. For details on the format for specifying requirements, see the [environment management reference][environment-management].
 
 #### `revision`
 
@@ -368,11 +346,13 @@ A file path or URL pointing at a tarball containing a Python support package. (i
 
 If this setting is not provided, Briefcase will use the default support package for the platform.
 
+The setting will be ignored if the app's environment manager is responsible for providing Python (e.g., Conda).
+
 #### `support_revision`
 
 The specific revision of a support package that should be used. By default, Briefcase will use the support package revision nominated by the application template. If you specify a support revision, that will override the revision nominated by the application template.
 
-If you specify an explicit support package (either as a URL or a file path), this argument is ignored.
+This argument will be ignored if you specify an explicit support package (either as a URL or a file path), or if the app's environment manager is responsible for providing Python (e.g., Conda).
 
 #### `supported`
 
@@ -396,7 +376,7 @@ A list of packages that are required for the test suite to run.
 
 Unlike most other keys in a configuration file, [`test_requires`][] is a *cumulative* setting. If an application defines requirements at the global level, application level, *and* platform level, the final set of requirements will be the *concatenation* of requirements from all levels, starting from least to most specific.
 
-See [`requires`][] for examples.
+The format for specifying requirements is determined by the [environment manager][env_manager] that is in use. For details on the format for specifying requirements, see the [environment management reference][environment-management].
 
 #### `test_sources`
 

docs/en/reference/env_management/conda.md

@@ -0,0 +1,59 @@
+# Environment management with Conda
+
+Briefcase is able to use [Conda](https://conda.io) to manage the installation of application requirements.
+
+When Conda is used to manage your app environment, Conda is also used to provide the underlying Python library for the running application, rather than an official Python or Briefcase-supplied Python support package.
+
+## Prerequisites
+
+Briefcase requires the use of Conda 26.5 or higher.
+
+Conda environment management can only be used for macOS and Windows apps. An error will be raised if you attempt to use Conda as an environment manager on any other platform.
+
+To use Conda as the environment manager in your application, the `conda` binary must be available on your `PATH`. It can be installed using any of the [installation methods described in the Conda documentation](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html).
+
+## Configuration
+
+To use Conda as the environment manager for your app, add `env_manager = "conda"` to your app configuration. This can be done as a global setting (in `[tool.briefcase]` section) or in a per-app setting (in the `[tool.briefcase.app.myapp]` section for `myapp`).
+
+The Conda environments that are created by Briefcase are installed using the `rattler` resolver.
+
+## Specifying requirements
+
+When `conda` is used as an environment manager, requirements are installed using `conda install`. The values provided to `requires` and `test_requires` must be in Conda-compatible format. The following would be examples of legal specifiers:
+
+- Bare package name:
+  ```python
+  requires = ["pillow"]
+  ```
+
+- Fuzzy version match
+  ```python
+  requires = ["pillow=9.1"]
+  ```
+
+- Channel-qualified install
+  ```python
+  requires = ["conda-forge::pillow"]
+  ```
+
+Conda cannot install packages stored as local source references. If your requirements reference a local path, Briefcase will use `pip` to install that requirement (and its dependencies) into your Conda environment. The following are examples of paths that would be installed with `pip`:
+
+- A local directory:
+  ```python
+  requires = [
+      "../mysrc/myapp",
+      "./local/otherapp",
+      "/usr/local/fullapp",
+  ]
+  ```
+  When in development mode, a reference to a local directory will be installed editable. Any changes made to the code in the original location will be picked up automatically the next time you start your application in development mode. When generating a final application, editable mode will *not* be used.
+
+- Local wheel file:
+  ```python
+  requires = [
+      "../mysrc/myapp-1.2.3.py3-none-any.whl",
+      "./local/otherapp-1.2.3.py3-none-any.whl",
+      "/usr/local/fullapp-1.2.3.py3-none-any.whl",
+  ]
+  ```

docs/en/reference/env_management/index.md

@@ -0,0 +1,7 @@
+# Environment management { #environment-management }
+
+Every Briefcase application is a standalone Python environment. Briefcase supports using the following environment management tools to create and install Python requirements into your application:
+
+* [`venv`](./venv.md) - Using the built-in Python `venv` tool to manage app environment.
+* [`uv`](./venv.md) - Using `uv` to manage your app environment.
+* [`conda`](./venv.md) - Using `conda` to manage your app environment.

docs/en/reference/env_management/uv.md

@@ -0,0 +1,58 @@
+# Environment management with uv
+
+Briefcase is able to use [uv](https://docs.astral.sh/uv/) to manage the installation of application requirements.
+
+When `uv` is used to manage your app environment, an official Python or Briefcase-supplied Python support package will be used for your app.
+
+## Prerequisites
+
+Uv environment management can be used for macOS, Windows and iOS apps; and for Linux System apps when Docker is *not* used. An error will be raised if you attempt to use uv as an environment manager on any other platform, or if you attempt to build a Linux System app with Docker.
+
+To use uv as the environment manager in your application, the `uv` binary must be available on your `PATH`. It can be installed using any of the [installation methods described in the uv documentation](https://docs.astral.sh/uv/getting-started/installation/).
+
+## Configuration
+
+To use uv as the environment manager for your app, add `env_manager = "uv"` to your app configuration. This can be done as a global setting (in `[tool.briefcase]` section) or in a per-app setting (in the `[tool.briefcase.app.myapp]` section for `myapp`).
+
+## Specifying requirements
+
+When `uv` is used as an environment manager, requirements are installed using `uv pip install`. The values provided to `requires` and `test_requires` must be in a `pip`-compatible format. The following would be examples of legal specifiers:
+
+- A bare package name:
+  ```python
+  requires = ["pillow"]
+  ```
+
+- A package name with version specifier:
+  ```python
+  requires = ["pillow==9.1.0"]
+  ```
+
+- A package with a platform specifier:
+  ```python
+  requires = ["pillow==9.1.0; sys_platform == 'darwin'"]
+  ```
+
+- A Git repository:
+  ```python
+  requires = ["git+https://github.com/beeware/briefcase.git"]
+  ```
+
+- A local directory:
+  ```python
+  requires = [
+      "../mysrc/myapp",
+      "./local/otherapp",
+      "/usr/local/fullapp",
+  ]
+  ```
+  When in development mode, a reference to a local directory will be installed editable. Any changes made to the code in the original location will be picked up automatically the next time you start your application in development mode. When generating a final application, editable mode will *not* be used.
+
+- Local wheel file:
+  ```python
+  requires = [
+      "../mysrc/myapp-1.2.3.py3-none-any.whl",
+      "./local/otherapp-1.2.3.py3-none-any.whl",
+      "/usr/local/fullapp-1.2.3.py3-none-any.whl",
+  ]
+  ```

docs/en/reference/env_management/venv.md

@@ -0,0 +1,58 @@
+# Environment management with `venv`
+
+The default environment manager used by Briefcase to manage the installation of application requirements is the `venv` package built into Python's standard library.
+
+When `venv` is used to manage your app environment, an official Python or Briefcase-supplied Python support package will be used for your app.
+
+## Prerequisites
+
+There are no additional pre-requisites for using `venv` to manage application environments. Requirements will be installed with `pip`; Briefcase will use the version of `pip` that is installed in the environment where Briefcase is executed. `venv` can be used to build apps on all platforms.
+
+## Configuration
+
+No additional configuration is needed to use `venv` as the environment manager for your application.
+
+However, you can *explicitly* specify the use of `venv` by adding `env_manager = "venv"` to your app configuration. This can be done as a global setting (in `[tool.briefcase]` section) or in a per-app setting (in the `[tool.briefcase.app.myapp]` section for `myapp`).
+
+## Specifying requirements
+
+When `venv` is used as an environment manager, requirements are installed using `pip`. The values provided to `requires` and `test_requires` must be in a `pip`-compatible format. The following would be examples of legal specifiers:
+
+- A bare package name:
+  ```python
+  requires = ["pillow"]
+  ```
+
+- A package name with version specifier:
+  ```python
+  requires = ["pillow==9.1.0"]
+  ```
+
+- A package with a platform specifier:
+  ```python
+  requires = ["pillow==9.1.0; sys_platform == 'darwin'"]
+  ```
+
+- A Git repository:
+  ```python
+  requires = ["git+https://github.com/beeware/briefcase.git"]
+  ```
+
+- A local directory:
+  ```python
+  requires = [
+      "../mysrc/myapp",
+      "./local/otherapp",
+      "/usr/local/fullapp",
+  ]
+  ```
+  When in development mode, a reference to a local directory will be installed editable. Any changes made to the code in the original location will be picked up automatically the next time you start your application in development mode. When generating a final application, editable mode will *not* be used.
+
+- Local wheel file:
+  ```python
+  requires = [
+      "../mysrc/myapp-1.2.3.py3-none-any.whl",
+      "./local/otherapp-1.2.3.py3-none-any.whl",
+      "/usr/local/fullapp-1.2.3.py3-none-any.whl",
+  ]
+  ```

docs/en/reference/index.md

@@ -4,6 +4,7 @@ This is the technical reference for public APIs provided by Briefcase.
 
 * [Briefcase configuration options][briefcase-configuration-options] - Configuring the environment variables needed to customize the Briefcase resource directory.
 * [Project configuration options][project-configuration-options] - Configuring an app built with Briefcase.
+* [Environment management][environment-management] - Configuring the standalone Python environment that is used by your Briefcase app.
 * [Command reference][command-reference] - Details about the commands available in Briefcase.
 * [Platform support][platform-support-key] - Details about the various platforms supported by Briefcase.
 * [Plugins][plugins] - Implementing a third-party plugin for use with Briefcase.

docs/en/reference/platforms/macOS/index.md

@@ -322,3 +322,7 @@ info."UIDesignRequiresCompatibility" = true
 ```
 
 Once you've made this change, re-run `briefcase create` for your application.
+
+### Universal apps and Conda
+
+If you are using Conda as an environment manager for your app, you *cannot* build a universal app. This is because Conda packages do not provide universal binaries, and merging separate platform-specific Conda environments to produce a universal Conda environment is not a simple task. Therefore, you *must* add `universal_build = false` to your macOS configuration if you are using Conda as your environment manager.

docs/spelling_wordlist

@@ -41,6 +41,7 @@ CLI
 cmd
 CMD
 codebase
+Conda
 cookiecutter
 Cookiecutter
 cryptographic
@@ -231,6 +232,7 @@ UTTypeConformsTo
 uv
 vendored
 Ventura
+venv
 verbing
 visionOS
 VM