From 63cadc42bfab80cc8a77267f5d16e39c550bcf9e Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Fri, 13 Sep 2024 11:54:54 -0700 Subject: [PATCH] add pyproject.toml and update docs (#1001) note this removes the old cross compile script ref #1000 * update docs --- .github/workflows/doxygen.yml | 2 +- cspell.config.yaml | 1 + docs/cross_compile.md | 37 ------------------ docs/python_wrapper.md | 43 +++++++++++---------- pyRF24/README.md | 25 +++++++++++++ pyRF24/crossunixccompiler.py | 70 ----------------------------------- pyRF24/pyproject.toml | 15 ++++++++ pyRF24/setup.py | 27 ++------------ 8 files changed, 68 insertions(+), 152 deletions(-) create mode 100644 pyRF24/README.md delete mode 100644 pyRF24/crossunixccompiler.py create mode 100644 pyRF24/pyproject.toml diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml index 7fc365a93..1f0457aee 100644 --- a/.github/workflows/doxygen.yml +++ b/.github/workflows/doxygen.yml @@ -50,5 +50,5 @@ jobs: uses: nRF24/.github/.github/workflows/build_docs.yaml@main with: deploy-gh-pages: ${{ github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/master') }} - doxygen-version: '1.11.0' + doxygen-version: '1.12.0' secrets: inherit diff --git a/cspell.config.yaml b/cspell.config.yaml index ebf65ffaf..713579a60 100644 --- a/cspell.config.yaml +++ b/cspell.config.yaml @@ -269,6 +269,7 @@ words: - vect - venv - vfpv + - virtualenv - vpfv - VSPI - Wcast diff --git a/docs/cross_compile.md b/docs/cross_compile.md index 2d3fabdf8..b1a43964b 100644 --- a/docs/cross_compile.md +++ b/docs/cross_compile.md @@ -61,40 +61,3 @@ Following prerequisites need to be assured: ```shell make upload ``` - -## Cross compilation steps for python wrapper - -### Prerequisites - -- Python setuptools must be installed on both target and cross-compilation machines - ```shell - sudo pip install setuptools - ``` - or - ```shell - sudo apt-get install python-setuptools - ``` - -### Installation steps - -1. Assure having libboost-python-dev library in your cross-compilation environment. Alternatively, you can install it into your target machine and copy /usr and /lib directories to the cross-compilation machine. - For example - ```shell - mkdir -p rpi_root && rsync -a pi@target_linux_host:/usr :/lib rpi_root - export CFLAGS="--sysroot=/your/dir/rpi_root -I/your/dir/rpi_root/usr/include/python2.7/" - ``` -2. Build the python wrapper - ```shell - cd pyRF24 - ./setup.py build --compiler=crossunix - ``` -3. Make the egg package - ```shell - ./setup.py bdist_egg --plat-name=cross - ``` - `dist/RF24--cross.egg` should be created. -4. Upload it to the target machine and install there: - ```shell - scp dist/RF24-*-cross.egg pi@target_linux_host: - ssh pi@target_linux_host 'sudo easy_install RF24-*-cross.egg' - ``` diff --git a/docs/python_wrapper.md b/docs/python_wrapper.md index cef706131..58e3935d6 100644 --- a/docs/python_wrapper.md +++ b/docs/python_wrapper.md @@ -17,7 +17,7 @@ We recommend using the newer [pyRF24 package](https://github.com/nRF24/pyRF24) 8. includes typing stub files for type checking tools like mypy The only reason that you should need to keep using these older individual python -wrappers is if you must to use python v3.6 or older. +wrappers is if you must use python v3.6 or older. You **cannot** use these individual wrappers in combination with the pyRF24 package. @endparblock @@ -33,6 +33,19 @@ python wrapper(s) to work. @note The interrupt_configure.py example uses the [gpiod library](https://pypi.org/project/gpiod) to watch the radio's IRQ pin. +> [!warning] +> Recent updates to pip mandate that users manage a python virtual environment. +> This is good practice because it avoids the risk that installing a package with pip will +> mess up a system-installed package. +> +> For information about using up a python virtual environment, see the official +> [instructions using the python standard library `venv`](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/) +> (which is a minimized variant of +> [the `virtualenv` library](https://virtualenv.pypa.io/en/stable/index.html)). +> +> There's also a note at the end of these instructions that talks about +> using `sudo` within a python virtual environment. + ### Python2 ```shell @@ -51,23 +64,17 @@ python -m pip install --upgrade pip setuptools sudo apt-get install python3-dev libboost-python-dev python3-pip ``` -Next, install some up-to-date python3 packages. - -```shell -python3 -m pip install --upgrade pip setuptools -``` - ## Installation -@note Only step 2 has to be repeated if installing the python wrappers for -RF24Network and RF24Mesh libraries. The prerequisites stated above still apply -to each library. +> [!note] +> If using **older versions of RF24* libraries** with python3, +> the setup.py script needed a manually created symlink for the boost.python library. +> ```shell +> sudo ln -s $(ls /usr/lib/$(ls /usr/lib/gcc | tail -1)/libboost_python3*.so | tail -1) /usr/lib/$(ls /usr/lib/gcc | tail -1)/libboost_python3.so +> ``` +> This is no longer needed with the latest versions of RF24 libraries. -1. For python3, setup.py needs a manually created symlink for the boost.python library: - ```shell - sudo ln -s $(ls /usr/lib/$(ls /usr/lib/gcc | tail -1)/libboost_python3*.so | tail -1) /usr/lib/$(ls /usr/lib/gcc | tail -1)/libboost_python3.so - ``` -2. Install the library. +1. Install the library. This step needs to be executed from the appropriate directory of the cloned RF24* repository: @@ -77,10 +84,6 @@ to each library. When in the correct directory, run the following command: ```shell - python setup.py install - ``` - or for python3 - ```shell python3 -m pip install -v . ``` @note Building/installing takes several minutes on arm-based machines. @@ -90,7 +93,7 @@ to each library. See the additional [Platform Support pages](pages.html) for information on connecting your hardware. See the included [\*.py files in the "examples_linux" folder](examples.html) for usage information. -3. Running the Example +2. Running the Example The python examples location differ for each RF24* repositories. - navigate to *examples_linux* directory in the RF24 cloned repository diff --git a/pyRF24/README.md b/pyRF24/README.md new file mode 100644 index 000000000..81384c9d6 --- /dev/null +++ b/pyRF24/README.md @@ -0,0 +1,25 @@ +# Individual python wrapper + +> [!warning] +> This python wrapper for the RF24 C++ library was not intended +> for distribution on pypi.org. Any such attempts to publish this package +> is unauthorized and unofficial. + +## Use pyRF24 instead + +We recommend using the newer [pyRF24](https://github.com/nRF24/pyRF24) package +[available from pypi](https://pypi.org/project/pyrf24/) because + +1. it is [practically drop-in compatible](https://nrf24.github.io/pyRF24/#migrating-to-pyrf24) +2. easier to install or get updates with popular package managers like pip +3. does not require the C++ libraries to be installed -- it uses its own isolated binaries +4. includes wrappers for RF24, RF24Network, RF24Mesh libraries +5. includes a new [fake BLE implementation](https://nrf24.github.io/pyRF24/ble_api.html) +6. has its own [dedicated documentation](https://nRF24.github.io/pyRF24) +7. is compatible with python's builtin `help()` +8. includes typing stub files for type checking tools like mypy + +The only reason that you should need to keep using these older individual python +wrappers is if you must use python v3.6 or older. + +You **cannot** use these individual wrappers in combination with the pyRF24 package. diff --git a/pyRF24/crossunixccompiler.py b/pyRF24/crossunixccompiler.py deleted file mode 100644 index 881d907d3..000000000 --- a/pyRF24/crossunixccompiler.py +++ /dev/null @@ -1,70 +0,0 @@ -import sys -from distutils import unixccompiler -from distutils import ccompiler - - -def register(): - sys.modules["distutils.crossunixccompiler"] = sys.modules[__name__] - ccompiler.compiler_class["crossunix"] = ( - __name__, - "CrossUnixCCompiler", - "UNIX-style compiler for cross compilation", - ) - - -def try_remove_all(lst, starts): - lst[:] = [x for x in lst if not x.startswith(starts)] - - -class CrossUnixCCompiler(unixccompiler.UnixCCompiler): - def _compile(self, obj, src, ext, cc_args, extra_postargs, pp_opts): - try_remove_all( - self.compiler_so, ("-m64", "-fstack-protector-strong", "-mtune=generic") - ) - try_remove_all(cc_args, "-I/usr") - try_remove_all(pp_opts, "-I/usr") - return unixccompiler.UnixCCompiler._compile( - self, obj, src, ext, cc_args, extra_postargs, pp_opts - ) - - def link( - self, - target_desc, - objects, - output_filename, - output_dir=None, - libraries=None, - library_dirs=None, - runtime_library_dirs=None, - export_symbols=None, - debug=0, - extra_preargs=None, - extra_postargs=None, - build_temp=None, - target_lang=None, - ): - try_remove_all(self.library_dirs, ("/usr")) - return unixccompiler.UnixCCompiler.link( - self, - target_desc, - objects, - output_filename, - output_dir, - libraries, - library_dirs, - runtime_library_dirs, - export_symbols, - debug, - extra_preargs, - extra_postargs, - build_temp, - target_lang, - ) - - def _fix_lib_args(self, libraries, library_dirs, runtime_library_dirs): - self.__class__ = unixccompiler.UnixCCompiler - ret = unixccompiler.UnixCCompiler._fix_lib_args( - self, libraries, library_dirs, runtime_library_dirs - ) - self.__class__ = CrossUnixCCompiler - return ret diff --git a/pyRF24/pyproject.toml b/pyRF24/pyproject.toml new file mode 100644 index 000000000..1f783371f --- /dev/null +++ b/pyRF24/pyproject.toml @@ -0,0 +1,15 @@ +[build-system] +requires = ["setuptools>=61"] +build-backend = "setuptools.build_meta" + +[project] +name = "RF24" +classifiers = [ + "Programming Language :: Python :: 2", + "Programming Language :: Python :: 3", + "Programming Language :: C++", + "License :: OSI Approved :: GNU General Public License v2 (GPLv2)", +] +license = {text = "GNU General Public License v2 (GPLv2)"} +readme = {file = "README.md", content-type = "text/markdown"} +dynamic = ["version"] # version is set in setup.py diff --git a/pyRF24/setup.py b/pyRF24/setup.py index 10129b07b..daf1d4038 100644 --- a/pyRF24/setup.py +++ b/pyRF24/setup.py @@ -3,7 +3,6 @@ import os from sys import version_info from setuptools import setup, Extension -import crossunixccompiler version = "" cflags = os.getenv("CFLAGS", "") @@ -74,33 +73,13 @@ os.environ["CFLAGS"] = cflags # get the proper boost.python lib symlink name according to version of python -if version_info >= (3,): - BOOST_LIB = "boost_python3" -else: - BOOST_LIB = "boost_python" - -crossunixccompiler.register() - -long_description = """ -.. warning:: This python wrapper for the RF24 C++ library was not intended - for distribution on pypi.org. If you're reading this, then this package - is likely unauthorized or unofficial. -""" +BOOST_LIB = "boost_python" + ( + "" if version_info < (3,) else "%d%d" % (version_info.major, version_info.minor) +) setup( - name="RF24", version=version, - license="GPLv2", - license_files=(os.path.join(git_dir, "LICENSE"),), - long_description=long_description, - long_description_content_type="text/x-rst", - classifiers=[ - "Programming Language :: Python :: 2", - "Programming Language :: Python :: 3", - "Programming Language :: C++", - "License :: OSI Approved :: GNU General Public License v2 (GPLv2)", - ], ext_modules=[ Extension( "RF24",