Skip to content

Commit db5e58a

Browse files
threexcthreexc
committed
docs: convert old docs for GitHub Pages
This includes an update to the "Motivation" section to reflect the current project status, as the old docs had outdated info about the broader ecosystem (e.g. manylinux) support. Signed-off-by: Trevor Gamblin <tgamblin@baylibre.com>
1 parent 2d36cc9 commit db5e58a

7 files changed

Lines changed: 463 additions & 0 deletions

File tree

‎docs/_config.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
title: RISE Python Wheels
2+
description: riscv64 binary wheels for popular Python projects
3+
remote_theme: just-the-docs/just-the-docs
4+
5+
url: https://riseproject-dev.github.io
6+
baseurl: /python-wheels
7+
8+
plugins:
9+
- jekyll-remote-theme
10+
11+
color_scheme: light
12+
search_enabled: true
13+
heading_anchors: true
14+
15+
aux_links:
16+
"GitHub":
17+
- "https://github.com/riseproject-dev/python-wheels"
18+
19+
exclude:
20+
- packages/generate_packages_doc.py
21+
- packages/*.yaml

‎docs/index.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: Home
3+
layout: default
4+
nav_order: 1
5+
---
6+
7+
# RISE Python Wheels
8+
9+
RISE Python Wheels is a public project enabling RISC-V support for the Python
10+
ecosystem. It uses the RISE [RISC-V
11+
Runners](https://riscv-runners.riseproject.dev/) project to build wheels on
12+
native riscv64 hardware, with the goal of maintaining a riscv64-specific
13+
package repository for projects where upstream are not yet ready or able to
14+
perform builds themselves.
15+
16+
This work continues the earlier
17+
[wheel_builder](https://gitlab.com/riseproject/python/wheel_builder) project,
18+
which hosts binary wheels for a variety of Python modules.
19+
20+
For more information about RISE, visit the [project
21+
website](https://riseproject.dev/).
22+
23+
## Sections
24+
25+
- [Motivation](motivation.html)
26+
- [Installing the Packages](install.html)
27+
- [Manylinux_2_35 and Manylinux_2_39](manylinux.html)
28+
- [Supported Packages](packages/)
29+
- [Infrastructure](infrastructure.html)

‎docs/infrastructure.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
---
2+
title: Infrastructure
3+
layout: default
4+
nav_order: 6
5+
---
6+
17
# Infrastructure
28

39
The [python-wheels](https://github.com/riseproject-dev/python-wheels) project

‎docs/install.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: Installing the Packages
3+
layout: default
4+
nav_order: 3
5+
---
6+
7+
# Installing the Packages
8+
9+
The built wheels are hosted in the [package
10+
registry](https://gitlab.com/riseproject/python/wheel_builder/-/packages)
11+
associated with the riseproject/python/wheel_builder project. To install them,
12+
first upgrade pip to the latest version, e.g.,
13+
14+
```bash
15+
python -m pip install --upgrade pip
16+
```
17+
18+
and then pass the `--index-url` option to the install command to tell pip to
19+
pull packages from the registry associated with this project, e.g.,
20+
21+
```bash
22+
python -m pip install scipy --index-url https://gitlab.com/api/v4/projects/riseproject%2Fpython%2Fwheel_builder/packages/pypi/simple
23+
```
24+
25+
{: .note }
26+
> Some riscv64 packages are now built and published upstream on PyPI. We will
27+
> no longer build, upgrade and publish them as part of the wheel_builder
28+
> project.
29+
>
30+
> To make sure to always install the latest version available, use
31+
>
32+
> ```bash
33+
> python -m pip install scipy --prefer-binary --extra-index-url https://gitlab.com/api/v4/projects/riseproject%2Fpython%2Fwheel_builder/packages/pypi/simple
34+
> ```
35+
>
36+
> This will:
37+
>
38+
> - search both PyPI and the internal registry.
39+
> - pick the highest available version.
40+
> - prefer binary wheels over source distributions.
41+
>
42+
> This ensures we get wheels from PyPI when available, while falling back to
43+
> our registry for packages without riscv64 wheels, avoiding unnecessary source
44+
> builds.
45+
46+
{: .warning }
47+
> In general, `--extra-index-url` should be used very carefully (see
48+
> <https://peps.python.org/pep-0708/#motivation>).
49+
>
50+
> The wheel_builder registry only contains wheels for packages that have
51+
> pre-existing counterparts in PyPI, so it is safe to use it in that context.

‎docs/manylinux.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: Manylinux_2_35 and Manylinux_2_39
3+
layout: default
4+
nav_order: 4
5+
---
6+
7+
# Manylinux_2_35 and Manylinux_2_39
8+
9+
The packages distributed in this registry are a mix of manylinux_2_35 and
10+
manylinux_2_39 wheels. Support for manylinux wheels for riscv64 was added to
11+
pip in version 24.1 so you must have pip 24.1 or greater installed locally in
12+
order to install the packages. This is why we recommend upgrading pip above
13+
before installing anything. Prior to the release of pip 24.1, some wheels with
14+
the linux tag were created for a select set of packages and uploaded to this
15+
package registry. If your version of pip is older than 24.1 pip will install
16+
these older wheels instead of the manylinux wheels, if they are available.
17+
This is probably not what you want so do upgrade pip.
18+
19+
These older packages in this registry with the 'linux' platform tag, e.g.,
20+
`numpy-1.26.4-cp39-cp39-linux_riscv64.whl`, actually behave like manylinux_2_35
21+
wheels. These wheels were generated because we didn't want to wait for the
22+
release of pip 24.1 to begin distributing riscv64 wheels, so while we were
23+
waiting, we used a modified auditwheel that generates wheels with the linux
24+
platform tag that mostly behave like manylinux_2_35 wheels. This means that
25+
the wheels will work on any Linux distribution with glibc 2.35 or greater. The
26+
wheels also vendor all of their dependencies that are not on the
27+
manylinux_2_35 whitelist, e.g., OpenBLAS and libgfortran. One downside of
28+
misusing the platform tag in this way is that pip will not warn you when you
29+
install the wheels on distributions that use a glibc older than 2.35. In this
30+
case the wheels will install but will be unlikely to work. As most riscv64
31+
users are expected to use recent distributions to benefit from the latest
32+
riscv64 support from the kernel and toolchains, this hopefully won't be too
33+
much of an issue.
34+
35+
The manylinux_2_39 wheels are built with the upstream manylinux_2_39_riscv64
36+
image. There are a few exceptions that were built with a custom
37+
manylinux_2_39_riscv64 based on RockyLinux 10 which we used for a short period
38+
of time before the official manylinux_2_39_riscv64 images were published.
39+
40+
All earlier wheels are built using a custom manylinux_2_35 based on Ubuntu
41+
22.04. See the local
42+
[riseproject/python/manylinux](https://gitlab.com/riseproject/python/manylinux)
43+
fork for more details.

‎docs/motivation.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: Motivation
3+
layout: default
4+
nav_order: 2
5+
---
6+
7+
# Motivation
8+
9+
Python is commonly used in the fields of scientific computing, data analysis and
10+
machine learning. However, the Python packages used in these disciplines aren't
11+
wholly written in Python - they also contain a lot of code written in C/C++ or
12+
other languages which needs to be built as part of the module. Such projects
13+
typically create binary wheels for each of their releases and upload these
14+
wheels to pypi, the Python Package Index. This allows users to easily and
15+
quickly install tested, prebuilt versions of their favourite projects using the
16+
pip (or [uv](https://docs.astral.sh/uv/)) tool.
17+
18+
Until recently, Python packaging infrastructure like
19+
[auditwheel](https://github.com/pypa/auditwheel),
20+
[cibuildwheel](https://github.com/pypa/cibuildwheel), and
21+
[manylinux](https://github.com/pypa/manylinux) did not support riscv64, and no
22+
native runners for GitHub Actions were available. This made supporting the
23+
architecture difficult for open-source projects without complicated build
24+
processes and emulated systems. However, the aforementioned infrastructure now
25+
supports riscv64, and with the RISE [RISC-V
26+
Runners](https://riscv-runners.riseproject.dev/) project, maintainers have the
27+
option of building binary wheels on native riscv64 platforms. The RISE Python
28+
Wheels project's goal is to accelerate this adoption and ensure that the riscv64
29+
architecture is fully-supported for data science and machine learning
30+
applications.

0 commit comments

Comments
 (0)