docs: first iteration on the documentation of the global feature

docs/features/global_tools.md

@@ -0,0 +1,140 @@
+# Pixi Global Tool Installation
+
+With `pixi global`, users can manage globally installed tools in a way that makes them available from any directory.
+This means that the pixi environment will be placed in a global location, and the tools will be exposed to the system `PATH`, allowing you to run them from the command line.
+
+!!! note
+    The design for global tools is still in progress, and the commands and behavior may change in future releases.
+    The proposal for the global tools feature can be found [here](../design_proposals/pixi_global_manifest.md).
+
+## The Global Manifest
+Since `v0.31.0` pixi has a new manifest file that will be created in the global directory (default: `$HOME/.pixi/manifests/pixi-global.toml`).
+This file will contain the list of environments that are installed globally, their dependencies and exposed binaries.
+The manifest can be edited, synced, checked in to a version control system, and shared with others.
+
+A simple version looks like this:
+```toml
+[envs.vim]
+channels = ["conda-forge"]
+dependencies = { vim = "*" } # (1)!
+exposed = { vimdiff = "vimdiff", vim = "vim" } # (2)!
+
+[envs.gh]
+channels = ["conda-forge"]
+dependencies = { gh = "*" }
+exposed = { gh = "gh" }
+
+[envs.python]
+channels = ["conda-forge"]
+dependencies = { python = ">=3.10,<3.11" }
+exposed = { python310 = "python" } # (3)!
+```
+
+1. Dependencies are the packages that will be installed in the environment. You can specify the version or use a wildcard.
+2. The exposed binaries are the ones that will be available in the system path. `vim` has multiple so they will all be exposed.
+3. Here python is exposed as `python310` to avoid conflicts with other python installations. You can give it any name you want.
+
+### Channels
+The channels are the conda channels that will be used to search for the packages.
+There is a priority to these, so the first one will have the highest priority, if a package is not found in that channel the next one will be used.
+More information on channels can be found [here](../advanced/channel_priority.md).
+
+### Exposed
+The exposed binaries are the ones that will be available in the system `PATH`.
+This is useful when the package has multiple binaries, but you want to get a select few, or you want to expose it with a different name.
+For example, the `python` package has multiple binaries, but you only want to expose the interpreter.
+You can do this with the following entry:
+```toml
+[envs.python]
+channels = ["conda-forge"]
+dependencies = { python = ">=3.10,<3.11" }
+exposed = { python310 = "python" }
+```
+This also helps when you want to access binaries of dependencies of the package.
+For example, the `ansible` package doesn't contain the `ansible` binary, but its dependency `ansible-core`does.
+So you can still expose it with:
+```
+pixi global expose add --environment ansible ansible=ansible
+```
+
+### Dependencies
+Dependencies are the **Conda** packages that will be installed into your environment. For example, running:
+```
+pixi global install "python<3.12"
+```
+creates the following entry in the manifest:
+```toml
+[envs.vim]
+channels = ["conda-forge"]
+dependencies = { python = "<3.12" }
+# ...
+```
+Typically, you'd specify just the tool you're installing, but you can add more packages if needed.
+Defining the environment to install into will allow you to add multiple dependencies at once.
+For example, running:
+```shell
+pixi global install --environment my-env git vim python
+```
+will create the following entry in the manifest:
+```toml
+[envs.my-env]
+channels = ["conda-forge"]
+dependencies = { git = "*", vim = "*", python = "*" }
+# ...
+```
+
+
+### Example: Creating a Data Science Sandbox Environment
+You can create an environment with multiple tools using the following command:
+```shell
+pixi global install --environment data-science --expose jupyter=jupyter --expose ipython=ipython jupyter numpy pandas matplotlib ipython
+```
+This command generates the following entry in the manifest:
+```toml
+[envs.data-science]
+channels = ["conda-forge"]
+dependencies = { jupyter = "*", numpy = "*", pandas = "*", matplotlib = "*", ipython = "*" }
+exposed = { jupyter = "jupyter", ipython = "ipython" }
+```
+In this setup, both `jupyter` and `ipython` are exposed from the `data-science` environment, allowing you to run:
+```shell
+> ipython
+# Or
+> jupyter lab
+```
+These commands will be available globally, making it easy to access your preferred tools without switching environments.
+
+### Example: Adding a series of tools at once
+Without specifying an environment, you can add multiple tools at once:
+```shell
+pixi global install pixi-pack rattler-build
+```
+This command generates the following entry in the manifest:
+```toml
+[envs.pixi-pack]
+channels = ["conda-forge"]
+dependencies= { pixi-pack = "*" }
+exposed = { pixi-pack = "pixi-pack" }
+
+[envs.rattler-build]
+channels = ["conda-forge"]
+dependencies = { rattler-build = "*" }
+exposed = { rattler-build = "rattler-build" }
+```
+Creating two separate non-interfering environments, while exposing only the minimum required binaries.
+
+### Example: Install packages for a different platform
+You can install packages for a different platform using the `--platform` flag.
+This is useful when you want to install packages for a different platform, such as `osx-64` packages on `osx-arm64`.
+For example, running this on `osx-arm64`:
+```shell
+pixi global install --platform osx-64 python
+```
+will create the following entry in the manifest:
+```toml
+[envs.python]
+channels = ["conda-forge"]
+platforms = ["osx-64"]
+dependencies = { python = "*" }
+# ...
+```

docs/reference/cli.md

@@ -914,8 +914,9 @@ pixi config unset repodata-config.disable-zstd --system
 
 ## `global`
 
-Global is the main entry point for the part of pixi that executes on the
-global(system) level.
+Global is the main entry point for the part of pixi that executes on the global(system) level.
+All commands in this section are used to manage global installations of packages and environments through the global manifest.
+More info on the global manifest can be found [here](../features/global_tools.md).
 
 !!! tip
     Binaries and environments installed globally are stored in `~/.pixi`
@@ -924,17 +925,20 @@ global(system) level.
 
 ### `global install`
 
-This command installs package(s) into its own environment and adds the binary to `PATH`, allowing you to access it anywhere on your system without activating the environment.
+This command installs package(s) into its own environment and adds the binary to `PATH`.
+Allowing you to access it anywhere on your system without activating the environment.
 
 ##### Arguments
 
-1.`<PACKAGE>`: The package(s) to install, this can also be a version constraint.
+1.`[PACKAGE]`: The package(s) to install, this can also be a version constraint.
 
 ##### 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)
-- `--no-activation`: Do not insert conda_prefix, path modifications, and activation script into the installed executable script.
+- `--environment <ENVIRONMENT> (-e)`: The environment to install the package into. (default: name of the tool)
+- `--expose <EXPOSE>`: A mapping from name to the binary to expose to the system. (default: name of the tool)
+- `--assume-yes (-y)`: Answer yes to all questions. (default: false)
 
 ```shell
 pixi global install ruff
@@ -953,9 +957,6 @@ 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
-
-# Install without inserting activation code into the executable script
-pixi global install ruff --no-activation
 ```
 
 !!! tip
@@ -969,85 +970,77 @@ After using global install, you can use the package you installed anywhere on yo
 ### `global list`
 
 This command shows the current installed global environments including what binaries come with it.
-A global installed package/environment can possibly contain multiple binaries and
-they will be listed out in the command output. Here is an example of a few installed packages:
-
-```
-> pixi global list
-Global install location: /home/hanabi/.pixi
-├── bat 0.24.0
-|   └─ exec: bat
-├── conda-smithy 3.31.1
-|   └─ exec: feedstocks, conda-smithy
-├── rattler-build 0.13.0
-|   └─ exec: rattler-build
-├── ripgrep 14.1.0
-|   └─ exec: rg
-└── uv 0.1.17
-    └─ exec: uv
-```
-
-### `global upgrade`
-
-This command upgrades a globally installed package (to the latest version by default).
-
-##### Arguments
-
-1. `<PACKAGE>`: The package to upgrade.
+A global installed package/environment can possibly contain multiple exposed binaries and they will be listed out in the command output.
 
 ##### Options
+- `--environment <ENVIRONMENT> (-e)`: The environment to install the package into. (default: name of the tool)
+- `--assume-yes (-y)`: Answer yes to all questions. (default: false)
 
-- `--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)
+We'll only show the dependencies and exposed binaries of the environment if they differ from the environment name.
+Here is an example of a few installed packages:
 
-```shell
-pixi global upgrade ruff
-pixi global upgrade --channel conda-forge --channel bioconda trackplot
-# Or in a more concise form
-pixi global upgrade -c conda-forge -c bioconda trackplot
-
-# Conda matchspec is supported
-# You can specify the version to upgrade to when you don't want the latest version
-# or you can even use it to downgrade a globally installed package
-pixi global upgrade python=3.10
+```
+> pixi global list
+Global environments at /home/user/.pixi:
+├── gh: 2.57.0
+├── pixi-pack: 0.1.8
+├── python: 3.11.0
+│   └─ exposes: 2to3, 2to3-3.11, idle3, idle3.11, pydoc, pydoc3, pydoc3.11, python, python3, python3-config, python3.1, python3.11, python3.11-config
+├── rattler-build: 0.22.0
+├── ripgrep: 14.1.0
+│   └─ exposes: rg
+├── vim: 9.1.0611
+│   └─ exposes: ex, rview, rvim, view, vim, vimdiff, vimtutor, xxd
+└── zoxide: 0.9.6
 ```
 
-### `global upgrade-all`
+Here is an example of list of a single environment:
+```
+> pixi g list -e pixi-pack
+The 'pixi-pack' environment has 8 packages:
+Package          Version    Build        Size
+_libgcc_mutex    0.1        conda_forge  2.5 KiB
+_openmp_mutex    4.5        2_gnu        23.1 KiB
+ca-certificates  2024.8.30  hbcca054_0   155.3 KiB
+libgcc           14.1.0     h77fa898_1   826.5 KiB
+libgcc-ng        14.1.0     h69a702a_1   50.9 KiB
+libgomp          14.1.0     h77fa898_1   449.4 KiB
+openssl          3.3.2      hb9d3cd8_0   2.8 MiB
+pixi-pack        0.1.8      hc762bcd_0   4.3 MiB
+Package          Version    Build        Size
+
+Exposes:
+pixi-pack
+Channels:
+conda-forge
+Platform: linux-64
+```
 
-This command upgrades all globally installed packages to their latest version.
+### `global sync`
+As the global manifest can be manually edited, this command will sync the global manifest with the current state of the global environment.
+You can modify the manifest in `$HOME/manifests/pixi_global.toml`.
 
 ##### Options
-
-- `--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)
+- `--assume-yes (-y)`: Answer yes to all questions. (default: false)
 
 ```shell
-pixi global upgrade-all
-pixi global upgrade-all --channel conda-forge --channel bioconda
-# Or in a more concise form
-pixi global upgrade-all -c conda-forge -c bioconda trackplot
+pixi global sync
 ```
 
-### `global remove`
-
-Removes a package previously installed into a globally accessible location via
-`pixi global install`
+### `global upgrade`
 
-Use `pixi global info` to find out what the package name is that belongs to the tool you want to remove.
+This command will be replaced, use `global install` instead.
+We'll bring it back as `pixi global update` ASAP.
 
-##### Arguments
+### `global upgrade-all`
 
-1. `<PACKAGE>`: The package(s) to remove.
+This command will be replaced, use `global install` instead.
+We'll bring it back as `pixi global update-all` ASAP.
 
-```shell
-pixi global remove pre-commit
+### `global remove`
 
-# multiple packages can be removed at once
-pixi global remove pre-commit starship
-```
+This command will be replaced, modify the `pixi_manifest.toml` by hand to remove the tool.
+We'll bring it back as `pixi global uninstall` ASAP.
 
 ## `project`
 

mkdocs.yml

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

src/prefix.rs

@@ -5,6 +5,7 @@ use std::{
 };
 
 use futures::{stream::FuturesUnordered, StreamExt};
+use itertools::Itertools;
 use miette::{Context, IntoDiagnostic};
 use pixi_utils::strip_executable_extension;
 use rattler_conda_types::{PackageName, Platform, PrefixRecord};
@@ -125,7 +126,14 @@ impl Prefix {
                     })
             })
             .collect();
-        tracing::debug!("Found executables: {:?}", executables);
+        tracing::debug!(
+            "In packages: {}, found executables: {:?} ",
+            prefix_packages
+                .iter()
+                .map(|rec| rec.repodata_record.package_record.name.as_normalized())
+                .join(", "),
+            executables
+        );
         executables
     }