docs: update system requirements information (#2079)

docs/features/system_requirements.md

@@ -0,0 +1,102 @@
+# System Requirements in pixi
+
+**System requirements** define the minimal system specifications necessary during dependency resolution for a project.
+For instance, specifying a Unix system with a particular minimal `libc` version ensures that dependencies are compatible
+with the project's environment.
+
+System specifications are closely related
+to [virtual packages](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-virtual.html), allowing for
+flexible and accurate dependency management.
+
+## Default System Requirements
+
+The following configurations outline the default minimal system requirements for different operating systems:
+
+=== "Linux"
+    ```toml
+    # Default system requirements for Linux
+    [system-requirements]
+    linux = "4.18"
+    libc = { family = "glibc", version = "2.28" }
+    ```
+=== "Windows"
+    Windows currently has no minimal system requirements defined. If your project requires specific Windows configurations,
+    you should define them accordingly.
+=== "osx-64"
+    ```toml
+    # Default system requirements for macOS
+    [system-requirements]
+    macos = "13.0"
+    ```
+=== "osx-arm64"
+    ```toml
+    # Default system requirements for macOS ARM64
+    [system-requirements]
+    macos = "13.0"
+    ```
+
+## Customizing System Requirements
+
+You only need to define system requirements if your project necessitates a different set from the defaults.
+This is common when installing environments on older or newer versions of operating systems.
+
+### Adjusting for Older Systems
+If you're encountering an error like:
+
+```bash
+× The current system has a mismatching virtual package. The project requires '__linux' to be at least version '4.18' but the system has version '4.12.14'
+```
+
+This indicates that the project's system requirements are higher than your current system's specifications.
+To resolve this, you can lower the system requirements in your project's configuration:
+
+```toml
+[system-requirements]
+linux = "4.12.14"
+```
+
+This adjustment informs the dependency resolver to accommodate the older system version.
+
+### Using CUDA in pixi
+
+To utilize CUDA in your project, you must specify the desired CUDA version in the system-requirements table.
+This ensures that CUDA is recognized and appropriately locked into the lock file if necessary.
+
+Example Configuration
+
+```toml
+[system-requirements]
+cuda = "12"  # Replace "12" with the specific CUDA version you intend to use
+```
+
+### Setting System Requirements environment specific
+This can be set per `feature` in the `the manifest` file.
+
+```toml
+[feature.cuda.system-requirements]
+cuda = "12"
+
+[environments]
+cuda = ["cuda"]
+```
+
+### Available Override Options
+In certain scenarios, you might need to override the system requirements detected on your machine.
+This can be particularly useful when working on systems that do not meet the project's default requirements.
+
+You can override virtual packages by setting the following environment variables:
+
+- `CONDA_OVERRIDE_CUDA`
+    - Description: Sets the CUDA version.
+    - Usage Example: `CONDA_OVERRIDE_CUDA=11`
+- `CONDA_OVERRIDE_GLIBC`
+    - Description: Sets the glibc version.
+    - Usage Example: `CONDA_OVERRIDE_GLIBC=2.28`
+- `CONDA_OVERRIDE_OSX`
+    - Description: Sets the macOS version.
+    - Usage Example: `CONDA_OVERRIDE_OSX=13.0`
+
+## Additional Resources
+
+For more detailed information on managing `virtual packages` and overriding system requirements, refer to
+the [Conda Documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-virtual.html).

docs/reference/project_configuration.md

@@ -229,63 +229,27 @@ You can modify this table using [`pixi task`](cli.md#task).
 ## The `system-requirements` table
 
 The system requirements are used to define minimal system specifications used during dependency resolution.
-For example, we can define a unix system with a specific minimal libc version.
-This will be the minimal system specification for the project.
-System specifications are directly related to the [virtual packages](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-virtual.html).
-
-Currently, the specified **defaults** are the same as [conda-lock](https://github.com/conda/conda-lock)'s implementation:
-
-=== "Linux"
-    ```toml title="default system requirements for linux"
-    [system-requirements]
-    linux = "4.18"
-    libc = { family="glibc", version="2.28" }
-    ```
-
-=== "Windows"
-    ```toml title="default system requirements for windows"
-    [system-requirements]
-    ```
-
-=== "Osx"
-    ```toml title="default system requirements for osx"
-    [system-requirements]
-    macos = "13.0"
-    ```
-
-=== "Osx-arm64"
-    ```toml title="default system requirements for osx-arm64"
-    [system-requirements]
-    macos = "13.0"
-    ```
-
-Only if a project requires a different set should you define them.
-
-For example, when installing environments on old versions of linux.
-You may encounter the following error:
-
-```
-× The current system has a mismatching virtual package. The project requires '__linux' to be at least version '4.18' but the system has version '4.12.14'
-```
-
-This suggests that the system requirements for the project should be lowered.
-To fix this, add the following table to your configuration:
 
+For example, we can define a unix system with a specific minimal libc version.
 ```toml
 [system-requirements]
-linux = "4.12.14"
+libc = "2.28"
 ```
-
-#### Using Cuda in pixi
-
-If you want to use `cuda` in your project you need to add the following to your `system-requirements` table:
-
+or make the project depend on a specific version of `cuda`:
 ```toml
 [system-requirements]
-cuda = "11" # or any other version of cuda you want to use
+cuda = "12"
 ```
 
-This informs the solver that cuda is going to be available, so it can lock it into the lock file if needed.
+The options are:
+
+- `linux`: The minimal version of the linux kernel.
+- `libc`: The minimal version of the libc library. Also allows specifying the family of the libc library.
+e.g. `libc = { family="glibc", version="2.28" }`
+- `macos`: The minimal version of the macOS operating system.
+- `cuda`: The minimal version of the CUDA library.
+
+More information in the [system requirements documentation](../features/system_requirements.md).
 
 ## The `pypi-options` table
 

mkdocs.yml

@@ -120,6 +120,7 @@ nav:
       - Multi Platform: features/multi_platform_configuration.md
       - Multi Environment: features/multi_environment.md
       - Lockfile: features/lockfile.md
+      - System Requirements: features/system_requirements.md
   - Design Proposals:
       - Pixi Global Manifest: design_proposals/pixi_global_manifest.md
   - Advanced: