folkslinux
/
mamba
mirror of https://github.com/mamba-org/mamba.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add MatchSpec doc and fix errors (#3224) 

* Add missing spec doc

* Add 2.0 changes to doc

* Cleanup spec usage doc

* Remove outdated documentation page

* Fix doc link

* Fix backticks in docs

* Add rst pre-commit checks
This commit is contained in:
Antoine Prouvost 2024-03-08 14:44:52 +01:00 committed by GitHub
parent fd42d8dd8e
commit a00ef35675
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
12 changed files with 197 additions and 205 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.pre-commit-config.yaml
View File

@ -16,6 +16,12 @@ repos:
args: [--autofix]
- id: debug-statements
language_version: python3
- repo: https://github.com/pre-commit/pygrep-hooks
rev: v1.9.0
hooks:
- id: rst-backticks
- id: rst-directive-colons
- id: rst-inline-touching-normal
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.1.6
hooks:

2
docs/source/advanced_usage/detailed_operations.rst
View File

@ -55,7 +55,7 @@ When a package gets installed, several steps are executed:
- the package is downloaded and placed into the ``$ROOT_PREFIX/pkgs`` folder
- the package is extracted
- the package is "linked" from the `pkgs` folder into the final destination
- the package is "linked" from the ``pkgs`` folder into the final destination
When the package is linked to the final destination (for example, some newly created environment), most files are "hard"-linked. That means, there is no copy of the file created. This saves a considerable amount of disk-space when re-using the same package in multiple environments.

2
docs/source/advanced_usage/package_resolution.rst
View File

@ -59,6 +59,6 @@ If we want to install ``python 3.7.*`` we would prefer ``python 3.7 HASH_cpython
On conda-forge, we're building "variant packages" for numpy (and other packages requiring the C API of Python). This means for a given version of numpy, we'll end up with ~5 almost equivalent variant packages, for cpython 3.6, 3.7 and 3.8 as well as pypy 3.6 and 3.7.
For this example the default is the cpython build of numpy. However, currently conda-forge does not apply the down-weigthing via track_feature on the terminal node (numpy), but only in some dependency package (such as python).
For the case where we want to simply install `numpy`, we need to find which numpy variant installs the highest python package. In this case libsolv would decide for ``numpy-1.20-cpython38``.
For the case where we want to simply install ``numpy``, we need to find which numpy variant installs the highest python package. In this case libsolv would decide for ``numpy-1.20-cpython38``.
If we install ``numpy python=3.7`` we have two potential variants: ``numpy-1.20-cpython37`` and ``numpy-1.20-pypy37``. In this case we need to inspect wether one of those two builds will require exclusively packages with a track_feature applied. And indeed, the ``pypy37`` package will have a requirement on ``python_abi 3.7 *pypy`` and **all** packages matching this requirement have a track_feature, so that it will be down-weighted.

52
docs/source/developer_zone/changes-2.0.rst
View File

@ -1,4 +1,3 @@
=================
Mamba 2.0 Changes
=================
.. ...................... ..
@ -9,11 +8,10 @@ Mamba 2.0 Changes
.. - OCI registries
.. - Mirrors
.. - Own implementation repodata.json
.. - Fully feature implementation of MatchSpec
Command Line Executables
========================
------------------------
Mamba (executable)
******************
``mamba``, previously a Python executable mixing ``libmambapy``, ``conda``, and code to bridge both
@ -37,14 +35,14 @@ Breaking changes include:
- ``micromamba shell init`` root prefix parameter ``--prefix`` (``-p``) was renamed
``--root-prefix`` (``-r``).
Both options were supported in version ``1.5``.
- A new config `order_solver_request` (default true) can be used to order the dependencies passed
- A new config ``order_solver_request`` (default true) can be used to order the dependencies passed
to the solver, getting order independent solutions.
.. TODO is micromamba executable renamed mamba?
.. TODO OCI and mirrors
Libraries
=========
---------
Mamba (Python package)
**********************
In version 2.0, all tools are fully written in C++.
@ -66,19 +64,21 @@ Changes inlcude:
``ChannelContext.make_conda_compatible`` (with ``Context.instance`` as argument in most cases)
and passed explicitly to a few functions.
- A new ``Context`` independent submodule ``libmambapy.specs`` has been introduced with:
- The redesign of the ``Channel`` and a new ``UnresolvedChannel`` used to describe unresolved
channel strings.
A featureful ``libmambapy.specs.CondaURL`` is used to describe channel URLs.
- The redesign``MatchSpec``.
- The redesign of ``MatchSpec``.
The module also includes a platform enumeration, an implementation of ordered ``Version``,
and a ``VersionSpec`` to match versions.
- ``PackageInfo`` has been moved to this submodule.
Some attributes have been given a more explicit name ``fn`` > ``filename``,
``url`` > ``package_url``.
- A new ``Context`` independent submodule ``libmambapy.solver`` has been introduced with the
changes below.
A usage documentation page is available at
https://mamba.readthedocs.io/en/latest/usage/solver.html
A usage documentation page is available at :ref:`mamba_usage_solver`.
- The redesign of the ``Pool``, which is now available as ``libmambapy.solver.libsolv.Database``.
The new interfaces makes it easier to create repositories without using other ``libmambapy``
objects.
@ -89,13 +89,12 @@ Changes inlcude:
high-level free functions such as ``load_subdir_in_database`` and
``load_installed_packages_in_database``.
- The ``Solver`` has been moved to ``libmambapy.solver.libsolv.Solver``.
- All jobs, pins, and flags must be passed as a single ``libmambapy.solver.Request``.
- The outcome of solving the request is either a ``libmambapy.solver.Solution`` or a
``libmambapy.solver.libsolv.Unsolvable`` state from which rich error messages can be
extracted.
.. TODO include final decision for Channels as URLs.
For many changes, an exception throwing placeholder has ben kept to advise developpers on the new
direction to take.
@ -106,11 +105,14 @@ Due to the low usage of the C++ interface, all changes are not listed here.
The main changes are:
- Refactoring and testing of a large number of utilities into a ``util::`` namespace,
- Creation of the ``specs::`` with:
- Implementations of ``Version`` and ``VersionSpec`` for matching versions,
- A refactoring of a purely funcitonal ``Channel`` class,
- Implementaiton of a ``UnresolvedChannel`` to describe unresolved ``Channels``,
- A refactored implementation of ``MatchSpec`` using the components above.
- Creation of the ``specs::`` the items below.
A usage documentation (in Python) is available at :ref:`mamba_usage_specs`.
- Implementations of ``Version`` and ``VersionSpec`` for matching versions,
- A refactoring of a purely funcitonal ``Channel`` class,
- Implementaiton of a ``UnresolvedChannel`` to describe unresolved ``Channels``,
- A refactored implementation of ``MatchSpec`` using the components above.
- A cleanup of ``ChannelContext`` for be a light proxy and parameter holder wrapping the
``specs::Channel``.
- A new ``repodata.json`` parser using `simdjson <https://simdjson.org/>`_.
@ -118,15 +120,15 @@ The main changes are:
subnamespace and works independently of the ``Context``.
The ``solver::libsolv`` sub-namespace has also been added for full isolation of libsolv, and a
solver API without ``Context``.
The ``solver`` API redesign includes:
- A refactoring of the ``MPool`` as a ``DataBase``, fully isolates libsolv, and simplifies
repository creation.
- A refactoring and thinning of ``MRepo`` as a new ``RepoInfo``.
- A solver ``Request`` with all requirements to solve is the new way to specify jobs.
- A refactoring of ``Solver``.
- A solver outcome as either a ``Solution`` or an ``UnSolvable`` state.
A usage documentation (in Python) is available at
https://mamba.readthedocs.io/en/latest/usage/solver.html
The ``solver`` API redesign includes the items below.
A usage documentation (in Python) is available at :ref:`mamba_usage_solver`.
- A refactoring of the ``MPool`` as a ``DataBase``, fully isolates libsolv, and simplifies
repository creation.
- A refactoring and thinning of ``MRepo`` as a new ``RepoInfo``.
- A solver ``Request`` with all requirements to solve is the new way to specify jobs.
- A refactoring of ``Solver``.
- A solver outcome as either a ``Solution`` or an ``UnSolvable`` state.
- Improved downloaders.
.. TODO OCI registry

13
docs/source/developer_zone/dev_environment.rst
View File

@ -28,7 +28,8 @@ Develop using Taskfile
======================
Many development operations can be automated and chained using `Taskfile <https://taskfile.dev/>`_.
You can follow the installation instructions there, or install it via `conda-forge`.
You can follow the installation instructions there, or install it via ``conda-forge``.
.. code:: bash
@ -63,15 +64,15 @@ At the time of writing, the following tasks are available:
* create-dev-env: Create a local development mamba environment with all needed dependencies
* create-test-env: Create a local test environment with as a copy of the dev environment.
* install-cpp: Install C++ targets into the test environment.
* install-py: Install the `libmambapy` Python package inside the test environment.
* micromamba: Run the development `micromamba`.
* install-py: Install the ``libmambapy`` Python package inside the test environment.
* micromamba: Run the development ``micromamba``.
* pre-commit: Run linters and code formatters.
* reconfigure: Erase all CMake cache entries and run confiiguration again.
* stubgen: Regenerate libmambapy typing stubs.
* test-docs: Test the documentation, for instance for dead links.
* test-libmamba: Run `libmamba` C++ based tests.
* test-libmambapy: Run `libmambapy` Python based unit tests.
* test-micromamba: Run `micromamba` integration tests.
* test-libmamba: Run ``libmamba`` C++ based tests.
* test-libmambapy: Run ``libmambapy`` Python based unit tests.
* test-micromamba: Run ``micromamba`` integration tests.
For instance to run ``libmamba`` tests, execute:

2
docs/source/index.rst
View File

@ -55,7 +55,6 @@ You can try Mamba now by visiting the installation for
:maxdepth: 2
:hidden:
python_api
usage/specs
usage/solver
@ -75,3 +74,4 @@ You can try Mamba now by visiting the installation for
developer_zone/contributing
developer_zone/dev_environment
developer_zone/internals
developer_zone/changes-2.0

4
docs/source/installation/mamba-installation.rst
View File

@ -7,7 +7,7 @@ Mamba Installation
Fresh install (recommended)
***************************
We recommend that you start with the `Miniforge distribution <https://github.com/conda-forge/miniforge>`_ >= `Miniforge3-22.3.1-0`.
We recommend that you start with the `Miniforge distribution <https://github.com/conda-forge/miniforge>`_ >= ``Miniforge3-22.3.1-0``.
If you need an older version of Mamba, please use the Mambaforge distribution.
Miniforge comes with the popular ``conda-forge`` channel preconfigured, but you can modify the configuration to use any channel you like.
@ -16,7 +16,7 @@ After successful installation, you can use the mamba commands as described in :r
.. note::
1. After installation, please :ref:`make sure <defaults_channels>` that you do not have the Anaconda default channels configured.
2. Do not install anything into the `base` environment as this might break your installation. See :ref:`here <base_packages>` for details.
2. Do not install anything into the ``base`` environment as this might break your installation. See :ref:`here <base_packages>` for details.
Existing ``conda`` install (not recommended)

138
docs/source/python_api.rst
View File

@ -1,138 +0,0 @@
=======================
Python API of ``mamba``
=======================
Using internal mamba APIs
-------------------------
The core of ``mamba`` is written in C++, but we expose the internals of mamba with a Python API
(using ``pybind11``).
You can import ``libmambapy`` containing the Python API using ``import libmambapy`` without having ``mamba`` installed.
These bindings expose the following objects (`boa`_ has a full example):
- ``Context``: a singleton configuration object. All global configuration goes through this. From Python you can use the context object like so:
.. code:: python
import libmambapy
ctx = libmambapy.Context.instance()
ctx.conda_prefix = "/home/wolfv/conda"
print(ctx.root_prefix)
Here is an example usage of ``libmambapy``:
.. code:: python
def get_index(
channel_urls=(),
prepend=True,
platform=None,
use_local=False,
use_cache=False,
unknown=None,
prefix=None,
repodata_fn="repodata.json",
):
check_allowlist(channel_urls)
dlist = libmambapy.DownloadTargetList()
index = []
for idx, url in enumerate(channel_urls):
channel = Channel(url)
full_url = channel.url(with_credentials=True) + "/" + repodata_fn
full_path_cache = os.path.join(
create_cache_dir(), cache_fn_url(full_url, repodata_fn)
)
# Channels might not have a name.
if channel.name is None:
name_and_subdir = channel.subdir
else:
name_and_subdir = channel.name + "/" + channel.subdir
sd = libmambapy.SubdirData(name_and_subdir, full_url, full_path_cache)
index.append((sd, channel))
dlist.add(sd)
is_downloaded = dlist.download(libmambapy.MAMBA_DOWNLOAD_FAILFAST)
if not is_downloaded:
raise RuntimeError("Error downloading repodata.")
return index
class MambaSolver:
def __init__(self, prefix, channels, platform):
api_ctx = libmambapy.Context()
api_ctx.conda_prefix = prefix
self.channels = channels
self.platform = platform
self.index = get_index(channels, platform=platform)
self.local_index = []
self.pool = libmambapy.Pool()
self.repos = []
start_prio = len(channels)
priority = start_prio
subpriority = 0 # wrong! :)
for subdir, channel in self.index:
repo = libmambapy.Repo(
self.pool,
str(channel),
subdir.cache_path(),
channel.url(with_credentials=True),
)
repo.set_priority(start_prio, subpriority)
start_prio -= 1
self.repos.append(repo)
self.local_repos = {}
def solve(self, specs, prefix):
"""Solve given a set of specs.
Parameters
----------
specs : list of str
A list of package specs. You can use `conda.models.match_spec.MatchSpec`
to get them to the right form by calling
`MatchSpec(mypec).conda_build_form()`
Returns
-------
solvable : bool
True if the set of specs has a solution, False otherwise.
"""
solver_options = [(libmambapy.SOLVER_FLAG_ALLOW_DOWNGRADE, 1)]
api_solver = libmambapy.Solver(self.pool, solver_options)
_specs = specs
api_solver.add_jobs(_specs, libmambapy.SOLVER_INSTALL)
success = api_solver.try_solve()
if not success:
error_string = "Mamba failed to solve:\n"
for s in _specs:
error_string += f" - {s}\n"
error_string += "\nwith channels:\n"
for c in self.channels:
error_string += f" - {c}\n"
pstring = api_solver.problems_to_str()
pstring = "\n".join([" " + l for l in pstring.split("\n")])
error_string += f"\nThe reported errors are:\n⇟{pstring}"
print(error_string)
exit(1)
package_cache = libmambapy.MultiPackageCache(pkgs_dirs)
t = libmambapy.Transaction(api_solver, package_cache)
return t
.. _boa: https://github.com/mamba-org/boa/blob/main/boa/core/solver.py

4
docs/source/usage/solver.rst
View File

@ -1,3 +1,5 @@
.. _mamba_usage_solver:
Solving Package Environments
============================
@ -30,7 +32,7 @@ This serves to resolve explicit channel requirements or channel priority.
As such, the database constructor takes a set of
:cpp:type:`ChannelResolveParams <mamba::specs::ChannelResolveParams>`
to work with :cpp:type:`Channel <mamba::specs::Channel>` work with Channel data
internaly (see `the usage section on Channels <libmamba_usage_channel>`_ for more
internaly (see :ref:`the usage section on Channels <libmamba_usage_channel>` for more
information).
The first way to add a repository is from a list of |PackageInfo| using

162
docs/source/usage/specs.rst
View File

@ -1,17 +1,29 @@
.. _mamba_usage_specs:
Describing Conda Objects
========================
.. |CondaURL| replace:: :cpp:type:`CondaURL <mamba::specs::CondaURL>`
.. |UnresolvedChannel| replace:: :cpp:type:`UnresolvedChannel <mamba::specs::UnresolvedChannel>`
.. |Channel| replace:: :cpp:type:`Channel <mamba::specs::Channel>`
.. |Version| replace:: :cpp:type:`Version <mamba::specs::Version>`
.. |VersionSpec| replace:: :cpp:type:`VersionSpec <mamba::specs::VersionSpec>`
.. |BuildNumberSpec| replace:: :cpp:type:`BuildNumberSpec <mamba::specs::BuildNumberSpec>`
.. |GlobSpec| replace:: :cpp:type:`GlobSpec <mamba::specs::GlobSpec>`
.. |MatchSpec| replace:: :cpp:type:`MatchSpec <mamba::specs::MatchSpec>`
The :any:`libmambapy.specs <mamba::specs>` submodule contains object to *describe* abstraction in the Conda ecosystem.
They are purely functional and do not have any observable impact on the user system.
For instance :cpp:type:`libmambapy.specs.Channel <mamba::specs::Channel>` is used to describe a
channel but does not download any file.
For instance |Channel| is used to describe a channel but does not download any file.
CondaURL
--------
The :cpp:type:`CondaURL <mamba::specs::CondaURL>` is a rich URL object that has additional
capabilities for dealing with tokens, platforms, and packages.
The |CondaURL| is a rich URL object that has additional capabilities for dealing with tokens,
platforms, and packages.
To parse a string into a ``CondaURL``, use ``CondaURL.parse`` as follows:
To parse a string into a |CondaURL| use :cpp:func:`CondaURL.parse <mamba::specs::CondaURL::parse>`
as follows:
.. code:: python
@ -94,8 +106,8 @@ user-friendly string, but that may not be parsed back.
UnresolvedChannel
-----------------
A :cpp:type:`UnresolvedChannel <mamba::specs::UnresolvedChannel>` is a lightweight object to represent
a channel string, as in passed in the CLI or configuration.
A |UnresolvedChannel| is a lightweight object to represent a channel string, as in passed in
the CLI or configuration.
Since channels rely heavily on configuration options, this type can be used as a placeholder for a
channel that has not been fully "resolved" to a specific location.
It does minimal parsing and can detect the type of ressource (an unresolved name, a URL, a file)
@ -125,15 +137,14 @@ Dynamic platforms (as in not known by Mamba) can only be detected with the ``[]`
.. _libmamba_usage_channel:
Channel
-------
The :cpp:type:`Channel <mamba::specs::Channel>` are represented by a
:cpp:type:`CondaURL <mamba::specs::CondaURL>` and a set of platform filters.
The |Channel| are represented by a |CondaURL| and a set of platform filters.
A display name is also available, but is not considered a stable identifiaction form of the
channel, since it depends on the many configuration parameters, such as the channel alias.
We construct a :cpp:type:`Channel <mamba::specs::Channel>` by *resolving* a
:cpp:type:`UnresolvedChannel <mamba::specs::UnresolvedChannel>`.
We construct a |Channel| by *resolving* a |UnresolvedChannel|.
All parameters that influence this resolution must be provided explicitly.
@ -197,13 +208,12 @@ This is because of custom multichannel, a single name can return mutliple channe
.. note::
Creating :cpp:type:`Channel <mamba::specs::Channel>` objects this way, while highly
customizable, can be very verbose.
Creating |Channel| objects this way, while highly customizable, can be very verbose.
In practice, one can create a ``ChannelContext`` with ``ChannelContext.make_simple`` or
``ChannelContext.make_conda_compatible`` to compute and hold all these parameters from a
``Context`` (itself getting its values from all the configuration sources).
``ChannelContext.make_channel`` can then directly construct a
:cpp:type:`Channel <mamba::specs::Channel>` from a string.
|Channel| from a string.
Version
@ -240,7 +250,7 @@ so ``1.2``, ``1.2.0``, and ``1.2.0.0`` are all considered equal.
`calendar versioning <https://calver.org/>`_, or
`PEP440 <https://peps.python.org/pep-0440/>`_.
A :cpp:type:`Version <mamba::specs::Version>` can be created by parsing a string with
A |Version| can be created by parsing a string with
:cpp:func:`Version.parse <mamba::specs::Version::parse>`.
.. code:: python
@ -268,16 +278,16 @@ A version spec is a way to describe a set of versions.
We have the following primitives:
- ``*`` matches all versions (unrestricted).
- ``==`` for **equal** states matches versions equal to the given one (a singleton).
- ``==`` for **equal** matches versions equal to the given one (a singleton).
For instance ``==1.2.4`` matches ``1.2.4`` only, and not ``1.2.4.1`` or ``1.2``.
Note that since ``1.2.4.0`` is the same as ``1.2.4``, this is also matched.
- ``!=`` for ``not equal`` is the opposite, it matches all but the given version.
- ``!=`` for **not equal** is the opposite, it matches all but the given version.
For instance ``=!1.2.4`` matches ``1.2.5`` and ``1!1.2.4`` but not ``1.2.4``.
- ``>`` for **greater** matches versions stricly greater than the current one, for instance
``>1.2.4`` matches ``2.0.0``, ``1!1.0.0``, but not ``1.1.0`` or ``1.2.4``.
- ``>=`` for **greater or equal**.
- ``<`` for **less**.
- ``<-`` for **less or equal**.
- ``<=`` for **less or equal**.
- ``=`` for **starts with** matches versions that start with the same non zero parts of the version.
For instance ``=1.7`` matches ``1.7.8``, and ``1.7.0alpha1`` (beware since this is smaller
than ``1.7.0``).
@ -287,7 +297,7 @@ We have the following primitives:
For instance ``!=1.7.*`` matches ``1.8.3`` but not ``1.7.2``.
- ``~=`` for **compatible with** matches versions that are greater or equal and starting with the
all but the last parts specified, including zeros.
For instance `~=2.0` matches ``2.0.0``, ``2.1.3``, but not ``3.0.1`` or ``2.0.0alpha``.
For instance ``~=2.0`` matches ``2.0.0``, ``2.1.3``, but not ``3.0.1`` or ``2.0.0alpha``.
All version spec can be combine using a boolean grammar where ``|`` means **or** and ``,`` means
**and**.
@ -299,10 +309,10 @@ For instance, ``(>2.1.0,<3.0)|==2.0.1`` means:
- greater that ``2.1.0``
- and less than ``3.0``.
To create a :cpp:type:`VersionSpec <mamba::specs::VersionSpec>` from a string, we parse it with
:cpp:type:`VersionSpec.parse <mamba::specs::VersionSpec::parse>`.
To create a |VersionSpec| from a string, we parse it with
:cpp:func:`VersionSpec.parse <mamba::specs::VersionSpec::parse>`.
To check if a given version matches a version spec, we use
:cpp:type:`VersionSpec.contains <mamba::specs::VersionSpec::contains>`.
:cpp:func:`VersionSpec.contains <mamba::specs::VersionSpec::contains>`.
.. code:: python
@ -313,3 +323,111 @@ To check if a given version matches a version spec, we use
assert vs.contains(specs.Version.parse("2.4.0"))
assert vs.contains(specs.Version.parse("2.0.1"))
assert not vs.contains(specs.Version.parse("3.0.1"))
.. warning::
Single versions such as ``3.7`` are parsed by Conda and Mamba as ``==3.7``, which can seem
unintuitive.
As such, it is recommended to always specify an operator.
This mistake is especially likely when writing a match spec such as ``python 3.7``.
BuildNumberSpec
---------------
Similarily, a build number spec is a way to describe a set of build numbers.
It's much simpler than the |VersionSpec| in that it does not contain any boolean grammar
(the ``,`` and ``|`` operators).
|BuildNumberSpec| only contain primitives similar to that used in |VersionSpec|:
- ``*`` or ``=*`` matches all build numbers (unrestricted).
- ``=`` for **equal** matches build numbers equal to the given one (a singleton).
- ``!=`` for **not equal**.
- ``>`` for **greater** matches versions stricly greater than the current one.
- ``>=`` for **greater or equal**.
- ``<`` for **less**.
- ``<=`` for **less or equal**.
To create a |BuildNumberSpec| from a string, we parse it
with :cpp:func:`BuildNumberSpec.parse <mamba::specs::BuildNumberSpec::parse>`.
To check if a given build number matches a build number spec, we use
:cpp:func:`BuildNumberSpec.contains <mamba::specs::BuildNumberSpec::contains>`.
.. code:: python
import libmambapy.specs as specs
bs = specs.BuildNumberSpec.parse(">2")
assert bs.contains(3)
assert not bs.contains(2)
Other Specs
-----------
The |GlobSpec| is used to match glob expressions on strings.
The only wildcard currently supported is ``*`` which stands for any string (0 or more characters).
The glob spec is used as the basis for the |MatchSpec| package name and build string.
.. code:: python
import libmambapy.specs as specs
glob = specs.GlobSpec.parse("py*")
assert glob.contains("python")
assert glob.contains("pypy")
assert not vs.contains("rust-python")
MatchSpec
---------
Ultimately, the |MatchSpec| is the way to match on conda packages, that is a way to describe a
set of packages.
This is what is passed in a command line argument such as ``mamba install <match_spec>``.
Match specs have a complex string representation, which we can informally write as
``[[<channel>:]<namespace>:]<name>[<version>[=<build_string>]][[<attribute>=<value>, [...]]]``, or
with an example
``conda-forge:ns:python>=3.7=*cypthon[subdir="linux-64",fn=pkg.conda]``.
- ``<channel>``, here ``conda-forge`` describes an |UnresolvedChannel| of where the channel the
package should come from.
It accepts all values from an unresolved channel, such as ``conda-forge/label/micromamba_dev``,
URLs, local file path, and platforms filters in between brackets.
- ``<namespace>``, here ``ns`` is a future, not implemented, feature.
It is nonetheless parsed, and retrievable.
- ``<name>``, here ``python`` is the package name or glob expression and is the only mandatory
field.
- Following is the |VersionSpec| ``<version>`` or ``>=3.7`` here.
- When the version specification is written (but it could also be set to ``=*``), it can be
followed by a ``<build_string>`` glob specification, here ``*cpython``.
- Last, a bracket section of comma separated ``<attribute>`` = ``<value>``.
In the example, we have two attributes, ``subdir`` and ``fn``.
Attribute values support quaoting with ``"`` or ``'``.
As such, they can be useful to set previously mentioned field without ambiguity.
Valid attribute names are:
- ``channel``, similar to ``<channel>``.
- ``name``, similar to ``<name>``.
- ``version``, similar to ``<version>`` (can be useful to set version expression containing
parentheses and ``,`` and ``|`` operators).
- ``build``, similar to ``<build_string>``.
- ``build_number`` to set the |BuildNumberSpec|.
- ``subdir`` to select the channel subdirectory platform from which the package must come from.
- ``fn`` to select the filename the package must match.
- ``md5`` to specify the MD5 hash the package archive must have.
- ``sha256`` to specify the SHA256 hash the package archive must have.
- ``license`` to specify the license the package must have.
- ``track_features`` to specify a list of ``track_features`` specified at the package build time.
- ``optional`` to add the package as a constraint rather than a strict dependency.
.. warning::
Specifying some value mulitple time, such as in ``python>=3.7[version="(=3.9|>3.11)"]``, or
``python[build="foo"][build="bar"]`` is undefined and subject to change in the future.
.. warning::
When specifying a version in the attribute section, the first ``=`` is parsed as the attribute
assignment.
That is ``python[version=3.7]`` is equivalent to ``python 3.7``, which is equivalent to
``python==3.7`` (strong equality).
This is intuitively different from how we write ``python=3.7``, which we must write with
attributes as ``python[version="=3.7"]``.

13
docs/source/user_guide/configuration.rst
View File

@ -14,7 +14,7 @@ rely on a pure C++ implementation.
The configuration is parsed/read from multiple sources types:
- **rc file**: a file using `YAML` syntax
- **rc file**: a file using ``YAML`` syntax
- **environment variable**: a key/value pair set prior to mamba execution
- **CLI**: a parsed argument/option from a CLI interface
- **API**: a value set programmatically by a program relying on mamba
@ -26,7 +26,8 @@ The precedence order between those sources is:
:align: center
.. note::
`rc` file stands historically for `run commands` which could also translate to `runtime configuration`.
``rc`` file stands historically for ``run commands`` which could also translate to
``runtime configuration``.
It's a convenient way to persist configuration on the filesystem and use it as default.
@ -44,9 +45,9 @@ Example:
Running ``micromamba install xtensor -c my-channel`` with 3 sources of configuration:
- ``channels`` and ``always_yes`` set from rc file located at `~/.mambarc`
- ``channels`` set from CLI using `-c` option
- ``always_yes`` set from environment variable using `MAMBA_ALWAYS_YES` env var
- ``channels`` and ``always_yes`` set from rc file located at ``~/.mambarc``.
- ``channels`` set from CLI using ``-c`` option.
- ``always_yes`` set from environment variable using ``MAMBA_ALWAYS_YES`` env var
.. code::
@ -60,7 +61,7 @@ Running ``micromamba install xtensor -c my-channel`` with 3 sources of configura
$ echo $MAMBA_ALWAYS_YES
true
The resulting configuration written using `YAML` syntax is:
The resulting configuration written using ``YAML`` syntax is:
.. code::

4
docs/source/user_guide/troubleshooting.rst
View File

@ -99,8 +99,8 @@ While we make our best effort to keep backward compatibility, it is not impossib
breaks the current installation.
The following actions can be tried:
- Reinitializing your shell with `micromamba shell reinit`.
- Deleting the package cache (`"package cache"` entries in `micromamba info`)
- Reinitializing your shell with ``micromamba shell reinit``.
- Deleting the package cache (``"package cache"`` entries in ``micromamba info``)
libmamba.so.2: undefined symbol ...
-----------------------------------