From da5881ce90f8ad5450e0beb0f3f1e1c9883f2052 Mon Sep 17 00:00:00 2001 From: Ruben Arts Date: Thu, 8 Aug 2024 17:51:12 +0200 Subject: [PATCH] docs: update some of the cli and add osx rosetta mention (#1760) --- docs/reference/cli.md | 67 +++++++++++++++++++------ docs/reference/project_configuration.md | 8 ++- 2 files changed, 59 insertions(+), 16 deletions(-) diff --git a/docs/reference/cli.md b/docs/reference/cli.md index e0327777a..beebb5690 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -56,6 +56,7 @@ It will only add if the package with its version constraint is able to work with [More info](../features/multi_platform_configuration.md) on multi-platform configuration. If the project manifest is a `pyproject.toml`, adding a pypi dependency will add it to the native pyproject `project.dependencies` array, or to the native `project.optional-dependencies` table if a feature is specified: + - `pixi add --pypi boto3` would add `boto3` to the `project.dependencies` array - `pixi add --pypi boto3 --feature aws` would add `boto3` to the `project.dependencies.aws` array @@ -63,7 +64,7 @@ These dependencies will be read by pixi as if they had been added to the pixi `p ##### Arguments -1. ``: The package(s) to add, space separated. The version constraint is optional. +1. `[SPECS]`: The package(s) to add, space separated. The version constraint is optional. ##### Options @@ -77,24 +78,48 @@ These dependencies will be read by pixi as if they had been added to the pixi `p - `--no-lockfile-update`: Don't update the lock-file, implies the `--no-install` flag. - `--platform (-p)`: The platform for which the dependency should be added. (Allowed to be used more than once) - `--feature (-f)`: The feature for which the dependency should be added. +- `--editable`: Specifies an editable dependency, only use in combination with `--pypi`. ```shell -pixi add numpy -pixi add numpy pandas "pytorch>=1.8" -pixi add "numpy>=1.22,<1.24" -pixi add --manifest-path ~/myproject/pixi.toml numpy -pixi add --host "python>=3.9.0" -pixi add --build cmake -pixi add --pypi requests[security] -pixi add --pypi "boltons @ https://files.pythonhosted.org/packages/46/35/e50d4a115f93e2a3fbf52438435bb2efcf14c11d4fcd6bdcd77a6fc399c9/boltons-24.0.0-py3-none-any.whl" -pixi add --pypi "exchangelib @ git+https://github.com/ecederstrand/exchangelib" -pixi add --pypi "project @ file:///absolute/path/to/project" -pixi add --platform osx-64 --build clang -pixi add --no-install numpy -pixi add --no-lockfile-update numpy -pixi add --feature featurex numpy +pixi add numpy # (1)! +pixi add numpy pandas "pytorch>=1.8" # (2)! +pixi add "numpy>=1.22,<1.24" # (3)! +pixi add --manifest-path ~/myproject/pixi.toml numpy # (4)! +pixi add --host "python>=3.9.0" # (5)! +pixi add --build cmake # (6)! +pixi add --platform osx-64 clang # (7)! +pixi add --no-install numpy # (8)! +pixi add --no-lockfile-update numpy # (9)! +pixi add --feature featurex numpy # (10)! + +# Add a pypi dependency +pixi add --pypi requests[security] # (11)! +pixi add --pypi Django==5.1rc1 # (12)! +pixi add --pypi "boltons>=24.0.0" --feature lint # (13)! +pixi add --pypi "boltons @ https://files.pythonhosted.org/packages/46/35/e50d4a115f93e2a3fbf52438435bb2efcf14c11d4fcd6bdcd77a6fc399c9/boltons-24.0.0-py3-none-any.whl" # (14)! +pixi add --pypi "exchangelib @ git+https://github.com/ecederstrand/exchangelib" # (15)! +pixi add --pypi "project @ file:///absolute/path/to/project" # (16)! +pixi add --pypi "project @ file:///absolute/path/to/project" --editable # (17)! ``` +1. This will add the `numpy` package to the project with the latest available for the solved environment. +2. This will add multiple packages to the project solving them all together. +3. This will add the `numpy` package with the version constraint. +4. This will add the `numpy` package to the project of the manifest file at the given path. +5. This will add the `python` package as a host dependency. There is currently no different behavior for host dependencies. +6. This will add the `cmake` package as a build dependency. There is currently no different behavior for build dependencies. +7. This will add the `clang` package only for the `osx-64` platform. +8. This will add the `numpy` package to the manifest and lockfile, without installing it in an environment. +9. This will add the `numpy` package to the manifest without updating the lockfile or installing it in the environment. +10. This will add the `numpy` package in the feature `featurex`. +11. This will add the `requests` package as `pypi` dependency with the `security` extra. +12. This will add the `pre-release` version of `Django` to the project as a `pypi` dependency. +13. This will add the `boltons` package in the feature `lint` as `pypi` dependency. +14. This will add the `boltons` package with the given `url` as `pypi` dependency. +15. This will add the `exchangelib` package with the given `git` url as `pypi` dependency. +16. This will add the `project` package with the given `file` url as `pypi` dependency. +17. This will add the `project` package with the given `file` url as an `editable` package as `pypi` dependency. + !!! tip If you want to use a non default pinning strategy, you can set it using [pixi's configuration](./pixi_configuration.md#pinning-strategy). ``` @@ -281,6 +306,7 @@ If the project manifest is a `pyproject.toml`, removing a pypi dependency with t - `--platform (-p)`: The platform from which the dependency should be removed. - `--feature (-f)`: The feature from which the dependency should be removed. - `--no-install`: Don't install the environment, only remove the package from the lock-file and manifest. +- `--no-lockfile-update`: Don't update the lock-file, implies the `--no-install` flag. ```shell pixi remove numpy @@ -907,6 +933,7 @@ This command installs package(s) into its own environment and adds the binary to ##### Options - `--channel (-c)`: specify a channel that the project uses. Defaults to `conda-forge`. (Allowed to be used more than once) +- `--platform (-p)`: specify a platform that you want to install the package for. (default: current platform) ```shell pixi global install ruff @@ -922,8 +949,17 @@ pixi global install python=3.9.* pixi global install "python [version='3.11.0', build_number=1]" pixi global install "python [version='3.11.0', build=he550d4f_1_cpython]" pixi global install python=3.11.0=h10a6764_1_cpython + +# Install for a specific platform, only useful on osx-arm64 +pixi global install --platform osx-64 ruff ``` +!!! tip + Running `osx-64` on Apple Silicon will install the Intel binary but run it using [Rosetta](https://developer.apple.com/documentation/apple-silicon/about-the-rosetta-translation-environment) + ``` + pixi global install --platform osx-64 ruff + ``` + After using global install, you can use the package you installed anywhere on your system. ### `global list` @@ -960,6 +996,7 @@ This command upgrades a globally installed package (to the latest version by def - `--channel (-c)`: specify a channel that the project uses. Defaults to `conda-forge`. Note the channel the package was installed from will be always used for upgrade. (Allowed to be used more than once) +- `--platform (-p)`: specify a platform that you want to upgrade the package for. (default: current platform) ```shell pixi global upgrade ruff diff --git a/docs/reference/project_configuration.md b/docs/reference/project_configuration.md index 9ada3386a..57fc792d5 100644 --- a/docs/reference/project_configuration.md +++ b/docs/reference/project_configuration.md @@ -66,6 +66,12 @@ platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"] The available platforms are listed here: [link](https://docs.rs/rattler_conda_types/latest/rattler_conda_types/enum.Platform.html) +!!! tip "Special MacOS behavior" + MacOS has two platforms: `osx-64` for Intel Macs and `osx-arm64` for Apple Silicon Macs. + To support both, include both in your platforms list. + Fallback: If `osx-arm64` can't resolve, use `osx-64`. + Running `osx-64` on Apple Silicon uses [Rosetta](https://developer.apple.com/documentation/apple-silicon/about-the-rosetta-translation-environment) for Intel binaries. + ### `version` (optional) The version of the project. @@ -648,7 +654,7 @@ This will create an environment called `test` that has `pytest` installed. The `feature` table allows you to define the following fields per feature. - `dependencies`: Same as the [dependencies](#dependencies). -- `pypi-dependencies`: Same as the [pypi-dependencies](#pypi-dependencies-beta-feature). +- `pypi-dependencies`: Same as the [pypi-dependencies](#pypi-dependencies). - `pypi-options`: Same as the [pypi-options](#the-pypi-options-table). - `system-requirements`: Same as the [system-requirements](#the-system-requirements-table). - `activation`: Same as the [activation](#the-activation-table).