Skip to content

Commit

Permalink
add pyproject.toml and update docs (#1001)
Browse files Browse the repository at this point in the history
note this removes the old cross compile script

ref #1000

* update docs
  • Loading branch information
2bndy5 authored Sep 13, 2024
1 parent 25f1fbd commit 63cadc4
Show file tree
Hide file tree
Showing 8 changed files with 68 additions and 152 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/doxygen.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
1 change: 1 addition & 0 deletions cspell.config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -269,6 +269,7 @@ words:
- vect
- venv
- vfpv
- virtualenv
- vpfv
- VSPI
- Wcast
Expand Down
37 changes: 0 additions & 37 deletions docs/cross_compile.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-<version>-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'
```
43 changes: 23 additions & 20 deletions docs/python_wrapper.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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.
Expand All @@ -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
Expand Down
25 changes: 25 additions & 0 deletions pyRF24/README.md
Original file line number Diff line number Diff line change
@@ -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.
70 changes: 0 additions & 70 deletions pyRF24/crossunixccompiler.py

This file was deleted.

15 changes: 15 additions & 0 deletions pyRF24/pyproject.toml
Original file line number Diff line number Diff line change
@@ -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
27 changes: 3 additions & 24 deletions pyRF24/setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
import os
from sys import version_info
from setuptools import setup, Extension
import crossunixccompiler

version = ""
cflags = os.getenv("CFLAGS", "")
Expand Down Expand Up @@ -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",
Expand Down

0 comments on commit 63cadc4

Please sign in to comment.