diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c14e1f402..6ff207b1c 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -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: diff --git a/docs/source/advanced_usage/detailed_operations.rst b/docs/source/advanced_usage/detailed_operations.rst index 0034c2b1c..af9ff7dfc 100644 --- a/docs/source/advanced_usage/detailed_operations.rst +++ b/docs/source/advanced_usage/detailed_operations.rst @@ -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. diff --git a/docs/source/advanced_usage/package_resolution.rst b/docs/source/advanced_usage/package_resolution.rst index ae686a1e0..d02fc9f08 100644 --- a/docs/source/advanced_usage/package_resolution.rst +++ b/docs/source/advanced_usage/package_resolution.rst @@ -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. diff --git a/docs/source/developer_zone/changes-2.0.rst b/docs/source/developer_zone/changes-2.0.rst index 71bc48a9c..ec35ba9b9 100644 --- a/docs/source/developer_zone/changes-2.0.rst +++ b/docs/source/developer_zone/changes-2.0.rst @@ -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 `_. @@ -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 diff --git a/docs/source/developer_zone/dev_environment.rst b/docs/source/developer_zone/dev_environment.rst index c5f3a5f8f..fb7650a2e 100644 --- a/docs/source/developer_zone/dev_environment.rst +++ b/docs/source/developer_zone/dev_environment.rst @@ -28,7 +28,8 @@ Develop using Taskfile ====================== Many development operations can be automated and chained using `Taskfile `_. -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: diff --git a/docs/source/index.rst b/docs/source/index.rst index e8e799fe1..a2ad90244 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -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 diff --git a/docs/source/installation/mamba-installation.rst b/docs/source/installation/mamba-installation.rst index 5c4386a57..f60a6ae9f 100644 --- a/docs/source/installation/mamba-installation.rst +++ b/docs/source/installation/mamba-installation.rst @@ -7,7 +7,7 @@ Mamba Installation Fresh install (recommended) *************************** -We recommend that you start with the `Miniforge distribution `_ >= `Miniforge3-22.3.1-0`. +We recommend that you start with the `Miniforge distribution `_ >= ``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 ` 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 ` for details. + 2. Do not install anything into the ``base`` environment as this might break your installation. See :ref:`here ` for details. Existing ``conda`` install (not recommended) diff --git a/docs/source/python_api.rst b/docs/source/python_api.rst deleted file mode 100644 index c052503a1..000000000 --- a/docs/source/python_api.rst +++ /dev/null @@ -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 diff --git a/docs/source/usage/solver.rst b/docs/source/usage/solver.rst index 0111e24be..f0771b1d9 100644 --- a/docs/source/usage/solver.rst +++ b/docs/source/usage/solver.rst @@ -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 ` to work with :cpp:type:`Channel ` work with Channel data -internaly (see `the usage section on Channels `_ for more +internaly (see :ref:`the usage section on Channels ` for more information). The first way to add a repository is from a list of |PackageInfo| using diff --git a/docs/source/usage/specs.rst b/docs/source/usage/specs.rst index a35a573dd..f872076d3 100644 --- a/docs/source/usage/specs.rst +++ b/docs/source/usage/specs.rst @@ -1,17 +1,29 @@ +.. _mamba_usage_specs: + Describing Conda Objects ======================== +.. |CondaURL| replace:: :cpp:type:`CondaURL ` +.. |UnresolvedChannel| replace:: :cpp:type:`UnresolvedChannel ` +.. |Channel| replace:: :cpp:type:`Channel ` +.. |Version| replace:: :cpp:type:`Version ` +.. |VersionSpec| replace:: :cpp:type:`VersionSpec ` +.. |BuildNumberSpec| replace:: :cpp:type:`BuildNumberSpec ` +.. |GlobSpec| replace:: :cpp:type:`GlobSpec ` +.. |MatchSpec| replace:: :cpp:type:`MatchSpec ` + + The :any:`libmambapy.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 ` 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 ` 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 ` +as follows: .. code:: python @@ -94,8 +106,8 @@ user-friendly string, but that may not be parsed back. UnresolvedChannel ----------------- -A :cpp:type:`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 ` are represented by a -:cpp:type:`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 ` by *resolving* a -:cpp:type:`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 ` 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 ` 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 `_, or `PEP440 `_. -A :cpp:type:`Version ` can be created by parsing a string with +A |Version| can be created by parsing a string with :cpp:func:`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 ` from a string, we parse it with -:cpp:type:`VersionSpec.parse `. +To create a |VersionSpec| from a string, we parse it with +:cpp:func:`VersionSpec.parse `. To check if a given version matches a version spec, we use -:cpp:type:`VersionSpec.contains `. +:cpp:func:`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 `. +To check if a given build number matches a build number spec, we use +:cpp:func:`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 specs have a complex string representation, which we can informally write as +``[[:]:][[=]][[=, [...]]]``, or +with an example +``conda-forge:ns:python>=3.7=*cypthon[subdir="linux-64",fn=pkg.conda]``. + +- ````, 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. +- ````, here ``ns`` is a future, not implemented, feature. + It is nonetheless parsed, and retrievable. +- ````, here ``python`` is the package name or glob expression and is the only mandatory + field. +- Following is the |VersionSpec| ```` or ``>=3.7`` here. +- When the version specification is written (but it could also be set to ``=*``), it can be + followed by a ```` glob specification, here ``*cpython``. +- Last, a bracket section of comma separated ```` = ````. + 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 ````. + - ``name``, similar to ````. + - ``version``, similar to ```` (can be useful to set version expression containing + parentheses and ``,`` and ``|`` operators). + - ``build``, similar to ````. + - ``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"]``. diff --git a/docs/source/user_guide/configuration.rst b/docs/source/user_guide/configuration.rst index 5e21ea927..6126541e2 100644 --- a/docs/source/user_guide/configuration.rst +++ b/docs/source/user_guide/configuration.rst @@ -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:: diff --git a/docs/source/user_guide/troubleshooting.rst b/docs/source/user_guide/troubleshooting.rst index 1bf1cd15d..99b91b740 100644 --- a/docs/source/user_guide/troubleshooting.rst +++ b/docs/source/user_guide/troubleshooting.rst @@ -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 ... -----------------------------------