Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update python readme and add py-wheel command #5912

Merged
merged 2 commits into from
Apr 11, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 25 additions & 1 deletion BUILD.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,9 +66,33 @@ Rerun is available as a package on PyPi and can be installed with `pip install r
Additionally, prebuilt dev wheels from head of main are available at <https://github.com/rerun-io/rerun/releases/tag/prerelease>.

If you want to build from source, you can do so easily in the pixi environment:
* Run `pixi run py-build-release` to build SDK & viewer for python (or `pixi run py-build` for a debug build)
* Run `pixi run py-build --release` to build SDK & viewer for python (or `pixi run py-build` for a debug build)
* Then you can run examples from the repository, either by making the pixi shell active with `pixi shell` and then running python or by using `pixi run`, e.g. `pixi run python examples/python/minimal/main.py`


### Tests & Tooling

```sh
# Run the unit tests
pixi run py-test

# Run the linting checks
pixi run py-lint

# Run the formatter
pixi run py-fmt
```

### Building an installable Python Wheel
The `py-wheel` command builds a whl file:
```sh
pixi run py-wheel --release
```
Which you can then install in your own python environment:
```sh
pip install ./target/wheels/*.whl
```

## Building and installing the Rerun C++ SDK

On Windows you have to have a system install of Visual Studio 2022 in order to compile the SDK and samples.
Expand Down
2 changes: 1 addition & 1 deletion pixi.toml
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ py-fmt-check = "ruff format --check --config rerun_py/pyproject.toml"
py-lint = "mypy --install-types --non-interactive --no-warn-unused-ignore"

py-build = "maturin develop --manifest-path rerun_py/Cargo.toml --extras=tests"
py-build-release = "maturin develop --release --manifest-path rerun_py/Cargo.toml --extras=tests"
py-wheel = "maturin build --manifest-path rerun_py/Cargo.toml"

# Run the Python tests.
# Don't call this on CI - use `nox` to run tests on all supported Python versions instead.
Expand Down
114 changes: 17 additions & 97 deletions rerun_py/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# The Rerun Python Log SDK
# The Rerun Python SDK

Use the Rerun SDK to log data like images, tensors, point clouds, and text. Logs are streamed to the Rerun Viewer for live visualization or to file for later use.
Use the Rerun SDK to record data like images, tensors, point clouds, and text. Data is streamed to the Rerun Viewer for live visualization or to file for later use.

<p align="center">
<img width="800" alt="Rerun Viewer" src="https://github.com/rerun-io/rerun/assets/2624717/c4900538-fc3a-43b8-841a-8d226e7b5a2e">
Expand All @@ -15,6 +15,8 @@ pip3 install rerun-sdk
ℹ️ Note:
The Python module is called `rerun`, while the package published on PyPI is `rerun-sdk`.

For other SDK languages see [Installing Rerun](https://www.rerun.io/docs/getting-started/installing-viewer).

## Example
```py
import rerun as rr
Expand Down Expand Up @@ -47,114 +49,32 @@ python3 -m rerun

In a second terminal, run the example with the `--connect` option:
```sh
python3 python examples/python/plots/main.py --connect
python3 examples/python/plots/main.py --connect
```
Note that SDK and Viewer can run on different machines!

-------------------------

# From source

Setup:

* Install the Rust toolchain: <https://rustup.rs/>
* `git clone [email protected]:rerun-io/rerun.git && cd rerun`
* Run `./scripts/setup_dev.sh`.
* Make sure `cargo --version` prints `1.74.0` once you are done
# Building Rerun from source

## Building
To build from source and install Rerun into your *current* Python environment run:
We use the [`pixi`](https://prefix.dev/) for managing dev-tool versioning, download and task running. See [here](https://github.com/casey/just#installation) for installation instructions.

```sh
python3 -m pip install --upgrade pip
pip3 install -r rerun_py/requirements-build.txt
pip3 install "./rerun_py"
pixi run py-build --release
```
To build SDK & viewer for python (or `pixi run py-build` for a debug build) and install it in the pixi environment.

ℹ️ Note:
If you are unable to upgrade pip to version `>=21.3`, you need to pass `--use-feature=in-tree-build` to the `pip3 install` command.

## Development

To set up a new virtualenv for development:
You can then run examples from the repository, either by making the pixi shell active with `pixi shell` and then running python or by using `pixi run`, e.g. `pixi run python examples/python/minimal/main.py`.

Respectively, to build a wheel instead for manual install use:
```sh
just py-dev-env
# For bash/zsh users:
source venv/bin/activate
# Or if you're using fish:
source venv/bin/activate.fish
pixi run py-wheel --release
```

## Build, test, and run
Refer to [BUILD.md](../BUILD.md) for details on the various different build options of the Rerun Viewer and SDKs for all target languages.

For ease of development you can build and install in "editable" mode. This means you can edit the `rerun` Python code without having to re-build and install to see changes.

```sh
# Build the SDK and install in develop mode into the virtualenv
# Re-run this if the Rust code has changed!
source venv/bin/activate
just py-build
```

### Test
```sh
# Run the unit tests
just py-test
# Installing a pre-release

# Run the linting checks
just py-lint
Prebuilt dev wheels from head of main are available at <https://github.com/rerun-io/rerun/releases/tag/prerelease>.

# Run an example
python examples/python/minimal/main.py
```

## Building an installable Python Wheel
The Python bindings to the core Rust library are built using https://github.com/PyO3/pyo3.

To build an installable Python wheel run:
```
pip install -r rerun_py/requirements-build.txt
maturin build -m rerun_py/Cargo.toml --release
```

By default the wheels will be built to `target/wheels` (use the `-o` flag to set a different output directory).

Now you can install `rerun` in any Python3 environment using:

```sh
pip3 install target/wheels/*.whl
```

## Viewing the docs locally
The rerun python docs are generated using `mkdocs`

Install the doc requirements:
```
pip install -r rerun_py/requirements-doc.txt
```

Serve the docs:
```sh
mkdocs serve -f rerun_py/mkdocs.yml -w rerun_py
```
or
```sh
just py-docs-serve
```

For information on how the docs system works, see: [docs/writing_docs.md](docs/writing_docs.md)


## Troubleshooting
You can run with `RUST_LOG=debug` to get more output out of the rerun SDK.

If you are using an Apple-silicon Mac, make sure `rustc -vV` outputs `host: aarch64-apple-darwin`. If not, this should fix it:

``` sh
rustup set default-host aarch64-apple-darwin && rustup install 1.74
```

If you want to switch back, this is how:
``` sh
rustup set default-host x86_64-apple-darwin && rustup install 1.74
```
While we try to keep the main branch usable at all times, it may be unstable occasionally. Use at your own risk.
Loading