Debian Codegraph @

c_impl/README.md

raw
1 # Python bindings for the BLAKE3 C implementation
2
3 This directory contains a reimplementation of the Python
4 [`blake3`](https://pypi.org/project/blake3) module, based on the official C
5 implementation of BLAKE3 rather than the official Rust implementation. This is
6 mainly intended as a proof-of-concept for code that might be submitted to
7 Python's hashlib in the future, and this module probably won't be published to
8 PyPI. Most applications should prefer the Rust-based bindings.
9
10 The C implementation of BLAKE3 doesn't currently support multithreading, but
11 the `max_threads` parameter is still allowed (and ignored) in these bindings
12 for compatibility with the Rust version. This point of compatibility is
13 actually why the parameter was named `max_threads` in the first place. Credit
14 to Larry Hastings for that idea.
15
16 ## Building
17
18 The build is defined in [`setup.py`](setup.py), and you can compile and install
19 this module with the usual commands like
20
21 ```
22 pip install .
23 ```
24
25 Python 3.8 or later is required.
26
27 The build implements the following decision tree, which is [documented in
28 greater detail
29 upstream](https://github.com/BLAKE3-team/BLAKE3/tree/master/c#building):
30
31 - Are we building on macOS?
32 - Combine the Unix assembly files and the NEON intrinsics implementation
33 into a "universal" binary using the `lipo` tool.
34 - Are we targetting x86-64?
35 - Are we targetting Windows?
36 - Include the MSVC assembly files.
37 - Otherwise:
38 - Include the Unix assembly files.
39 - Are we targetting 32-bit x86?
40 - Build and include the x86 intrinsics files. These are OS-independent, but
41 each one needs to be compiled with different flags (`-msse4.1`, `-mavx2`,
42 etc.) to enable the appropriate instruction set extensions.
43 - Are we targetting AArch64?
44 - Build and include the NEON intrinsics implementation. There are ARMv7
45 targets that support NEON, but there are also ARMv7 targets that don't,
46 and there's no standard way to distinguish them. So we play it safe and
47 only enable NEON on AArch64.
48 - Otherwise:
49 - Just build the portable implementation.
50
51 The x86-64-only assembly implementations perform better than intrinsics, and
52 they also build faster, so these are preferable where possible. They come in
53 three target-specific flavors: Unix, Windows MSVC, and Windows GNU. Currently
54 `setup.py` doesn't try to target the Windows GNU ABI, but this should be
55 relatively easy to add if needed.
56
57 Nothing here takes cross-compilation into account yet. Can Python extensions be
58 cross-compiled? Do we care about this?
59
60 **Feedback needed:** I'm very new to both `setuptools` and the Python C API,
61 and there's a good chance I've made mistakes or accidentally relied on
62 deprecated features. This code needs to be reviewed by someone with more
63 experience. The part that sets compiler flags for intrinsics files and the part
64 that builds `.asm` files on Windows are especially rocky.