Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update some of the cli and add osx rosetta mention #1760

Merged
merged 4 commits into from
Aug 8, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 52 additions & 15 deletions docs/reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,14 +56,15 @@ 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

These dependencies will be read by pixi as if they had been added to the pixi `pypi-dependencies` tables of the default or a named feature.

##### Arguments

1. `<SPECS>`: 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

Expand All @@ -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 <PLATFORM> (-p)`: The platform for which the dependency should be added. (Allowed to be used more than once)
- `--feature <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).
```
Expand Down Expand Up @@ -281,6 +306,7 @@ If the project manifest is a `pyproject.toml`, removing a pypi dependency with t
- `--platform <PLATFORM> (-p)`: The platform from which the dependency should be removed.
- `--feature <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
Expand Down Expand Up @@ -907,6 +933,7 @@ This command installs package(s) into its own environment and adds the binary to
##### Options

- `--channel <CHANNEL> (-c)`: specify a channel that the project uses. Defaults to `conda-forge`. (Allowed to be used more than once)
- `--platform <PLATFORM> (-p)`: specify a platform that you want to install the package for. (default: current platform)

```shell
pixi global install ruff
Expand All @@ -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`
Expand Down Expand Up @@ -960,6 +996,7 @@ This command upgrades a globally installed package (to the latest version by def
- `--channel <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 <PLATFORM> (-p)`: specify a platform that you want to upgrade the package for. (default: current platform)

```shell
pixi global upgrade ruff
Expand Down
8 changes: 7 additions & 1 deletion docs/reference/project_configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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).
Expand Down