Conda's Prefixes Blogpost (#148)

Co-authored-by: Katherine Kinnaman <[email protected]>
Co-authored-by: Bianca Henderson <[email protected]>
Co-authored-by: Paul Yim <[email protected]>

blog/2024-05-20-prefixes.mdx

@@ -0,0 +1,158 @@
+---
+title: "Developer Guide: A Tale of Five Prefixes"
+slug: 2024-05-20-prefixes
+authors: [kenodegard, chatgpt]
+tags: [conda, context, prefix, prefixes, api]
+description: Prefixes, prefixes, prefixes! All the prefixes!
+image: img/blog/2024-05-20-prefixes/banner.png
+---
+
+[conda-env-pr]: https://github.com/conda/conda/pull/2950
+[conda-4.2.0]: https://github.com/conda/conda/releases/tag/4.2.0
+[condarc]: https://docs.conda.io/projects/conda/en/stable/user-guide/configuration/use-condarc.html
+
+In the realm of package management and environment configuration, `conda` has
+emerged as a versatile tool empowering developers with environment management. A
+pivotal aspect of `conda`'s architecture lies in its prefix system, which
+underwent a significant evolution over its previous versions, transforming `conda` from a
+simple package manager into a sprawling environment manager. In this technical
+discourse, we delve into the intricacies of `conda`'s prefix system, shedding
+light on its evolution and the five distinct prefixes delineated within the
+`conda` source code.
+
+<!-- truncate -->
+
+In the nascent stages of `conda`'s development, its primary functionality
+revolved around installing packages into a singular environment, at the time
+referred to as the `root` environment. This era, marked by `conda` versions
+preceding 4.2.0, laid the groundwork for `conda`'s subsequent evolution as an
+environment manager.
+
+With the advent of [`conda 4.2.0`][conda-4.2.0] and beyond, a paradigm shift
+occurred when the `conda-env` project was [merged][conda-env-pr] with the
+`conda` project, elevating `conda` from a mere package manager to a
+comprehensive environment manager. This pivotal transformation bestowed upon
+`conda` the capability to create and manage separate environments, fostering
+modularity and flexibility in development workflows.
+
+Delving into `conda`'s Git history via `git blame` provides invaluable insights
+into the timeline of the prefix system evolution. By tracing the commit history,
+we unearthed pivotal moments that introduced and refined the various prefixes
+integral to `conda`'s architecture. The history reveals two distinct phases in
+the evolution of `conda`'s prefix system. The first phase occurred early on in
+`conda 1.x` and the second phase much later in `conda 4.x` with the merging of
+`conda-env` with `conda`.
+
+Here are the five prefixes defined within conda, ordered from the lowest level (system-level
+and least configurable) to the highest level (user-level and most configurable):
+
+### `conda.base.context.context.conda_prefix`
+
+Introduced in `conda 4.2.0` (see https://github.com/conda/conda/commit/6e730cc)
+as part of the private environment effort, which has since been abandoned and
+deprecated.
+
+The `conda_prefix` lies at the heart of the prefix system, denoting the
+installation directory of `conda` itself. Typically, this aligns with the
+location of the `base` environment and is equivalent to Python's `sys.prefix`
+value.
+
+:::info
+
+Use this any time you need to interact with the `conda` installation itself.
+
+:::
+
+### `conda.base.context.context.root_prefix`
+
+:::note[Previously]
+
+&nbsp;●&nbsp;&nbsp;&nbsp;`conda.config.ROOT_DIR`\
+&nbsp;↓&nbsp;&nbsp;&nbsp;`conda.config.root_dir`\
+&nbsp;○&nbsp;&nbsp;&nbsp;`conda.base.context.context.root_prefix`
+
+:::
+
+Introduced in `conda 1.1.0` (see https://github.com/conda/conda/commit/d2b370a)
+and was originally intended for testing purposes only.
+
+The `root_prefix` serves as a [configurable value][condarc], most easily
+configurable in the user's `~/.condarc` file. In the absence of user-defined
+preferences, it defaults to the `conda_prefix`.
+
+:::warning
+
+Avoid using this. This is a contender for deprecation.
+
+:::
+
+### `conda.base.context.context.active_prefix`
+
+Introduced in `conda 4.4.0` (see https://github.com/conda/conda/commit/cbbe81f)
+as part of cleaning up the `conda info` output.
+
+Reflecting the currently active environment, the `active_prefix` is determined
+by the `$CONDA_PREFIX` environment variable, which is set by the `conda activate`
+and `conda deactivate` commands.
+
+:::warning
+
+Avoid using this. Treat this as an internal value.
+
+:::
+
+### `conda.base.context.context.default_prefix`
+
+:::note[Previously]
+
+&nbsp;●&nbsp;&nbsp;&nbsp;`conda.anaconda.default_environment`\
+&nbsp;↓&nbsp;&nbsp;&nbsp;`conda.config.default_environment`\
+&nbsp;↓&nbsp;&nbsp;&nbsp;`conda.config.DEFAULT_ENV_PREFIX`\
+&nbsp;↓&nbsp;&nbsp;&nbsp;`conda.config.default_prefix`\
+&nbsp;○&nbsp;&nbsp;&nbsp;`conda.base.context.context.default_prefix`
+
+:::
+
+Introduced in `conda 1.1.0` (see https://github.com/conda/conda/commit/acd8144)
+as part of a larger configuration overhaul.
+
+The `default_prefix` is the same as `active_prefix` when an environment is
+active. When no environment is active the default environment is returned
+(which can be overridden via the `$CONDA_DEFAULT_ENV` environment variable)
+and otherwise defaults to the `root_prefix`.
+
+:::warning
+
+Avoid using this. Treat this as an internal value.
+
+:::
+
+### `conda.base.context.context.target_prefix`
+
+:::note[Previously]
+
+&nbsp;●&nbsp;&nbsp;&nbsp;`conda.cli.utils.get_prefix()`\
+&nbsp;↓&nbsp;&nbsp;&nbsp;`conda.cli.common.get_prefix()`\
+&nbsp;↓&nbsp;&nbsp;&nbsp;`conda.base.context.context.prefix`\
+&nbsp;○&nbsp;&nbsp;&nbsp;`conda.base.context.context.target_prefix`
+
+:::
+
+Introduced in `conda 1.3.0` (see https://github.com/conda/conda/commit/9fd0f4b)
+to abstract out the `--name`/`--prefix` logic from the CLI implementations.
+
+The `target_prefix` is the highest level prefix and reflects the user input
+via the CLI options, `--name` or `--prefix`. In the absence of CLI overrides,
+it defaults to the `default_prefix`.
+
+:::info
+
+Use this when you need to interact with the current environment.
+
+:::
+
+In essence, the `conda` prefix system serves as the cornerstone of its environment
+management capabilities, facilitating seamless navigation and interaction within
+the different environments a user may have created. As `conda` continues to
+evolve, understanding its prefix system remains paramount for harnessing its
+capabilities effectively and correctly.

blog/authors.yml

@@ -9,6 +9,11 @@ beeankha:
  title: Conda maintainer 🐍📦
  url: https://github.com/beeankha
  image_url: https://github.com/beeankha.png
+chatgpt:
+ name: OpenAI ChatGPT
+ title: Large Language Model 🤖
+ url: https://chatgpt.com/
+ image_url: /img/authors/openai.png
 dholth:
  name: Daniel Holth
  title: Conda maintainer

blog/news.json

@@ -1 +1 @@
-[{"title": "April and May 2024 Releases", "slug": "2024-05-13-april-and-may-releases", "authors": ["beeankha"], "tags": ["announcement", "conda", "conda-build"], "description": "Conda 24.4.0, conda 24.5.0, and conda-build 24.5.0 have been released! \ud83c\udf89\n", "image": "img/blog/2024-05-13-april-and-may-releases/banner.png", "date": "2024-05-13T00:00:00"}, {"title": "March 2024 Releases", "slug": "2024-03-20-march-releases", "authors": ["beeankha"], "tags": ["announcement", "conda", "conda-build"], "description": "Conda 24.3.0 and conda-build 24.3.0 have been released! \ud83c\udf89\n", "image": "img/blog/2024-03-20-march-releases/banner.png", "date": "2024-03-20T00:00:00"}, {"title": "January 2024 Releases", "slug": "2024-01-31-january-releases", "authors": ["kenodegard"], "tags": ["announcement", "conda", "conda-build", "conda-libmamba-solver", "conda-index"], "description": "Conda 24.1.0/.1/.2, conda-build 24.1.0/.1/.2, conda-libmamba-solver 24.1.0, and conda-index 0.4.0 have been released! \ud83c\udf89\n", "image": "img/blog/2024-01-31-january-releases/banner.jpg", "date": "2024-01-31T00:00:00"}, {"title": "Conda is moving to Mastodon & LinkedIn", "slug": "2023-12-27-social-move", "authors": ["tnabtaf"], "tags": ["announcement", "conda", "twitter", "mastodon", "linkein"], "description": "Conda is retiring its Twitter account. Please join us on Mastodon and LinkedIn\n", "image": "img/blog/2023-12-27-social-move/banner.png", "date": "2023-12-27T00:00:00"}, {"title": "November 2023 Releases", "slug": "2023-12-07-november-releases", "authors": ["kenodegard"], "tags": ["announcement", "conda", "conda-build", "conda-libmamba-solver"], "description": "Conda 23.11.0, conda-build 3.28.0/3.28.1, and conda-libmamba-solver 23.11.0/23.11.1 have been released! \ud83c\udf89\n", "image": "img/blog/2023-12-07-november-releases/banner.jpg", "date": "2023-12-07T00:00:00"}]
+[{"title": "Developer Guide: A Tale of Five Prefixes", "slug": "2024-05-20-prefixes", "authors": ["kenodegard", "chatgpt"], "tags": ["conda", "context", "prefix", "prefixes", "api"], "description": "Prefixes, prefixes, prefixes! All the prefixes!", "image": "img/blog/2024-05-20-prefixes/banner.png", "date": "2024-05-20T00:00:00"}, {"title": "April and May 2024 Releases", "slug": "2024-05-13-april-and-may-releases", "authors": ["beeankha"], "tags": ["announcement", "conda", "conda-build"], "description": "Conda 24.4.0, conda 24.5.0, and conda-build 24.5.0 have been released! \ud83c\udf89\n", "image": "img/blog/2024-05-13-april-and-may-releases/banner.png", "date": "2024-05-13T00:00:00"}, {"title": "March 2024 Releases", "slug": "2024-03-20-march-releases", "authors": ["beeankha"], "tags": ["announcement", "conda", "conda-build"], "description": "Conda 24.3.0 and conda-build 24.3.0 have been released! \ud83c\udf89\n", "image": "img/blog/2024-03-20-march-releases/banner.png", "date": "2024-03-20T00:00:00"}, {"title": "January 2024 Releases", "slug": "2024-01-31-january-releases", "authors": ["kenodegard"], "tags": ["announcement", "conda", "conda-build", "conda-libmamba-solver", "conda-index"], "description": "Conda 24.1.0/.1/.2, conda-build 24.1.0/.1/.2, conda-libmamba-solver 24.1.0, and conda-index 0.4.0 have been released! \ud83c\udf89\n", "image": "img/blog/2024-01-31-january-releases/banner.jpg", "date": "2024-01-31T00:00:00"}, {"title": "Conda is moving to Mastodon & LinkedIn", "slug": "2023-12-27-social-move", "authors": ["tnabtaf"], "tags": ["announcement", "conda", "twitter", "mastodon", "linkein"], "description": "Conda is retiring its Twitter account. Please join us on Mastodon and LinkedIn\n", "image": "img/blog/2023-12-27-social-move/banner.png", "date": "2023-12-27T00:00:00"}]