Merge pull request #1943 from minrk/pyzmq_no_bundle

more consistent naming of build variables
zeromq · Feb 19, 2024 · 0a940b6 · 0a940b6
2 parents 0947190 + cd8faa6
commit 0a940b6
Show file tree

Hide file tree

Showing 3 changed files with 94 additions and 70 deletions.
diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml
@@ -10,7 +10,8 @@ on:
   pull_request:
     paths:
       - pyproject.toml
-      - setup.py
+      - CMakeLists.txt
+      - cmake/**
       - buildutils/**
       - .github/workflows/wheels.yml
       - tools/install_libzmq.sh

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -9,52 +9,56 @@ find_package(
   COMPONENTS Interpreter Development.Module
   REQUIRED)
 
+# legacy pyzmq env options, no PYZMQ_ prefix
 set(ZMQ_PREFIX "auto" CACHE STRING "libzmq installation prefix or 'bundled'")
 option(ZMQ_DRAFT_API "whether to build the libzmq draft API" OFF)
-set(LIBZMQ_BUNDLED_VERSION "4.3.5" CACHE STRING "libzmq version when bundling")
-set(LIBSODIUM_BUNDLED_VERSION "1.0.19" CACHE STRING "libsodium version when bundling")
-set(LIBZMQ_BUNDLED_URL "" CACHE STRING "full URL to download bundled libzmq")
-set(LIBSODIUM_BUNDLED_URL "" CACHE STRING "full URL to download bundled libsodium")
-set(LIBSODIUM_CONFIGURE_ARGS "" CACHE STRING "semicolon-separated list of arguments to pass to ./configure for bundled libsodium")
-set(LIBSODIUM_MSBUILD_ARGS "" CACHE STRING "semicolon-separated list of arguments to pass to msbuild for bundled libsodium")
-set(LIBSODIUM_VS_VERSION "" CACHE STRING "Visual studio solution version for bundled libsodium (default: detect from MSVC_VERSION)")
+
+# anything new should start with PYZMQ_
+option(PYZMQ_LIBZMQ_NO_BUNDLE "Prohibit building bundled libzmq. Useful for repackaging, to allow default search for libzmq and requiring it to succeed." OFF)
+set(PYZMQ_LIBZMQ_VERSION "4.3.5" CACHE STRING "libzmq version when bundling")
+set(PYZMQ_LIBSODIUM_VERSION "1.0.19" CACHE STRING "libsodium version when bundling")
+set(PYZMQ_LIBZMQ_URL "" CACHE STRING "full URL to download bundled libzmq")
+set(PYZMQ_LIBSODIUM_URL "" CACHE STRING "full URL to download bundled libsodium")
+set(PYZMQ_LIBSODIUM_CONFIGURE_ARGS "" CACHE STRING "semicolon-separated list of arguments to pass to ./configure for bundled libsodium")
+set(PYZMQ_LIBSODIUM_MSBUILD_ARGS "" CACHE STRING "semicolon-separated list of arguments to pass to msbuild for bundled libsodium")
+set(PYZMQ_LIBSODIUM_VS_VERSION "" CACHE STRING "Visual studio solution version for bundled libsodium (default: detect from MSVC_VERSION)")
 
 if (NOT CMAKE_BUILD_TYPE)
   # default to Release
   set(CMAKE_BUILD_TYPE "Release")
 endif()
 
 # get options from env
-if (DEFINED ENV{ZMQ_PREFIX})
-  set(ZMQ_PREFIX "$ENV{ZMQ_PREFIX}")
-endif()
 
-if (DEFINED ENV{ZMQ_DRAFT_API})
-  if ("$ENV{ZMQ_DRAFT_API}" STREQUAL "1")
-    set(ZMQ_DRAFT_API TRUE)
-  else()
-    set(ZMQ_DRAFT_API FALSE)
+# handle booleans
+foreach(_optname ZMQ_DRAFT_API PYZMQ_NO_BUNDLE)
+  if (DEFINED ENV{${_optname}})
+    if ("$ENV{${_optname}}" STREQUAL "1" OR "$ENV{${_optname}}" STREQUAL "ON")
+      set(${_optname} TRUE)
+    else()
+      set(${_optname} FALSE)
+    endif()
   endif()
-endif()
+endforeach()
 
-# load options from env with PYZMQ_ prefix
 foreach(_optname
-  LIBZMQ_BUNDLED_VERSION
-  LIBZMQ_BUNDLED_URL
-  LIBSODIUM_BUNDLED_VERSION
-  LIBSODIUM_BUNDLED_URL
-  LIBSODIUM_CONFIGURE_ARGS
-  LIBSODIUM_MSBUILD_ARGS
-  LIBSODIUM_VS_VERSION
+  ZMQ_PREFIX
+  PYZMQ_LIBZMQ_VERSION
+  PYZMQ_LIBZMQ_URL
+  PYZMQ_LIBSODIUM_VERSION
+  PYZMQ_LIBSODIUM_URL
+  PYZMQ_LIBSODIUM_CONFIGURE_ARGS
+  PYZMQ_LIBSODIUM_MSBUILD_ARGS
+  PYZMQ_LIBSODIUM_VS_VERSION
 )
-  if (DEFINED ENV{PYZMQ_${_optname}})
+  if (DEFINED ENV{${_optname}})
     if (_optname MATCHES ".*_ARGS")
       # if it's an _ARGS, split "-a -b" into "-a" "-b"
       # use native CMake lists for cmake args,
       # native command-line strings for env variables
-      separate_arguments(${_optname} NATIVE_COMMAND "$ENV{PYZMQ_${_optname}}")
+      separate_arguments(${_optname} NATIVE_COMMAND "$ENV{${_optname}}")
     else()
-      set(${_optname} "$ENV{PYZMQ_${_optname}}")
+      set(${_optname} "$ENV{${_optname}}")
     endif()
   endif()
 endforeach()
@@ -64,12 +68,12 @@ if(ZMQ_DRAFT_API)
   add_compile_definitions(ZMQ_BUILD_DRAFT_API=1)
 endif()
 
-if (LIBSODIUM_BUNDLED_VERSION AND NOT LIBSODIUM_BUNDLED_URL)
-  set(LIBSODIUM_BUNDLED_URL "https://download.libsodium.org/libsodium/releases/libsodium-${LIBSODIUM_BUNDLED_VERSION}.tar.gz")
+if (PYZMQ_LIBSODIUM_VERSION AND NOT PYZMQ_LIBSODIUM_URL)
+  set(PYZMQ_LIBSODIUM_URL "https://download.libsodium.org/libsodium/releases/libsodium-${PYZMQ_LIBSODIUM_VERSION}.tar.gz")
 endif()
 
-if (LIBZMQ_BUNDLED_VERSION AND NOT LIBZMQ_BUNDLED_URL)
-  set(LIBZMQ_BUNDLED_URL "https://github.com/zeromq/libzmq/releases/download/v${LIBZMQ_BUNDLED_VERSION}/zeromq-${LIBZMQ_BUNDLED_VERSION}.tar.gz")
+if (PYZMQ_LIBZMQ_VERSION AND NOT PYZMQ_LIBZMQ_URL)
+  set(PYZMQ_LIBZMQ_URL "https://github.com/zeromq/libzmq/releases/download/v${PYZMQ_LIBZMQ_VERSION}/zeromq-${PYZMQ_LIBZMQ_VERSION}.tar.gz")
 endif()
 
 #------- bundle libzmq ------
@@ -124,8 +128,13 @@ if (ZMQ_PREFIX STREQUAL "auto")
   endif()
 
   if (NOT ZeroMQ_FOUND)
-    message(CHECK_FAIL "libzmq not found, will bundle libzmq and libsodium")
-    set(ZMQ_PREFIX "bundled")
+    if (PYZMQ_NO_BUNDLE)
+      message(CHECK_FAIL "libzmq not found")
+      message(FATAL_ERROR "aborting because bundled libzmq is disabled")
+    else()
+      message(CHECK_FAIL "libzmq not found, will bundle libzmq and libsodium")
+      set(ZMQ_PREFIX "bundled")
+    endif()
   endif()
 elseif (NOT ZMQ_PREFIX STREQUAL "bundled")
   message(CHECK_START "Looking for libzmq in ${ZMQ_PREFIX}")
@@ -168,7 +177,7 @@ if (ZMQ_PREFIX STREQUAL "bundled")
   endif()
 
   FetchContent_Declare(bundled_libsodium
-    URL ${LIBSODIUM_BUNDLED_URL}
+    URL ${PYZMQ_LIBSODIUM_URL}
     PREFIX ${BUNDLE_DIR}
   )
   FetchContent_MakeAvailable(bundled_libsodium)
@@ -179,18 +188,18 @@ if (ZMQ_PREFIX STREQUAL "bundled")
     message(STATUS "building bundled libsodium")
     if (MSVC)
       # select vs build solution by msvc version number
-      if (NOT LIBSODIUM_VS_VERSION)
+      if (NOT PYZMQ_LIBSODIUM_VS_VERSION)
         if(MSVC_VERSION GREATER 1940)
           message(STATUS "Unrecognized MSVC_VERSION=${MSVC_VERSION}")
           set(MSVC_VERSION 1939)
         endif()
 
         if(MSVC_VERSION GREATER_EQUAL 1930)
-          set(LIBSODIUM_VS_VERSION "2022")
+          set(PYZMQ_LIBSODIUM_VS_VERSION "2022")
         elseif(MSVC_VERSION GREATER_EQUAL 1920)
-          set(LIBSODIUM_VS_VERSION "2019")
+          set(PYZMQ_LIBSODIUM_VS_VERSION "2019")
         elseif(MSVC_VERSION GREATER_EQUAL 1910)
-          set(LIBSODIUM_VS_VERSION "2017")
+          set(PYZMQ_LIBSODIUM_VS_VERSION "2017")
         else()
           message(FATAL_ERROR "unsupported bundling libsodium for MSVC_VERSION=${MSVC_VERSION} (need at least VS2017)")
         endif()
@@ -203,9 +212,9 @@ if (ZMQ_PREFIX STREQUAL "bundled")
         "/v:n"
         "/p:Configuration=Static${CMAKE_BUILD_TYPE}"
         "/p:Platform=${CMAKE_GENERATOR_PLATFORM}"
-        "builds/msvc/vs${LIBSODIUM_VS_VERSION}/libsodium.sln"
+        "builds/msvc/vs${PYZMQ_LIBSODIUM_VS_VERSION}/libsodium.sln"
       )
-      list(APPEND libsodium_build ${LIBSODIUM_MSBUILD_ARGS})
+      list(APPEND libsodium_build ${PYZMQ_LIBSODIUM_MSBUILD_ARGS})
       execute_process(
         COMMAND ${libsodium_build}
         WORKING_DIRECTORY ${bundled_libsodium_SOURCE_DIR}
@@ -223,7 +232,7 @@ if (ZMQ_PREFIX STREQUAL "bundled")
         --disable-shared
         --enable-static
       )
-      list(APPEND libsodium_configure ${LIBSODIUM_CONFIGURE_ARGS})
+      list(APPEND libsodium_configure ${PYZMQ_LIBSODIUM_CONFIGURE_ARGS})
       execute_process(
         COMMAND ${libsodium_configure}
         WORKING_DIRECTORY ${bundled_libsodium_SOURCE_DIR}
@@ -259,7 +268,7 @@ if (ZMQ_PREFIX STREQUAL "bundled")
   set(BUILD_STATIC ON)
 
   FetchContent_Declare(bundled_libzmq
-    URL ${LIBZMQ_BUNDLED_URL}
+    URL ${PYZMQ_LIBZMQ_URL}
     PREFIX ${BUNDLE_DIR}
     CMAKE_ARGS ${LIBZMQ_CMAKE_ARGS}
     EXCLUDE_FROM_ALL

diff --git a/docs/source/howto/build.md b/docs/source/howto/build.md
@@ -6,7 +6,7 @@ pyzmq publishes around a hundred wheels for each release, so hopefully very few
 
 pyzmq 26 has a whole new build system using CMake via [scikit-build-core].
 
-~all options can be specified via environment variables, in order to play nicely with pip.
+~all options can be specified via environment variables with the same name, in order to play nicely with pip.
 
 ## Installing from source
 
@@ -46,7 +46,7 @@ First, some quick examples of influencing pyzmq's build.
 Build a wheel against already-installed libzmq:
 
 ```bash
-ZMQ_PREFIX=/usr/local
+export ZMQ_PREFIX=/usr/local
 python3 -m pip install --no-binary pyzmq pyzmq
 ```
 
@@ -83,7 +83,18 @@ If pyzmq doesn't find your libzmq via the default search, or you want to skip th
 ZMQ_PREFIX=/path/to/zmq  # should contain 'include', 'lib', etc.
 ```
 
-If you tell pyzmq where to look, it will not try to build if it doesn't find libzmq there, rather than falling back on bundled libzmq.
+### Disabling bundled build fallback
+
+You may want to keep the default search,
+which will import targets from CMake, pkg-config, etc.,
+but make _sure_ libzmq is found.
+
+To do this, set PYZMQ_NO_BUNDLE.
+If you set only this, pyzmq will still search via standard means, but _fail_ if libzmq is not found, rather than falling back on the bundled static library.
+
+```bash
+-DPYZMQ_NO_BUNDLE=ON
+```
 
 ## Building bundled libzmq
 
@@ -109,20 +120,20 @@ or `msbuild` on Windows:
 msbuild /m /v:n /p:Configuration=StaticRelease /pPlatform=x64 builds/msvc/vs2022/libsodium.sln
 ```
 
-You can _add_ arguments to configure with a semicolon-separated list, by specifying `PYZMQ_LIBSODIUM_CONFIGURE_ARGS` environment variable, or `LIBSODIUM_CONFIGURE_ARGS` CMake variable.
+You can _add_ arguments to configure with a semicolon-separated list, by specifying `PYZMQ_LIBSODIUM_CONFIGURE_ARGS` variable:
 
 ```bash
 PYZMQ_LIBSODIUM_CONFIGURE_ARGS="--without-pthread --enable-minimal"
 # or
-CMAKE_ARGS="-DLIBSODIUM_CONFIGURE_ARGS=--without-pthread;--enable-minimal"
+CMAKE_ARGS="-DPYZMQ_LIBSODIUM_CONFIGURE_ARGS=--without-pthread;--enable-minimal"
 ```
 
-and `[PYZMQ_]LIBSODIUM_MSBUILD_ARGS` on Windows:
+and `PYZMQ_LIBSODIUM_MSBUILD_ARGS` on Windows:
 
 ```bash
 PYZMQ_LIBSODIUM_MSBUILD_ARGS="/something /else"
 # or
-CMAKE_ARGS="-DLIBSODIUM_MSBUILD_ARGS=/something;/else"
+CMAKE_ARGS="-DPYZMQ_LIBSODIUM_MSBUILD_ARGS=/something;/else"
 ```
 
 ```{note}
@@ -148,15 +159,15 @@ CMAKE_ARGS="-DWITH_OPENPGM=ON"
 You can specify which version of libsodium/libzmq to bundle with:
 
 ```
--DLIBZMQ_BUNDLED_VERSION=4.3.5
--DLIBSODIUM_BUNDLED_VERSION=1.0.19
+-DPYZMQ_LIBZMQ_VERSION=4.3.5
+-DPYZMQ_LIBSODIUM_VERSION=1.0.19
 ```
 
 or the specify the full URL to download (e.g. to test bundling an unreleased version):
 
 ```
--DLIBZMQ_BUNDLED_URL="https://github.com/zeromq/libzmq/releases/download/v4.3.5/zeromq-4.3.5.tar.gz"
--DLIBSODIUM_BUNDLED_URL="https://download.libsodium.org/libsodium/releases/libsodium-1.0.19.tar.gz"
+-DPYZMQ_LIBZMQ_URL="https://github.com/zeromq/libzmq/releases/download/v4.3.5/zeromq-4.3.5.tar.gz"
+-DPYZMQ_LIBSODIUM_URL="https://download.libsodium.org/libsodium/releases/libsodium-1.0.19.tar.gz"
 ```
 
 ```{warning}
@@ -171,20 +182,20 @@ but it's not really meant to be customizable; it's meant to allow you to workaro
 
 libsodium ships several solutions for msbuild, identified by `/builds/msvc/vs{year}/libsodium.sln`.
 pyzmq tries to guess which solution to use based on the MSVC_VERSION CMake variable,
-but you can skip the guess by specifying `-D LIBSODIUM_VS_VERSION=2022` to explicitly use the vs2022 solution.
+but you can skip the guess by specifying `-D PYZMQ_LIBSODIUM_VS_VERSION=2022` to explicitly use the vs2022 solution.
 
 ## Passing arguments
 
 pyzmq has a few CMake options to influence the build. All options are settable as environment variables, as well.
-Other than `ZMQ_PREFIX` and `ZMQ_DRAFT_API`, environment variables for building pyzmq have the prefix `PYZMQ_`.
+Other than `ZMQ_PREFIX` and `ZMQ_DRAFT_API` which have been around forever, environment variables for building pyzmq have the prefix `PYZMQ_`.
 
 The `_ARGS` variables that are meant to pass-through command-line strings accept standard command-line format from environment, or semicolon-separated lists when specified directly to cmake.
 
 So
 
 ```bash
 export ZMQ_PREFIX=bundled
-export PYZMQ_LIBZMQ_BUNDLED_VERSION=4.3.4
+export PYZMQ_LIBZMQ_VERSION=4.3.4
 export PYZMQ_LIBSODIUM_CONFIGURE_ARGS=--disable-pie --minimal
 
 python3 -m build .
@@ -193,7 +204,7 @@ python3 -m build .
 is equivalent to
 
 ```bash
-export CMAKE_ARGS="-DZMQ_PREFIX=bundled -DLIBZMQ_BUNDLED_VERSION=4.3.4 -DLIBSODIUM_CONFIGURE_ARGS=--disable-pie;--minimal"
+export CMAKE_ARGS="-DZMQ_PREFIX=bundled -DPYZMQ_LIBZMQ_VERSION=4.3.4 -DPYZMQ_LIBSODIUM_CONFIGURE_ARGS=--disable-pie;--minimal"
 python3 -m build .
 ```
 
@@ -205,34 +216,37 @@ Most cmake options can be seen below:
 <summary>
 
 `cmake -LH` output for pyzmq, which can be passed via `CMAKE_ARGS`.
-Most of these can also be specified via `PYZMQ_` environment variables.
+Most of these can also be specified via environment variables.
 
 </summary>
 
 ```bash
 # Path to a program.
 CYTHON:FILEPATH=$PREFIX/bin/cython
 
-# full URL to download bundled libsodium
-LIBSODIUM_BUNDLED_URL:STRING=
-
-# libsodium version when bundling
-LIBSODIUM_BUNDLED_VERSION:STRING=1.0.19
-
 # semicolon-separated list of arguments to pass to ./configure for bundled libsodium
-LIBSODIUM_CONFIGURE_ARGS:STRING=
+PYZMQ_LIBSODIUM_CONFIGURE_ARGS:STRING=
 
 # semicolon-separated list of arguments to pass to msbuild for bundled libsodium
-LIBSODIUM_MSBUILD_ARGS:STRING=
+PYZMQ_LIBSODIUM_MSBUILD_ARGS:STRING=
+
+# full URL to download bundled libsodium
+PYZMQ_LIBSODIUM_URL:STRING=
+
+# libsodium version when bundling
+PYZMQ_LIBSODIUM_VERSION:STRING=1.0.19
 
 # Visual studio solution version for bundled libsodium (default: detect from MSVC_VERSION)
-LIBSODIUM_VS_VERSION:STRING=
+PYZMQ_LIBSODIUM_VS_VERSION:STRING=
 
 # full URL to download bundled libzmq
-LIBZMQ_BUNDLED_URL:STRING=
+PYZMQ_LIBZMQ_URL:STRING=
 
 # libzmq version when bundling
-LIBZMQ_BUNDLED_VERSION:STRING=4.3.5
+PYZMQ_LIBZMQ_VERSION:STRING=4.3.5
+
+# Prohibit building bundled libzmq. Useful for repackaging, to allow default search for libzmq and requiring it to succeed.
+PYZMQ_NO_BUNDLE:BOOL=OFF
 
 # whether to build the libzmq draft API
 ZMQ_DRAFT_API:BOOL=OFF