From 50136aeb6705857e8393d49372ca1b1e8551f291 Mon Sep 17 00:00:00 2001 From: Ruben Arts Date: Mon, 25 Sep 2023 10:04:03 +0200 Subject: [PATCH 1/2] docs: copy from cms --- docs/basic_usage.mdx | 89 ++++++++++ docs/configuration.mdx | 336 ++++++++++++++++++++++++++++++++++++++ docs/examples/cpp-sdl.mdx | 2 +- docs/overview.mdx | 158 ++++++++++++++---- docs/vision.mdx | 2 +- 5 files changed, 556 insertions(+), 31 deletions(-) create mode 100644 docs/basic_usage.mdx create mode 100644 docs/configuration.mdx diff --git a/docs/basic_usage.mdx b/docs/basic_usage.mdx new file mode 100644 index 000000000..190674dfe --- /dev/null +++ b/docs/basic_usage.mdx @@ -0,0 +1,89 @@ +--- +part: pixi +title: Basic usage +description: Taking your first steps with pixi +--- + +Make sure that you have `pixi` installed, this should print the help function, check the [installation manual](overview) if it doesn't. + +```shell +pixi +``` + +Initialize a new project and navigate to the project directory. + +```shell +pixi init pixi-hello-world +cd pixi-hello-world +``` + +Add the dependencies you would like to use. + +```shell +pixi add python +``` + +Create a file named `hello_world.py` in the directory and paste the following code into the file. + +```python title="hello_world.py" showLineNumbers +def hello(): + print("Hello World, to the new revolution in package management.") + +if __name__ == "__main__": + hello() +``` + +Run the code inside the environment. + +```shell +pixi run python hello_world.py +``` + +You can also put this run command in a **task**. + +```shell +pixi task add hello python hello_world.py +``` + +After adding the task, you can run the task using its name. + +```shell +pixi run hello +``` + +Use the `shell` command to activate the environment and start a new shell in there. + +```shell +pixi shell +python +exit +``` + +You've just learned the basic features of pixi: +1. adding a dependency. +2. adding a task, and executing it. +3. running a program. +Feel free to play around with what you just learned like adding more tasks, dependencies or code. +If you want to learn more checkout out our [in-depth documentation](./advanced) + +Happy coding! + +## Use pixi as an installation tool + +Use pixi to install tools on your machine. + +Some notable examples: + +```shell +# Awesome cross shell prompt, huge tip when using pixi! +pixi global install starship + +# Want to try a different shell? +pixi global install fish + +# Install other prefix.dev tools +pixi global install rattler-build + +# Install a linter you want to use in multiple projects. +pixi global install ruff +``` diff --git a/docs/configuration.mdx b/docs/configuration.mdx new file mode 100644 index 000000000..dd4fc1156 --- /dev/null +++ b/docs/configuration.mdx @@ -0,0 +1,336 @@ +--- +part: pixi +title: Configuration +description: Learn what you can do in the `pixi.toml` configuration. +--- + +The `pixi.toml` is the pixi project configuration file, also known as the project manifest. + +A `toml` file is structured in different tables. +This document will explain the usage of the different tables. +For more technical documentation check [crates.io](https://docs.rs/pixi/latest/pixi/project/manifest/struct.ProjectManifest.html). + +## The `project` table +The minimally required information in the `project` table is: +```toml +[project] +name = "project-name" +version = "0.1.0" +authors = ["John Doe "] +channels = ["conda-forge"] +platforms = ["linux-64"] +``` + +### `name` +The name of the project. +```toml +[project] +name = "project-name" +``` + +### `version` +The version of the project. +This should be a valid version based on the conda Version Spec. +See the [version documentation](https://docs.rs/rattler_conda_types/latest/rattler_conda_types/struct.Version.html), for an explanation what is allowed in a Version Spec. +```toml +[project] +version = "1.2.3" +``` + +### `authors` +This is a list of authors of the project. +```toml +[project] +authors = ["John Doe ", "Marie Curie "] +``` + +### `channels` +This is a list that defines the channels used to fetch the packages from. +If you want to use channels hosted on `anaconda.org` you only need to use the name of the channel directly. +```toml +[project] +channels = ["conda-forge", "robostack", "bioconda", "nvidia", "pytorch"] +``` + +Channels situated on the file system are also supported with file paths: +```toml +[project] +channels = ["conda-forge", "file:///home/user/staged-recipes/build_artifacts"] +``` + +To access private or public channels on [prefix.dev](prefix.dev) or [Quetz](https://github.com/mamba-org/quetz) use the url including the hostname: +```toml +[project] +channels = ["conda-forge", "https://repo.prefix.dev/channel-name"] +``` + +### `platforms` +Defines the list of platforms that the project supports. +Pixi solves the dependencies for all these platforms and puts them in the lockfile (`pixi.lock`). + +```toml +[project] +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) + +### `description` (optional) +Should contain a short description of the project. +```toml +[project] +description = "A simple description" +``` + +### `license` (optional) +The license as a valid [SPDX](https://spdx.org/licenses/) string (e.g. MIT AND Apache-2.0) +```toml +[project] +license = "MIT" +``` + +### `license-file` (optional) +Relative path to the license file. +```toml +[project] +license-file = "LICENSE.md" +``` + +### `readme` (optional) +Relative path to the README file. +```toml +[project] +readme = "README.md" +``` + +### `homepage` (optional) +URL of the project homepage. +```toml +[project] +homepage = "https://pixi.sh" +``` + +### `repository` (optional) +URL of the project source repository. +```toml +[project] +repository = "https://github.com/prefix-dev/pixi" +``` + +### `documentation` +URL of the project documentation. +```toml +[project] +documentation = "https://pixi.sh" +``` + +## The `tasks` table +Tasks are a way to automate certain custom commands in your project. +For example: a `lint` or `format` step. +Tasks in a pixi project are essentially cross-platform shell commands, with a unified syntax across platforms. +For the more in-depth information check the [Advanced tasks documentation](advanced/advanced_tasks). +Pixi tasks are run in a pixi environment using `pixi run` and are executed using the [`deno_task_shell`](advanced/advanced_tasks#our-task-runner-deno_task_shell). + +```toml +[tasks] +simple = "echo This is a simple task" +cmd = { cmd="echo Same as a simple task but now more verbose"} +depending = { cmd="echo run after simple", depends_on="simple"} +alias = { depends_on=["depending"]} +``` +You can modify this table using [`pixi task`](cli#task). +:::note +Specify different tasks for different platforms using the [target](#the-target-table) table +::: + +## 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: + + + ```toml title="default system requirements" + [system-requirements] + unix = true + linux = "5.10" + libc = { family="glibc", version="2.17" } + ``` + + + ```toml title="default system requirements" + [system-requirements] + windows = true + ``` + + + ```toml title="default system requirements" + [system-requirements] + unix = true + macos = "10.15" + ``` + + + ```toml title="Default system requirements" + [system-requirements] + unix = true + macos = "11.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 '5.10' 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: +``` +[system-requirements] +linux = "4.12.14" +``` + +## The `dependencies` table(s) +This section defines what dependencies you would like to use your project. + +There are multiple dependencies tables. +The default is `[dependencies]`, which are dependencies that are shared across platforms. + +Dependencies are defined using a [VersionSpec](https://docs.rs/rattler_conda_types/latest/rattler_conda_types/version_spec/enum.VersionSpec.html). +A `VersionSpec` combines a [Version](https://docs.rs/rattler_conda_types/latest/rattler_conda_types/struct.Version.html) with an optional operator. + +Some examples are: +```toml +# Use this exact package version +package0 = "1.2.3" +# Use 1.2.3 up to 1.3.0 +package1 = "~=1.2.3" +# Use larger than 1.2 lower and equal to 1.4 +package2 = ">1.2,<=1.4" +# Bigger or equal than 1.2.3 or lower not including 1.0.0 +package3 = ">=1.2.3|<1.0.0" +``` + +:::tip +The dependencies can be easily added using the `pixi add` command line. +Running `add` for an existing dependency will replace it with the newest it can use. +::: +:::note +To specify different dependencies for different platforms use the [target](#the-target-table) table +::: + +### `dependencies` +Add any conda package dependency that you want to install into the environment. +Don't forget to add the channel to the project table should you use anything different than `conda-forge`. + +```toml +[dependencies] +python = ">3.9,<=3.11" +rust = "1.72" +``` + +:::note +All packages added to the `dependencies` table are also included as dependencies of the binary build by `pixi build`. + +To only include certain packages in different stages of the build see [`build-dependencies`](#build-dependencies) and [`host-dependencies`](#host-dependencies). +::: + +### `host-dependencies` + +This table contains dependencies that are needed to build your project but which should not be included when your project is installed as part of another project. +In other words, these dependencies are available during the build but are no longer available when your project is installed. +Dependencies listed in this table are installed for the architecture of the target machine. + +```toml +[host-dependencies] +python = "~=3.10.3" +``` + +Typical examples of host dependencies are: + +* Base interpreters: a Python package would list `python` here and an R package would list `mro-base` or `r-base`. +* Libraries your project links against during compilation like `openssl`, `rapidjson`, or `xtensor`. + +### `build-dependencies` +This table contains dependencies that are needed to build the project. +Different from `dependencies` and `host-dependencies` these packages are installed for the architecture of the _build_ machine. +This enables cross-compiling from one machine architecture to another. + +```toml +[build-depencencies] +cmake = "~=3.24" +``` + +Typical examples of build dependencies are: + +* Compilers are invoked on the build machine, but they generate code for the target machine. +If the project is cross-compiled the architecture of the build and target machine might differ. +* `cmake` is invoked on the build machine to generate additional code- or project-files which are then include in the compilation process. + +:::info +The _build_ target refers to the machine that will execute the build. +Programs and libraries installed by these dependencies will be executed on the build machine. + +For example, if you compile on a MacBook with an Apple Silicon chip but target Linux x86_64 then your *build* platform is `osx-arm64` and your *host* platform is `linux-64`. +::: + +## The `activation` table +If you want to run an activation script inside the environment when either doing a `pixi run` or `pixi shell` these can be defined here. +The scripts defined in this table will be sourced when the environment is activated using `pixi run` or `pixi shell` + +```toml +[activation] +scripts = ["env_setup.sh"] +``` +:::note +Specify different scripts for different platforms using the [target](#the-target-table) table +::: + + +## The `target` table +The target table is a table that allows for platform specific configuration. +Allowing you to make different sets of tasks or dependencies per platform. + +The target table is currently implemented for the following sub-tables: +- [`activation`](#the-activation-table) +- [`dependencies`](#the-dependencies-table) +- [`tasks`](#the-tasks-table) + +The target table is defined using `[target.PLATFORM.SUB-TABLE]`. +E.g `[target.linux-64.dependencies]` +The platform can be any of the target [platforms](#platforms) but must also be defined there. +The sub-table can be any of the specified above. + +To make it a bit more clear, lets look at an example below. +Currently, pixi combines the top level tables like `dependencies` with the target-specific ones into a single set. +Which, in the case of dependencies, can both add or overwrite dependencies. +In the example below, we have `cmake` being used for all targets but on `osx-64` a different version of python will be selected. +```toml +[dependencies] +cmake = "3.26.4" +python = "3.10" + +[target.osx-64.dependencies] +python = "3.11" +``` + +Here are some more examples: +```toml +[target.win-64.activation] +scripts = ["setup.ps1"] + +[target.win-64.dependencies] +msmpi = "~=10.1.1" + +[target.win-64.build-dependecies] +vs2022_win-64 = "19.36.32532" + +[target.win-64.tasks] +tmp = "echo $TEMP" + +[target.osx-64.dependencies] +clang = ">=16.0.6" +``` diff --git a/docs/examples/cpp-sdl.mdx b/docs/examples/cpp-sdl.mdx index 58c8f37bc..cd5602582 100644 --- a/docs/examples/cpp-sdl.mdx +++ b/docs/examples/cpp-sdl.mdx @@ -23,7 +23,7 @@ Run the `start` command pixi run start ``` -Using the [`depends_on`](/advanced/advanced_tasks#depends-on) feature you only needed to run the `start` task but under water it is running the following tasks. +Using the [`depends_on`](../advanced/advanced_tasks#depends-on) feature you only needed to run the `start` task but under water it is running the following tasks. ```shell # Configure the CMake project diff --git a/docs/overview.mdx b/docs/overview.mdx index 52f20ca1e..f6661753e 100644 --- a/docs/overview.mdx +++ b/docs/overview.mdx @@ -1,43 +1,143 @@ --- -part: Overview -title: Pixi +part: pixi +title: Getting Started description: Package management made easy --- -Explore pixi's documentation to find how to get started, how its used and why we build it. +Pixi is a package management tool for developers. +It allows the developer to install libraries and applications a reproducible way. +Use pixi cross-platform, on Windows, Mac and Linux. + +# Installation + +To install pixi you can run the following command in your terminal: + + + + ```bash + curl -fsSL https://pixi.sh/install.sh | bash + ``` + + The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `~/.pixi/bin`. + If this directory does not already exist, the script will create it. + + The script will also update your `~/.bash_profile` to include `~/.pixi/bin` in your PATH, allowing you to invoke the `pixi` command from anywhere. + + + + ```shell + iwr -useb https://pixi.sh/install.ps1 | iex + ``` + + The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `LocalAppData/pixi/bin`. + If this directory does not already exist, the script will create it. + + The command will also automatically add `LocalAppData/pixi/bin` to your path allowing you to invoke `pixi` from anywhere. + + + + +:::tip + +You might need to restart your terminal or source your shell for the changes to take effect. + +::: + +# Autocompletion + +To get autocompletion run: + + + + ```shell + # Pick your shell (use `echo $SHELL` to find the shell you are using.): + echo 'eval "$(pixi completion --shell bash)"' >> ~/.bashrc + echo 'eval "$(pixi completion --shell zsh)"' >> ~/.zshrc + echo 'pixi completion --shell fish | source' >> ~/.config/fish/config.fish + echo 'eval (pixi completion --shell elvish | slurp)' >> ~/.elvish/rc.elv + ``` + + + ```shell + Add-Content -Path $PROFILE -Value 'Invoke-Expression (&pixi completion --shell powershell)' + ``` + + + +And then restart the shell or source the shell config file. + +## Alternative installation methods + +Although we recommend installing pixi through the above method we also provide additional installation methods. + +### Homebrew + +Pixi is available via homebrew. To install pixi via homebrew simply run: + +```shell +brew install pixi +``` + +### Windows installer + +We provide an `msi` installer on [our Github releases page](https://github.com/prefix-dev/pixi/releases/latest). +The installer will download pixi and add it to the path. + +### Install from source + +pixi is 100% written in Rust and therefore it can be installed, build and +tested with cargo. +To start using pixi from a source build run: + +```shell +cargo install --locked --git https://github.com/prefix-dev/pixi.git +``` + +or when you want to make changes use: + +```shell +cargo build +cargo test +``` + +If you have any issues building because of the dependency on `rattler` checkout +it's [compile steps](https://github.com/mamba-org/rattler/tree/main#give-it-a-try) + +## Uninstall + +To uninstall pixi from you system, simply remove the binary. + + + + ```shell + rm ~/.pixi/bin/pixi + ``` + + + ```shell + $PIXI_BIN = "$Env:LocalAppData\pixi\bin\pixi"; Remove-Item -Path $PIXI_BIN + ``` + + + +After this command you can still use the tools you installed with pixi. +To remove these as well just remove the whole `~/.pixi` directory and remove the directory from your path. - - - - - diff --git a/docs/vision.mdx b/docs/vision.mdx index a78bfb6b9..9ff36c81c 100644 --- a/docs/vision.mdx +++ b/docs/vision.mdx @@ -1,5 +1,5 @@ --- -part: Pixi Vision +part: pixi title: Pixi Vision description: What is the vision for pixi? --- From 14c3736885ddb923e4fb40158c93c7701604a4b0 Mon Sep 17 00:00:00 2001 From: Ruben Arts Date: Tue, 26 Sep 2023 09:22:48 +0200 Subject: [PATCH 2/2] misc: align cli docs with cms --- docs/cli.mdx | 60 +++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 52 insertions(+), 8 deletions(-) diff --git a/docs/cli.mdx b/docs/cli.mdx index 7780c15ce..0b8dd813b 100644 --- a/docs/cli.mdx +++ b/docs/cli.mdx @@ -85,9 +85,11 @@ pixi run --manifest-path ~/myproject/pixi.toml python pixi run build ``` -> **Note:** In `pixi` the [`deno_task_shell`](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) is the underlying runner of the run command. -> Checkout their [documentation](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) for the syntax and available commands. -> This is done so that the run commands can be run across all platforms. +:::info +In `pixi` the [`deno_task_shell`](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) is the underlying runner of the run command. +Checkout their [documentation](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) for the syntax and available commands. +This is done so that the run commands can be run across all platforms. +::: ## `task` @@ -142,9 +144,11 @@ cow = "cowpy \"Hello User\"" moo = { depends_on = ["cow"] } ``` -> **Note:** In `pixi` the [`deno_task_shell`](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) is the underlying runner of the tasks. -> Checkout their [documentation](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) for the syntax and available commands. -> This is done so that the tasks defined can be run across all platforms. +:::info +In `pixi` the [`deno_task_shell`](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) is the underlying runner of the tasks. +Checkout their [documentation](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) for the syntax and available commands. +This is done so that the tasks defined can be run across all platforms. +::: ## `shell` @@ -194,7 +198,9 @@ This command is used to authenticate the user's access to remote hosts such as ` Store authentication information for given host. -> **Note:** The host is real hostname not a channel. +:::tip +The host is real hostname not a channel. +::: #### Options @@ -221,7 +227,12 @@ pixi auth logout repo.prefix.dev pixi auth logout anaconda.org ``` -## `global install` +## `global` + +Global is the main entry point for the part of pixi that executes on the +global(system) level. + +### `global install` This command installs a package into its own environment and adds the binary to `PATH`, allowing you to access it anywhere on your system without activating the environment. @@ -245,6 +256,39 @@ pixi global install python=3.11.0=h10a6764_1_cpython After using global install, you can use the package you installed anywhere on your system. +### `global info` + +This command shows the current installed global environments including what binaries come with it. +A global installed package/environment can possibly contain multiple binaries. +Here is an example of a few installed packages: +``` +> pixi global info +Globally installed binary packages: + - [package] starship + - [bin] starship + - [package] pre-commit + - [bin] pre-commit + - [package] grayskull + - [bin] grayskull + - [bin] greyskull + - [bin] conda-grayskull + - [bin] conda-greyskull + - [package] zsh + - [bin] zsh + - [bin] zsh-5 +``` + +### `global remove` + +Removes a package previously installed into a globally accessible location via +`pixi global install` + +Use `pixi global info` to find out what the package name is that belongs to the tool you want to remove. + +``` +pixi global remove pre-commit +``` + ## `project` This subcommand allows you to modify the project configuration through the command line interface.