diff --git a/docs/source/caching.rst b/docs/source/caching.rst index d802c30da..41a4df78c 100644 --- a/docs/source/caching.rst +++ b/docs/source/caching.rst @@ -11,7 +11,7 @@ Memcached is widely used, easy to deploy (because there is no storage needed sin process/executable), and is very fast due to the data residing in memory. In a studio environment (with many machines), machines that perform a solve that is already cached to the -resolve cache will simply receive the cached result rather than preforming a re-solve. This can significantly +resolve cache will simply receive the cached result rather than performing a re-solve. This can significantly decrease the time it takes to resolve environments. Slow solves will now be almost instantaneous. Resolve caching has almost no downsides. Only in rare edge cases where you have to "hack" a released package into @@ -27,13 +27,13 @@ The following information is stored to the memcached server for each solve: * Timestamps of packages seen in previous solves. * Variant states information about the state of a variant. For example, in the 'filesystem' repository type, the 'state' is the last modified date of the file associated with the variant (perhaps a package.py). - If the state of any variant has changed from a cached resolve - eg. if a file has been modified - the cached resolve is discarded. + If the state of any variant has changed from a cached resolve - e.g. if a file has been modified - the cached resolve is discarded. Setup ----- To enable memcached caching, you need to configure the :data:`memcached_uri` config variable. -This variable accepts a list of URI to your memcached servers or None. Example with memcached running on +This variable accepts a list of URIs to your memcached servers or None. Example with memcached running on localhost on its default port: .. code-block:: python @@ -180,8 +180,9 @@ you should **not** enable caching on package repositories where packages may get overwritten. It is for this reason that caching is disabled for local packages by default (see :data:`package_cache_local`). -Control Disk Usage ------------------- +Controlling Disk Usage +Controlling Disk Usage +---------------------- You can control the disk usage of the package cache by using the :data:`package_cache_space_buffer` and :data:`package_cache_used_threshold` settings. @@ -191,8 +192,8 @@ them to your liking. Another way to control the disk usage is to run the :option:`rez-pkg-cache --clean` command either manually or as a cron job. See :ref:`caching-cleaning-the-cache`. -Commandline Tool ----------------- +Command Line Tool +----------------- Inspection ++++++++++ @@ -232,7 +233,7 @@ Cached variants have one of the following statuses at any given time: Logging +++++++ -Caching operations are stored into logfiles within the cache directory. To view: +Caching operations are stored into log files within the cache directory. To view: .. code-block:: console diff --git a/docs/source/configuring_rez.rst b/docs/source/configuring_rez.rst index 807d87999..f71a97176 100644 --- a/docs/source/configuring_rez.rst +++ b/docs/source/configuring_rez.rst @@ -11,9 +11,9 @@ Settings are determined in the following way: - The setting is then overridden if it is present in another settings file pointed at by the :envvar:`REZ_CONFIG_FILE` environment variable. This can also be a path-like variable, to read from multiple configuration files; -- The setting is further overriden if it is present in ``$HOME/.rezconfig`` or ``$HOME/.rezconfig.py``; +- The setting is further overridden if it is present in ``$HOME/.rezconfig`` or ``$HOME/.rezconfig.py``; - The setting is overridden again if the environment variable :envvar:`REZ_XXX` is present, where ``XXX`` is - the uppercase version of the setting key. For example, :data:`.image_viewer` will be overriden by + the uppercase version of the setting key. For example, :data:`.image_viewer` will be overridden by :envvar:`REZ_IMAGE_VIEWER`. - This is a special case applied only during a package build or release. In this case, if the package definition file contains a "config" section, settings in this section will override all @@ -109,12 +109,12 @@ JSON formats are supported: # in rezconfig default_relocatable_per_package = DelayLoad('/svr/configs/rez_relocs.yaml') -See :Class:`.DelayLoad`. +See :class:`.DelayLoad`. .. _configuring-rez-commandline-line: -Commandline Tool -================ +Command Line Tool +================= You can use the :ref:`rez-config` command line tool to see what the current configured settings are. Called with no arguments, it prints all settings; if you specify an argument, it prints out just @@ -145,6 +145,6 @@ Following is an alphabetical list of rez settings. file in the rez source, so you can also refer to that file for the same information. .. This is a custom directive. See the rez_sphinxext.py file for more information. -.. TL;DR: It will take care of generating the documentation or all the settings defined +.. TL;DR: It will take care of generating the documentation for all the settings defined .. in rezconfig.py .. rez-config:: diff --git a/docs/source/environment.rst b/docs/source/environment.rst index 7045d5586..b5ac13e00 100644 --- a/docs/source/environment.rst +++ b/docs/source/environment.rst @@ -102,7 +102,7 @@ dots replaced with underscore. .. envvar:: REZ_(PKG)_PATCH_VERSION - The patch version of the package, or an emopty string. + The patch version of the package, or an empty string. Ephemeral packages environment variables ---------------------------------------- @@ -216,7 +216,7 @@ operation of rez. For any given rez config entry (see ``rezconfig.py``), you can override the setting with an environment variable, for convenience. Here, ``XXX`` is the uppercased equivalent of the setting name. For example, - a setting commonly overriden this way is :data:`packages_path`, whos equivalent + a setting commonly overridden this way is :data:`packages_path`, whose equivalent variable is :envvar:`REZ_PACKAGES_PATH`. .. hint:: @@ -234,7 +234,7 @@ operation of rez. .. envvar:: EDITOR - On Linux and OSX systems, this will set the default editor to use + On Linux and macOS systems, this will set the default editor to use if and when rez requires one (an example is on release if the :data:`prompt_release_message` config setting is true). @@ -259,18 +259,18 @@ Development Environment Variables .. envvar:: REZ_LOG_DEPRECATION_WARNINGS Enable all deprecation warnings to be logged regardless of how you have configured - your python interpreter. This is usefull to help upgrading to newer versions of rez. + your python interpreter. This is useful to help upgrading to newer versions of rez. Prior to updating, you should set this environment variable to see if you need to change some things to be compatible with newer versions. .. warning:: Enabling this will forcefully load every configuration file instead of loading them - lazilly. This can have an impact on startup time. + lazily. This can have an impact on startup time. .. envvar:: REZ_SIGUSR1_ACTION - If you set this to ``print_stack``, rez will prints its + If you set this to ``print_stack``, rez will print its current stacktrace to stdout if sent a USR1 signal. This is for debugging purposes only. .. envvar:: _REZ_NO_KILLPG diff --git a/docs/source/ephemerals.rst b/docs/source/ephemerals.rst index 57c6c89f9..e669d162a 100644 --- a/docs/source/ephemerals.rst +++ b/docs/source/ephemerals.rst @@ -7,7 +7,7 @@ Ephemerals Ephemeral packages (or simply 'ephemerals') are requests for packages that do not exist. Ephemeral package names always begin with a dot (``.``). Like all package requests, ephemerals can be requested as part of packages' requires or variants -lists, or directly by the user (via :ref:`rez-env` for eg). +lists, or directly by the user (via :ref:`rez-env` for e.g.). Example: @@ -101,10 +101,10 @@ etc) is present in the resolve. Note that the leading ``.`` is implied and not included when querying the :attr:`ephemerals` object. .. warning:: - Since :attr:`ephemerals` is a dict-like object, so it has - a ``get`` function which will return a full request string if key exists. Hence, + Since :attr:`ephemerals` is a dict-like object, it has + a ``get`` function which will return a full request string if the key exists. Hence, the default value should also be a full request string, not just a version range - string like ``0`` in :func:`ephemerals.get_range`. Or :func:`intersects` may not work as expect. + string like ``0`` in :func:`ephemerals.get_range`. Otherwise, :func:`intersects` may not work as expected. Ephemeral Use Cases =================== @@ -162,7 +162,7 @@ Abstract Package Representation Sometimes it makes sense for a package to require some form of abstract object or capability, rather than an actual package. For example, perhaps your package (or one of its variants) requires a GPU to be present on the host machine. To support -this, you might have something setup that includes a ``.gpu-1`` ephemeral in the +this, you might have something set up that includes a ``.gpu-1`` ephemeral in the :ref:`implicits ` list on all GPU-enabled hosts. Then, your package could look like this: @@ -176,7 +176,7 @@ Then, your package could look like this: ] .. warning:: - Be aware that on hosts that do **not** have a gpu + Be aware that on hosts that do **not** have a GPU implicit, either variant could be selected. You would want to either guarantee - that every host has the gpu implicit set to 0 or 1, or that the user always + that every host has the GPU implicit set to 0 or 1, or that the user always explicitly specifies ``.gpu-0`` or ``.gpu-1`` in their request. diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 3b5696649..199080cfc 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -7,7 +7,7 @@ Essential packages .. warning:: :ref:`rez-bind` is going to be deprecated. The current implementation is not actively maintained. - Especially on windows, using :option:`--quickstart ` is likely to fail. + Especially on Windows, using :option:`--quickstart ` is likely to fail. Even if rez-bind will be deprecated and we generally discourage its use, you can safely use it for creating the ``arch``, ``os`` and ``platform`` packages. @@ -144,7 +144,7 @@ You can use the :ref:`rez-env` tool to request a configured environment containi > ]$ █ Now you are within the configured environment. The caret (``>``) prefixed to your prompt is a visual -cue telling you that you're within a rez-configured subshell. Rez does not update the currect environment, +cue telling you that you're within a rez-configured subshell. Rez does not update the current environment, instead it configures a subshell and puts you within it. Now you can run the ``hello`` tool in our ``hello_world`` package: @@ -176,7 +176,7 @@ initially created the environment: platform-osx /home/ajohns/packages/platform/osx (local) python-2.7.11 /home/ajohns/packages/python/2.7.11/platform-osx/arch-x86_64/os-osx-10.11.5 (local) -To exit the configured environment, simply exist the shell using the ``exit`` command or :kbd:`Control-d`: +To exit the configured environment, simply exit the shell using the ``exit`` command or :kbd:`Control-d`: You can also create a configured environment and run a command inside of it, with a single command. When you use this form, the shell is immediately exited after the command runs: diff --git a/docs/source/guides/update_to_3.rst b/docs/source/guides/update_to_3.rst index 0b45a1fb8..088068dbc 100644 --- a/docs/source/guides/update_to_3.rst +++ b/docs/source/guides/update_to_3.rst @@ -3,7 +3,7 @@ Update to rez 3.0.0 =================== Rez ``3.0.0`` is not be a major breaking change, except that Python 2 is not supported anymore. -There is various other small changes too. +There are various other small changes too. This guide will show you how to prepare before upgrading to ``3.0.0``. We hope that this guide will help make the upgrade process smoother. @@ -22,7 +22,7 @@ Steps for smooth upgrade if you wish. You should prefer 2.114.1 over 2.114.0 because 2.114.0 contained a bug that prevented - rez from correctly running when :envvar:`REZ_LOG_DEPRECATION_WARNINGS` is set. + rez from correctly running when :envvar:`REZ_LOG_DEPRECATION_WARNINGS` was set. .. warning:: diff --git a/docs/source/index.rst b/docs/source/index.rst index 1d31a1689..ba66ce55f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -89,5 +89,5 @@ ways to get in touch with us: * `Report an issue `_ * `Chat room `_: Join the ``#rez`` channel * `Start a discussion `_ -* `Mailing list `_: Note that are way less active on the mailing +* `Mailing list `_: Note that we are far less active on the mailing list than on any other communication channel. diff --git a/docs/source/managing_packages.rst b/docs/source/managing_packages.rst index 64899dbbc..de8b2b954 100644 --- a/docs/source/managing_packages.rst +++ b/docs/source/managing_packages.rst @@ -10,7 +10,7 @@ repository, but it will not be visible to the rez API nor to any newly resolved runtimes. Any runtimes that are currently using an ignored package are unaffected, since the package's payload has not been removed. -To ignore a package via commandline: +To ignore a package via command line: .. code-block:: console @@ -36,7 +36,7 @@ Via API: Both of these options generate a :file:`.ignore{{version}}` file (e.g. ``.ignore3.1.2``) next to the package version directory. -You can also do the reverse (ie unignore a package). Use the :option:`-u ` option of +You can also do the reverse (i.e. unignore a package). Use the :option:`-u ` option of :ref:`rez-pkg-ignore`, or the :meth:`~rez.package_repository.PackageRepository.unignore_package` method on the package repository object. @@ -46,7 +46,7 @@ Copying Packages Packages can be copied from one :ref:`package repository ` to another, like so: -Via commandline: +Via command line: .. code-block:: console @@ -117,7 +117,7 @@ to another. Be aware that moving a package does not actually delete the source package however. Instead, the source package is hidden (ignored). It is up to you to delete it at some later date. -To move a package via commandline: +To move a package via command line: .. code-block:: console @@ -143,7 +143,7 @@ Via API: None Be aware that a non-relocatable package is also not movable (see -:attr:`here `. Like package +:attr:`here `). Like package copying, there is a ``force`` option to move it regardless. A typical reason you might want to move a package is to archive packages that are @@ -164,7 +164,7 @@ Packages can be removed. This is different from ignoring. The package and its payload is deleted from storage, whereas ignoring just hides it. It is not possible to un-remove a package. -To remove a package via commandline: +To remove a package via command line: .. code-block:: console diff --git a/docs/source/package_commands.rst b/docs/source/package_commands.rst index 3c2c1aa88..17493544e 100644 --- a/docs/source/package_commands.rst +++ b/docs/source/package_commands.rst @@ -93,7 +93,7 @@ incorrectly, import the system version. .. todo:: Add custom class for "construction"? -.. admonition:: Noteasd +.. admonition:: Note Better control over environment variable initialization is coming. Specifically, you will be able to specify various modes for variables. For example, one @@ -322,7 +322,7 @@ Following is a list of the objects and functions available. .. py:attribute:: build - This is a dict like object. Each key can also be accessed as attributes. + This is a dict-like object. Each key can also be accessed as attributes. This object is only available in the :func:`pre_build_commands` function. It has the following fields: @@ -465,7 +465,7 @@ Following is a list of the objects and functions available. .. py:attribute:: ephemerals - A dict like object representing the list of ephemerals in the resolved environment. Each item is a + A dict-like object representing the list of ephemerals in the resolved environment. Each item is a string (the full request, eg ``.foo.cli-1``), keyed by the ephemeral package name. Note that you do **not** include the leading ``.`` when getting items from the ``ephemerals`` object. @@ -523,7 +523,7 @@ Following is a list of the objects and functions available. .. py:attribute:: implicits - A dict like object that is similar to the :attr:`request` object, but it contains only the package request as + A dict-like object that is similar to the :attr:`request` object, but it contains only the package request as defined by the :data:`implicit_packages` configuration setting. .. code-block:: python @@ -597,7 +597,7 @@ Following is a list of the objects and functions available. .. py:attribute:: request :type: ~rez.rex_bindings.RequirementsBinding - A dict like object representing the list of package requests. Each item is a request string keyed by the + A dict-like object representing the list of package requests. Each item is a request string keyed by the package name. For example, consider the package request: .. code-block:: text @@ -614,11 +614,6 @@ Following is a list of the objects and functions available. "corelib": "!corelib-1.4.4" } - Use ``get_range`` to test with the :func:`intersects` function: - - if intersects(request.get_range("maya", "0"), "2019"): - info("maya 2019.* was asked for!") - Example: .. code-block:: python @@ -626,6 +621,13 @@ Following is a list of the objects and functions available. if "maya" in request: info("maya was asked for!") + Use ``get_range`` to test with the :func:`intersects` function: + + .. code-block:: python + + if intersects(request.get_range("maya", "0"), "2019"): + info("maya 2019.* was asked for!") + .. tip:: If multiple requests are present that refer to the same package, the request is combined ahead of time. In other words, if requests ``foo-4+`` and ``foo-<6`` were both @@ -633,11 +635,18 @@ Following is a list of the objects and functions available. .. py:function:: resetenv(envvar: str, value: str, friends=None) -> None - TODO: Document + This is intended to handle the case where multiple packages want to set the same environment + variable during the resolve. In that case, you would use :attr:`resetenv` instead of :attr:`setenv`. + See :any:`resetting_variables` for more details. + + However, rez does not currently behave like this - multiple :attr:`setenv` calls to the same variable + do not abort the resolve. Instead, the latest call to :attr:`setenv` wins. + + And currently, :attr:`resetenv` merely acts as a synonym for :attr:`setenv`. .. py:attribute:: resolve - A dict like object representing the list of packages in the resolved environment. Each item is a + A dict-like object representing the list of packages in the resolved environment. Each item is a :ref:`Package ` object, keyed by the package name. Packages can be accessed using attributes (ie ``resolve.maya``). @@ -685,7 +694,7 @@ Following is a list of the objects and functions available. .. py:attribute:: system :type: ~rez.system.System - This object provided system information, such as current platform, arch and os. + This object provides system information, such as current platform, arch and os. .. code-block:: python @@ -694,7 +703,7 @@ Following is a list of the objects and functions available. .. py:attribute:: test - Dict like object to access test related attributes. Only available in the :func:`pre_test_commands` function. + Dict-like object to access test related attributes. Only available in the :func:`pre_test_commands` function. Keys can be accessed as object attributes. .. py:attribute:: test.name @@ -735,16 +744,61 @@ Following is a list of the objects and functions available. .. py:attribute:: this.is_package :type: bool - .. todo:: Document + "Package" here means "a containing object that describes a package". It does not mean you are + in a resolved context for a package. This variable is set to ``True`` if you are in a package that + does not represent a resolved context; this happens, for example, when you are searching + through packages. + + If :attr:`this.is_package` is ``True`` then :attr:`this.is_variant` must be ``False``, and vice versa. - TODO: Document + See :attr:`this.is_variant` for a fuller explanation and example. .. py:attribute:: this.is_variant :type: bool - .. todo:: Document + This is set to ``True`` if you are in a resolved context. That's because a context must be + resolved down to a specific :doc:`variant <../variants>`. To see the relationship between :attr:`this.is_package` and + :attr:`this.is_variant`, consider a package called ``test`` with the following code in its ``package.py`` + file: + + .. code-block:: python + + @late() + def foo(): + print(f"in foo: {in_context()=}") + print(f"in foo: {this.is_package=}") + print(f"in foo: {this.is_variant=}") + return ["foo"] + + def commands(): + print(f"in commands: {this.is_package=}") + print(f"in commands: {this.is_variant=}") + value = this.foo + print(f"{value=}") + + + In this example, ``foo`` is a late-binding attribute that will be executed as part of resolving the + package's context. If you build the ``test`` package and run ``rez env test`` you will get this output: + + .. code-block:: text + + % rez env test + in commands: this.is_package=False + in commands: this.is_variant=True + in foo: in_context()=True + in foo: this.is_package=True + in foo: this.is_variant=False + value=['foo'] + + But if you only search through the ``test`` package, where no context must be resolved, you get this: + + .. code-block:: text - TODO: Document + % rez search -f '{foo}' test + in foo: in_context()=False + in foo: this.is_package=True + in foo: this.is_variant=False + foo .. py:attribute:: this.name :type: str diff --git a/docs/source/package_definition.rst b/docs/source/package_definition.rst index 5f896b842..0a108709e 100644 --- a/docs/source/package_definition.rst +++ b/docs/source/package_definition.rst @@ -414,7 +414,7 @@ such as :attr:`build_requires`) by using wildcards as shown here: If you check the ``package.py`` of the built package, you will see that the boost reference in the requires list will be expanded to the latest found within the given range (``boost-1.55`` for example). -There is also a special wilcard available, ``**``. This expands to the full package version. For +There is also a special wildcard available, ``**``. This expands to the full package version. For example, the requirement ``boost-1.**`` might expand to ``boost-1.55.1``. You can also achieve requirements expansion by implementing :attr:`requires` as an early binding @@ -477,6 +477,9 @@ It is not uncommon to override config settings such as the release path in a pac with scope("config") as c: c.release_packages_path = "/software/packages/external" +Here a package is overriding the default release path - perhaps you're releasing +internally and externally developed packages to different locations, for example. + Let's say we have a scenario where we want to install third party packages to a specific install path, and that we set the arbitrary attribute ``external`` to ``True`` for these packages. We could do this with a global preprocessing function like this: @@ -701,7 +704,7 @@ the data type, and includes a code snippet. :type: bool Indicates that the package is an application that may have plugins. These plugins are often made - available as rez packages also. Used in conjuction with the :ref:`rez-plugins` command. Also, see :attr:`plugin_for`. + available as rez packages also. Used in conjunction with the :ref:`rez-plugins` command. Also, see :attr:`plugin_for`. .. code-block:: python @@ -749,7 +752,7 @@ the data type, and includes a code snippet. name = "maya_utils" .. py:attribute:: plugin_for - :type: str + :type: list[str] Provided if this package is a plugin of another package. For example, this might be a maya plugin. This is useful when using the :ref:`rez-plugins` command. Also, see :attr:`has_plugins`. @@ -871,11 +874,11 @@ the data type, and includes a code snippet. } } - As an example, if you want to run the ``maya_CI`` block defined in the example above (named ``maya_utils``), you can run: + As an example, if you want to run the ``maya_CI`` block defined in the example above (named ``maya_CI``), you can run: .. code-block:: text - ]$ rez-test maya_utils lint + ]$ rez-test maya_CI .. note:: Prior to running the tests, you will need to run :ref:`rez-build`. :ref:`rez-test` can only @@ -1085,7 +1088,7 @@ of these attributes have been added. The package release message. This is supplied either via the :option:`rez-release --message` option, or was entered in a text editor on release if rez is configured to do this (see the config - setting ``TODO_ADD_THIS``). A package may not have a release message. + setting :data:`prompt_release_message`). A package may not have a release message. .. code-block:: python diff --git a/docs/source/pip.rst b/docs/source/pip.rst index 6cde13a78..b3a99bdcc 100644 --- a/docs/source/pip.rst +++ b/docs/source/pip.rst @@ -3,12 +3,12 @@ Pip === Rez is language agnostic. -But since python is so much used in the VFX industry (and outside), -it knows how to convert/translate it into a rez package. -To do so, it provides a :ref:`rez-pip` command. +But since python is so prevalent in the VFX industry (and outside), +rez knows how to convert/translate Pip packages into rez packages. +It does this using the :ref:`rez-pip` command. .. warning:: - It doesn't know how to translate its own packages into pip packages. + This command will not translate rez packages into Pip packages. .. hint:: We are planning to introduce a new rez-pip implemented as a plugin that will @@ -23,7 +23,7 @@ Usage [-s] [-r] [-v] PACKAGE - Install a pip-compatible python package, and its dependencies, as rez + Install a Pip-compatible python package, and its dependencies, as rez packages. positional arguments: @@ -33,10 +33,10 @@ Usage -h, --help show this help message and exit --python-version VERSION python version (rez package) to use, default is - latest. Note that the pip package(s) will be installed + latest. Note that the Pip package(s) will be installed with a dependency on python-MAJOR.MINOR. --pip-version VERSION - pip version (rez package) to use, default is latest. + Pip version (rez package) to use, default is latest. This option is deprecated and will be removed in the future. -i, --install install the package @@ -50,62 +50,62 @@ Usage The :ref:`rez-pip` command allows you to do two main things. -1. Install or release a pip package as a rez package. +1. Install or release a Pip package as a rez package. 2. Search for a package on PyPI .. _which-pip-will-be-used: -Which pip will be used? +Which Pip will be used? ======================= -:ref:`rez-pip` uses a fallback mechanism to find which pip will be used to run the commands. -The logic is as follow: +:ref:`rez-pip` uses a fallback mechanism to find which Pip will be used to run the commands. +The logic is as follows: -1. Search for pip in the rezified ``python`` package specified with :option:`--python-version `, or +1. Search for Pip in the rezified ``python`` package specified with :option:`--python-version `, or the latest version if not specified; 2. If found, use it; -3. If not found, search for pip in the rezified ``pip`` package specified with :option:`--pip-version `, +3. If not found, search for Pip in the rezified ``pip`` package specified with :option:`--pip-version `, or latest version if not specified. .. note:: Note that this is deprecated and will be removed in the future 4. If rezified ``pip`` is found, use it; -5. If not found, fall back to pip installed in rez own virtualenv. +5. If not found, fall back to Pip installed in rez’s own virtualenv. .. note:: - In all of these options, we also check if the version of pip is greater or equal + In all of these options, we also check if the version of Pip is greater or equal than 19.0. This is a hard requirement of :ref:`rez-pip`. -Note that rez-pip output should tell you what it tries and which pip it will use. +Note that rez-pip output should tell you what it tries and which Pip it will use. -It is extremely important to know which pip is used and understand why it is used. Pip packages +It is extremely important to know which Pip is used and understand why it is used. Pip packages define which python version they are compatible with. -When you install a pip package, pip checks which python version it is +When you install a Pip package, Pip checks which python version it is currently running under to determine if a package can be downloaded and installed. -Not only this but it also checks which python implementation is used (CPython, PyPy, +It also checks which python implementation is used (CPython, PyPy, IronPython, etc), the architecture python was built with, and other variables. So the thing you really need to know first is which python you want to use and from there you should know -which pip is used. Knowing the pip version comes in second place. +which Pip is used. Knowing the Pip version is of secondary importance. At some point, we supported the :option:`--pip-version ` argument, but considering what was just said -above, we decided to deprecate it (but not yet removed) just for backward compatibility reasons. -Pip is too much (read tightly) coupled to the python version/interpreter it is installed with -for us to support having pip as a rez package. We just can't guarantee that pip can be +above, we decided to deprecate it (but not remove it yet) just for backward compatibility. +Pip is too tightly coupled to the python version/interpreter it is installed with +for us to support having Pip as a rez package. We just can't guarantee that Pip can be install once in a central way and work with multiple different python version, and potentially different implementations. .. _how-should-i-install-pip: -How should I install pip? +How should I install Pip? ========================= -Following the :ref:`which-pip-will-be-used` section, we recommend to install -pip inside your python packages. For Python 2, this can be done when you compile it with the +Following the :ref:`which-pip-will-be-used` section, we recommend you install +Pip inside your python packages. For Python 2, this can be done when you compile it with the ``--with-ensurepip`` flag of the ``configure`` script. This will install a version older than 19.0 though, so you will need to upgrade it. For Python 3, it is already installed by default. Though your mileage may vary for the version installed, depending on which Python version you -installed. So check the pip version and update it if necessary. We also encourage you +installed. So check the Pip version and update it if necessary. We also encourage you to install ``wheel`` and possibly update ``setuptools``. ``pip``, ``setuptools`` and ``wheel`` are perfectly fine when installed in the interpreter directly as they are pretty core packages and all have no dependencies (and that's what ``virtualenv`` does by default too). @@ -118,26 +118,26 @@ packages and all have no dependencies (and that's what ``virtualenv`` does by de $ /path/to/python -E -s -m pip install - ``-E`` will render any ``PYTHON*`` environment variable to not be used and ``-s`` will + ``-E`` will force any ``PYTHON*`` environment variables to be ignored, and ``-s`` will remove your :mod:`user site ` from the equation. -Install/release +Install/Release --------------- -You have two options when you want to convert a pip package to a rez package. You can +You have two options when you want to convert a Pip package to a rez package. You can install it, or release it. Install means that it will install in your :data:`local_packages_path`, while release means it will be installed in your :data:`release_packages_path`. You can also specify a custom installation location using :option:`--prefix ` (or ``-p``). You can (and we recommend) use :option:`--python-version ` to choose for which python -version you want to install a given package. This will make ``rez-pip`` to resolve +version you want to install a given package. This will make ``rez-pip`` resolve the given version of the ``python`` rez package and use it to run the ``pip install``. See :ref:`which-pip-will-be-used` for more details. -If the pip package is not pure (so contains ``.so`` for example), you will need to -call :ref:`rez-pip` for each python version you want to install the pip package for. +If the Pip package is not pure (so contains ``.so`` for example), you will need to +run :ref:`rez-pip` for each python version you want to install the Pip package for. .. warning:: :option:`--pip-version ` is deprecated and will be removed in the future. See :ref:`how-should-i-install-pip` on how we recommend - to install pip from now on. + to install Pip from now on. diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index d2a7a1132..c960fe944 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -34,7 +34,7 @@ Existing plugin types ====================== =========================================================== ================== .. [1] Top level settings: The concept of top level settings is documented in :ref:`default-settings`. -.. [2] build_process: You have to choose between on of the two classes. +.. [2] build_process: You have to choose between one of the two classes. .. [3] package_repository: All 4 classes have to be implemented. .. _configuring-plugins: @@ -62,7 +62,7 @@ Currently installed plugins can be queried by running :option:`rez -i` $ rez -i - Rez 2.113.0 + Rez 3.3.0 PLUGIN TYPE NAME DESCRIPTION STATUS ----------- ---- ----------- ------ @@ -80,10 +80,12 @@ Currently installed plugins can be queried by running :option:`rez -i` release vcs hg Mercurial version control loaded release vcs stub Stub version control system, for testing purposes loaded release vcs svn FAILED: No module named 'pysvn' - shell cmd Windows Command Prompt (DOS) shell. loaded - shell gitbash Git Bash (for Windows) shell loaded - shell powershell Windows PowerShell 5 loaded + shell bash Bash shell loaded + shell csh CSH shell loaded shell pwsh PowerShell Core 6+ loaded + shell sh SH shell loaded + shell tcsh TCSH shell loaded + shell zsh Zsh shell loaded Discovery mechanisms ==================== diff --git a/docs/source/variants.rst b/docs/source/variants.rst index 9b2bc9e45..b0ef2ec2d 100644 --- a/docs/source/variants.rst +++ b/docs/source/variants.rst @@ -131,7 +131,7 @@ You may often see packages with just one variant. There are two reasons for this * *Future proofing*: Let's say you have a compiled package that links against python. It may currently support ``python-2.7``, however it's conceivable that support for newer python versions may be added later. **It is not possible to add new variants - to a package that does not have any without changing/bumnig the version**. So by + to a package that does not have any without changing/bumping the version**. So by adding the ``python-2.7`` variant now, you can add variants later without needing to move to a newer version. * *Installation path*: People often expect to see platform, architecture and/or @@ -153,7 +153,7 @@ depending on the environment being resolved. For example, consider: ]$ rez-env my_maya_plugin maya-2016 -- echo '$REZ_MY_MAYA_PLUGIN_ROOT' /rez/packages/my_maya_plugin/1.0.0/maya-2016.sp2 -You can see how the correct variant (ie the one that does not conflict with other +You can see how the correct variant (i.e. the one that does not conflict with other packages in the request) has been selected. But what if both variants are valid for the given request? Consider: