make pip source installs a bit easier (#1048)

Follow-up to #1044
Contributes to rapidsai/build-planning#31
Related to #1047

* updates `libucx` build requirements so they can be satisfied by only packages from pypi.org
* removes `--extra-index-url https://pypi.anaconda.org/rapidsai-wheels-nightly/simple/` in `pip install` calls, now that `rapids-build-backend` is on pypi.org (https://pypi.org/project/rapids-build-backend/)
* sets `rapids-build-backend` config `disable-cuda=true` in `pyproject.toml`
  - *this means that now `pip install .` will not require `nvcc` or produce a wheel with a suffix like `-cu12`*
  - *modified CI script used to build wheels to override this, so the published wheels will still have `-cu${ver}` suffixes
* updates docs on source installation to reflect these changes

## Notes for Reviewers

These changes came out of an offline conversation with @pentschev and @vyasr

Authors:
  - James Lamb (https://github.com/jameslamb)
  - Peter Andreas Entschev (https://github.com/pentschev)

Approvers:
  - Peter Andreas Entschev (https://github.com/pentschev)
  - Vyas Ramasubramani (https://github.com/vyasr)

URL: #1048

.readthedocs.yml

@@ -6,10 +6,10 @@ build:
     python: "mambaforge-22.9"
   jobs:
     post_create_environment:
+      # explicitly passing matrix-entry so that 'libucx' is pulled in,
+      # and therefore tested in this no-CUDA environment
       - |
         pip install \
-          --extra-index-url "https://pypi.anaconda.org/rapidsai-wheels-nightly/simple/" \
-          -C rapidsai.disable-cuda=true \
           -C rapidsai.matrix-entry="cuda=12.2" \
           .
 

ci/build_wheel.sh

@@ -13,7 +13,7 @@ rapids-generate-version > ./VERSION
 
 RAPIDS_PY_CUDA_SUFFIX="$(rapids-wheel-ctk-name-gen ${RAPIDS_CUDA_VERSION})"
 
-python -m pip wheel . -w dist --no-deps --disable-pip-version-check
+python -m pip wheel . -w dist --no-deps --disable-pip-version-check --config-settings rapidsai.disable-cuda=false
 
 mkdir -p final_dist
 python -m auditwheel repair \

dependencies.yaml

@@ -142,17 +142,20 @@ dependencies:
           - --extra-index-url=https://pypi.nvidia.com
           - --extra-index-url=https://pypi.anaconda.org/rapidsai-wheels-nightly/simple
     specific:
+      # very tight >=x.x.x,<x.x.(x+1) here allows for installation of
+      # post release like 1.15.0.post1
       - output_types: [requirements, pyproject]
         matrices:
           - matrix: {cuda: "12.*"}
             packages:
-              - libucx-cu12==1.15.0
+              - libucx-cu12>=1.15.0,<1.15.1
           - matrix: {cuda: "11.*"}
             packages:
-              - libucx-cu11==1.15.0
+              - libucx-cu11>=1.15.0,<1.15.1
+          # this fallback is intentionally empty... it simplifies building from source
+          # without CUDA, e.g. 'pip install .'
           - matrix: null
-            packages:
-              - libucx==1.15.0
+            packages: null
   depends_on_ucx_run:
     common:
       - output_types: conda
@@ -172,9 +175,10 @@ dependencies:
           - matrix: {cuda: "11.*"}
             packages:
               - libucx-cu11>=1.15.0,<1.16
+          # this fallback is intentionally empty... it simplifies building from source
+          # without CUDA, e.g. 'pip install .'
           - matrix: null
-            packages:
-              - libucx>=1.15.0,<1.16
+            packages: null
   test_python:
     common:
       - output_types: [conda, requirements, pyproject]

docker/ucx-py-cuda11.5.yml

@@ -7,7 +7,7 @@ dependencies:
   - python=3.9
   - cudatoolkit=11.5
   - setuptools
-  - cython>=0.29.14,<3.0.0a0
+  - cython>=3.0.0
   - pytest
   - pytest-asyncio
   - dask

docs/source/install.rst

@@ -46,15 +46,40 @@ be done if desired (e.g., to test for new capabilities or bug fixes).
     conda create -n ucx -c conda-forge -c rapidsai \
       cudatoolkit=<CUDA version> ucx-py
 
+PyPI
+----
+
+PyPI installation is possible and currently supports two variants: CUDA
+version ``11`` and ``12``. Both packages are compatible with CPU-only
+workloads and either one can be chosen if the application doesn't use
+CUDA, but currently there are no pre-built CPU-only packages available,
+so either one of CUDA packages must be installed instead. The CUDA
+version is differentiated by the suffix ``-cuXY``, where ``XY`` must be
+replaced with the desired CUDA version. Installing CUDA ``12`` package
+can be done with the following command:
+
+::
+
+    pip install ucx-py-cu12
+
+
+UCX-Py has no direct dependency on CUDA, but the package specifies the
+``-cuXY`` prefix so that the correct ``libucx-cuXY`` package is selected.
+This is also the reason why there are no CPU-only UCX-Py packages
+available at the moment, CPU-only builds of the UCX library are not
+currently available in PyPI.
 
 Source
 ------
 
-The following instructions assume you'll be using UCX-Py on a CUDA enabled system and is in a `Conda environment <https://docs.conda.io/projects/conda/en/latest/>`_.
+Conda
+~~~~~
+
+The following instructions assume you'll be using UCX-Py on a CUDA-enabled system and is in a `Conda environment <https://docs.conda.io/projects/conda/en/latest/>`_.
 
 
 Build Dependencies
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -67,7 +92,7 @@ Build Dependencies
     only Python 3.9, 3.10, and 3.11.
 
 Test Dependencies
-~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -78,7 +103,7 @@ Test Dependencies
 
 
 UCX >= 1.11.1
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 Instructions for building UCX >= 1.11.1 (minimum version supported by UCX-Py), make sure to change ``git checkout v1.11.1`` to a newer version if desired:
 
@@ -99,7 +124,7 @@ Instructions for building UCX >= 1.11.1 (minimum version supported by UCX-Py), m
 
 
 UCX + rdma-core
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 It is possible to enable InfiniBand support via the conda-forge rdma-core package. To do so, first activate the environment created previously and install conda-forge compilers and rdma-core:
 
@@ -127,7 +152,7 @@ After installing the necessary dependencies, it's now time to build UCX from sou
 
 
 UCX + MOFED
-~~~~~~~~~~~
+^^^^^^^^^^^
 
 It is still possible to build UCX and use the MOFED system install. Unlike the case above, we must not install conda-forge compilers, this
 is because conda-forge compilers can't look for libraries in the system directories (e.g., ``/usr``). Additionally, the rdma-core conda-forge package
@@ -161,9 +186,32 @@ to adjust that for the path to your system compilers. For example:
 
 
 UCX-Py
-~~~~~~
+^^^^^^
+
+Building and installing UCX-Py can be done via ``pip install``. For example:
+
+::
+
+    conda activate ucx
+    git clone https://github.com/rapidsai/ucx-py.git
+    cd ucx-py
+    pip install -v .
+    # or for develop build
+    pip install -v -e .
+
+
+PyPI
+~~~~
+
+The following instructions assume you'll be installing UCX-Py on a CUDA-enabled system, in a pip-only environment.
+
+Installing UCX-Py from source in a pip-only environment has additional limitations when compared to conda environments. Unlike conda packages, where the ``ucx`` package is installed under the ``CONDA_PREFIX``, ``libucx`` is installed under ``site-packages`` which is normally not looked for system libraries. Therefore, you will either need UCX to be installed in the system path, or include the UCX install path in ``LD_LIBRARY_PATH``.
+
+
+UCX-Py with UCX system install
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Building and installing UCX-Py can be done via `pip install`. For example:
+If a UCX system install is available, building and installing UCX-Py can be done via ``pip install`` with no additional requirements. For example:
 
 ::
 
@@ -173,3 +221,40 @@ Building and installing UCX-Py can be done via `pip install`. For example:
     pip install -v .
     # or for develop build
     pip install -v -e .
+
+
+UCX-Py with custom UCX install
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If UCX is installed in a non-default path, specifying ``LD_LIBRARY_PATH`` is required both to install and run UCX-Py code. For installation, ``LD_LIBRARY_PATH`` is required to ensure UCX-Py builds against the desired version of UCX, since another incompatible UCX version may already be installed in the system. Running UCX-Py code also needs to find the proper UCX libraries at runtime, and thus ``LD_LIBRARY_PATH`` must be specified as well.
+
+A custom UCX install does not necessarily mean it needs to be build from source, a ``libucx-cuXY`` package may be used as well. For example, with the CUDA ``12`` package:
+
+::
+
+    pip install libucx-cu12
+
+The above will install the UCX library in your environment, specifically under ``site-packages/libucx``. To find the path to ``site-packages`` you may execute:
+
+::
+
+    python -c "import site; print(site.getsitepackages()[0])"
+
+The command above will print the path to ``site-packages``, such as ``/opt/python/site-packages``. The path to the UCX shared library installation is then ``/opt/python/site-packages/libucx/lib``, which is the value that will be specified for ``LD_LIBRARY_PATH``. If you build UCX from source and installed it in a different location, make sure you adjust the value of ``LD_LIBRARY_PATH`` accordingly, or if you built UCX from source and installed it in a path that the system will lookup for libraries by default, specifying ``LD_LIBRARY_PATH`` is unnecessary.
+
+Now installing UCX-Py can be done via ``pip install``:
+
+::
+
+    conda activate ucx
+    git clone https://github.com/rapidsai/ucx-py.git
+    cd ucx-py
+    LD_LIBRARY_PATH=/opt/python/site-packages/libucx/lib pip install -v .
+    # or for develop build
+    LD_LIBRARY_PATH=/opt/python/site-packages/libucx/lib pip install -v -e .
+
+Now, to run UCX-Py-enabled code specifying ``LD_LIBRARY_PATH`` will also be required. For example:
+
+::
+
+    LD_LIBRARY_PATH=/opt/python/site-packages/libucx/lib python -c "import ucp; print(ucp.get_ucx_version())"

pyproject.toml

@@ -30,7 +30,6 @@ authors = [
 license = { text = "BSD-3-Clause" }
 requires-python = ">=3.9"
 dependencies = [
-    "libucx>=1.15.0,<1.16",
     "numpy>=1.23,<2.0a0",
     "pynvml>=11.4.1",
 ] # This list was generated by `rapids-dependency-file-generator`. To make changes, edit dependencies.yaml and run `rapids-dependency-file-generator`.
@@ -116,10 +115,12 @@ build-backend = "setuptools.build_meta"
 commit-files = [
     "ucp/COMMIT_FILE"
 ]
+# by default, do not rename the package 'ucx-py-cu${ver}'
+# (this is overridden in wheel publishing)
+disable-cuda=true
 dependencies-file = "dependencies.yaml"
 requires = [
     "cython>=3.0.0",
-    "libucx==1.15.0",
 ] # This list was generated by `rapids-dependency-file-generator`. To make changes, edit dependencies.yaml and run `rapids-dependency-file-generator`.
 
 [tool.setuptools]