From 86d38898ae3198f35e4d33cd7992470b40f4e385 Mon Sep 17 00:00:00 2001 From: Swastik Patel Date: Wed, 16 Jul 2025 00:56:05 +0530 Subject: [PATCH 1/4] docs: update introduction with pixi-extensions --- docs/integration/extensions/introduction.md | 115 +++++++++++++++++++- 1 file changed, 114 insertions(+), 1 deletion(-) diff --git a/docs/integration/extensions/introduction.md b/docs/integration/extensions/introduction.md index e7ce3efde4..7c3f46be03 100644 --- a/docs/integration/extensions/introduction.md +++ b/docs/integration/extensions/introduction.md @@ -1,3 +1,116 @@ +# Pixi Extensions + `Pixi` allows you to extend its functionality with various extensions. -When executing e.g. `pixi diff`, Pixi will search for the executable `pixi-diff` in your PATH. +When executing e.g. `pixi diff`, Pixi will search for the executable `pixi-diff` in your PATH and in your pixi global directories. Then it will execute it by passing any additional arguments to it. + +## How Extensions Work + +Pixi extensions are standalone executables that follow a simple naming convention: they must be named `pixi-{command}` where `{command}` is the name of the subcommand you want to add. When you run `pixi {command}`, pixi will automatically discover and execute the corresponding `pixi-{command}` executable. + +For example: +- `pixi diff` → looks for `pixi-diff` executable +- `pixi pack` → looks for `pixi-pack` executable +- `pixi deploy` → looks for `pixi-deploy` executable + +## Extension Discovery + +Pixi discovers extensions by searching for `pixi-*` executables in the following locations, in order: + +### 1. PATH Environment Variable +Pixi searches all directories in your `PATH` environment variable for executables with the `pixi-` prefix. + +### 2. Pixi Global Directories +Pixi also searches in directories managed by `pixi global`, which allows for organized extension management without cluttering your system PATH. + +When you run `pixi --help`, all discovered extensions are automatically listed in the "Available Extensions" section, making them easily discoverable alongside built-in commands. + +## Installing Extensions + +### Using Pixi Global (Recommended) + +The easiest way to install pixi extensions is using `pixi global install`: + +```bash +# Install a single extension +pixi global install pixi-pack + +# Install multiple extensions at once +pixi global install pixi-pack pixi-diff rattler-build +``` + +This approach has several advantages: +- **Isolated environments**: Each extension gets its own environment, preventing dependency conflicts +- **Automatic discovery**: Extensions are automatically found by pixi without modifying PATH +- **Easy management**: Use `pixi global list` and `pixi global remove` to manage extensions +- **Consistent experience**: Extensions appear in `pixi --help` just like built-in commands + +### Manual Installation + +You can also install extensions manually by placing the executable in any directory in your PATH: + +```bash +# Download or build the extension +curl -L https://github.com/user/pixi-myext/releases/download/v1.0.0/pixi-myext -o pixi-myext +chmod +x pixi-myext +mv pixi-myext ~/.local/bin/ +``` + +## Contributing Extensions + +### Creating an Extension + +1. **Choose a descriptive name**: Your extension should be named `pixi-{command}` where `{command}` clearly describes its functionality. + +2. **Create the executable**: Extensions can be written in any language (Rust, Python, shell scripts, etc.) as long as they produce an executable binary. + +3. **Handle arguments**: Extensions receive all arguments passed after the command name. + +### Example: Simple Python Extension + +```python +#!/usr/bin/env python3 +import sys + +def main(): + name = sys.argv[1] if len(sys.argv) > 1 else "World" + print(f"Hello, {name}!") + +if __name__ == "__main__": + main() +``` + +Save this as `pixi-hello`, make it executable (`chmod +x pixi-hello`), and place it in your PATH. + +Usage: `pixi hello Alice` outputs `Hello, Alice!` + +## Best Practices + +- **Use standard argument parsing**: Libraries like `clap` (Rust) or `argparse` (Python) provide consistent behavior +- **Support `--help`**: Users expect this standard flag +- **Follow UNIX conventions**: Use exit code 0 for success, non-zero for errors +- **Work with pixi environments**: Extensions should respect pixi's environment management + +## Command Suggestions + +Pixi includes intelligent command suggestions powered by string similarity. If you mistype a command name, pixi will suggest the closest match from both built-in commands and available extensions: + +```bash +$ pixi pck +error: unrecognized subcommand 'pck` +tip: a similar subcommand exists: 'pack' +``` + +This works for both built-in commands and any extensions you have installed, making extension discovery seamless. + +## Getting Help + +- **List available extensions**: Run `pixi --help` to see all available extensions +- **Community**: Join the [pixi Discord](https://discord.gg/kKV8ZxyzY4) for discussions and support + +## See Also + +- [Pixi Pack](../pixi_pack.md) - Official extension for packaging environments +- [Pixi Diff](pixi_diff.md) - Compare lock files and environments +- [Pixi Inject](pixi_inject.md) - Inject dependencies into existing environments +- [Global Tools](../../global_tools/introduction.md) - Managing global tool installations From b606bdb9027fb6210f8fb897b716fa4d382a50e5 Mon Sep 17 00:00:00 2001 From: Swastik Patel Date: Wed, 16 Jul 2025 01:06:28 +0530 Subject: [PATCH 2/4] misc: fix CI --- docs/integration/extensions/introduction.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/integration/extensions/introduction.md b/docs/integration/extensions/introduction.md index 7c3f46be03..b86055a92f 100644 --- a/docs/integration/extensions/introduction.md +++ b/docs/integration/extensions/introduction.md @@ -110,7 +110,6 @@ This works for both built-in commands and any extensions you have installed, mak ## See Also -- [Pixi Pack](../pixi_pack.md) - Official extension for packaging environments - [Pixi Diff](pixi_diff.md) - Compare lock files and environments - [Pixi Inject](pixi_inject.md) - Inject dependencies into existing environments - [Global Tools](../../global_tools/introduction.md) - Managing global tool installations From 7edd65bb7f471b34b886d053b4fa8bf08ec2f3af Mon Sep 17 00:00:00 2001 From: Swastik Patel Date: Fri, 18 Jul 2025 17:53:50 +0530 Subject: [PATCH 3/4] misc: minor changes --- docs/integration/extensions/introduction.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/integration/extensions/introduction.md b/docs/integration/extensions/introduction.md index b86055a92f..660518c95d 100644 --- a/docs/integration/extensions/introduction.md +++ b/docs/integration/extensions/introduction.md @@ -6,7 +6,7 @@ Then it will execute it by passing any additional arguments to it. ## How Extensions Work -Pixi extensions are standalone executables that follow a simple naming convention: they must be named `pixi-{command}` where `{command}` is the name of the subcommand you want to add. When you run `pixi {command}`, pixi will automatically discover and execute the corresponding `pixi-{command}` executable. +Pixi extensions are standalone executables that follow a simple naming convention: they must be named `pixi-{command}` where `{command}` is the name of the subcommand you want to add. When you run `pixi {command}`, Pixi will automatically discover and execute the corresponding `pixi-{command}` executable. For example: - `pixi diff` → looks for `pixi-diff` executable @@ -29,19 +29,19 @@ When you run `pixi --help`, all discovered extensions are automatically listed i ### Using Pixi Global (Recommended) -The easiest way to install pixi extensions is using `pixi global install`: +The easiest way to install Pixi extensions is using `pixi global install`: ```bash # Install a single extension pixi global install pixi-pack # Install multiple extensions at once -pixi global install pixi-pack pixi-diff rattler-build +pixi global install pixi-pack pixi-diff ``` This approach has several advantages: - **Isolated environments**: Each extension gets its own environment, preventing dependency conflicts -- **Automatic discovery**: Extensions are automatically found by pixi without modifying PATH +- **Automatic discovery**: Extensions are automatically found by Pixi without modifying PATH - **Easy management**: Use `pixi global list` and `pixi global remove` to manage extensions - **Consistent experience**: Extensions appear in `pixi --help` just like built-in commands @@ -89,11 +89,11 @@ Usage: `pixi hello Alice` outputs `Hello, Alice!` - **Use standard argument parsing**: Libraries like `clap` (Rust) or `argparse` (Python) provide consistent behavior - **Support `--help`**: Users expect this standard flag - **Follow UNIX conventions**: Use exit code 0 for success, non-zero for errors -- **Work with pixi environments**: Extensions should respect pixi's environment management +- **Work with Pixi environments**: Extensions should respect Pixi's environment management ## Command Suggestions -Pixi includes intelligent command suggestions powered by string similarity. If you mistype a command name, pixi will suggest the closest match from both built-in commands and available extensions: +Pixi includes intelligent command suggestions powered by string similarity. If you mistype a command name, Pixi will suggest the closest match from both built-in commands and available extensions: ```bash $ pixi pck @@ -106,7 +106,7 @@ This works for both built-in commands and any extensions you have installed, mak ## Getting Help - **List available extensions**: Run `pixi --help` to see all available extensions -- **Community**: Join the [pixi Discord](https://discord.gg/kKV8ZxyzY4) for discussions and support +- **Community**: Join our [Discord](https://discord.gg/kKV8ZxyzY4) for discussions and support ## See Also From 669d5092cd6ccc3012ed99703c1f338b6dd81631 Mon Sep 17 00:00:00 2001 From: Lucas Colley Date: Tue, 29 Jul 2025 11:24:09 +0100 Subject: [PATCH 4/4] tweak headings --- docs/integration/extensions/introduction.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/integration/extensions/introduction.md b/docs/integration/extensions/introduction.md index 660518c95d..24102f2c41 100644 --- a/docs/integration/extensions/introduction.md +++ b/docs/integration/extensions/introduction.md @@ -20,14 +20,14 @@ Pixi discovers extensions by searching for `pixi-*` executables in the following ### 1. PATH Environment Variable Pixi searches all directories in your `PATH` environment variable for executables with the `pixi-` prefix. -### 2. Pixi Global Directories +### 2. `pixi global` Directories Pixi also searches in directories managed by `pixi global`, which allows for organized extension management without cluttering your system PATH. When you run `pixi --help`, all discovered extensions are automatically listed in the "Available Extensions" section, making them easily discoverable alongside built-in commands. ## Installing Extensions -### Using Pixi Global (Recommended) +### Using `pixi global` (Recommended) The easiest way to install Pixi extensions is using `pixi global install`: