BLAKE3

The blake3_c_rust_bindings package provides Rust bindings for the C implementation of BLAKE3.

Warning: These bindings are not intended for production use. Because a native Rust implementation of BLAKE3 is available in this repository, you should use the native Rust crate for production workloads. Use these C bindings exclusively for testing and benchmarking purposes.

The recommended way to build the library is using CMake (minimum version 3.9).

Modern CMake usage:

cmake -S c -B c/build "-DCMAKE_INSTALL_PREFIX=/usr/local"
cmake --build c/build --target install

Available CMake Options:

• BLAKE3_USE_TBB: Enable oneTBB parallelism (requires C++20 capable compiler).
• BLAKE3_FETCH_TBB: Allow fetching oneTBB from GitHub if not found on the system.
• BLAKE3_EXAMPLES: Compile and install example programs.

cmake -S c -B c/build "-DCMAKE_INSTALL_PREFIX=/usr/local" -DBLAKE3_USE_TBB=1 -DBLAKE3_FETCH_TBB=1

To view the rendered documentation for the reference implementation, run the following command from the reference_impl directory:

cargo doc --open

NEON is enabled by default on AArch64, but for other ARM targets, you must explicitly enable it using the BLAKE3_USE_NEON=1 macro.

Troubleshooting ARMv7: If you encounter inlining errors (e.g., target specific option mismatch), you may need to add compiler flags such as -mfpu=neon-vfpv4 -mfloat-abi=hard to activate NEON support.

gcc -shared -O3 -o libblake3.so -DBLAKE3_USE_NEON=1 blake3.c blake3_dispatch.c \
    blake3_portable.c blake3_neon.c

You can install b3sum using prebuilt binaries from the releases page for Linux, Windows, and macOS.

Alternatively, if you have Rust and Cargo installed, you can install it via Cargo:

cargo install b3sum

If you are working within the repository directory, you can install directly from the current path:

cargo install --path .

To build the binary without installing it to your cargo bin directory, use:

cargo build --release

This will place the binary in ./target/release/b3sum.

To omit all SIMD instruction sets and build only the portable C implementation, define the following macros during compilation:

• BLAKE3_NO_SSE2
• BLAKE3_NO_SSE41
• BLAKE3_NO_AVX2
• BLAKE3_NO_AVX512

gcc -shared -O3 -o libblake3.so -DBLAKE3_NO_SSE2 -DBLAKE3_NO_SSE41 -DBLAKE3_NO_AVX2 \
    -DBLAKE3_NO_AVX512 blake3.c blake3_dispatch.c blake3_portable.c

To build a shared library on x86_64 Linux using the preferred assembly implementations (which offer better performance and consistency), link the core files with the specific assembly files for each instruction set.

gcc -shared -O3 -o libblake3.so blake3.c blake3_dispatch.c blake3_portable.c \
    blake3_sse2_x86-64_unix.S blake3_sse41_x86-64_unix.S blake3_avx2_x86-64_unix.S \
    blake3_avx512_x86-64_unix.S

If you are on x86_64 with a Unix-like OS, you can compile the example.c program manually by linking the necessary implementation files and assembly optimizations.

gcc -O3 -o example example.c blake3.c blake3_dispatch.c blake3_portable.c \
    blake3_sse2_x86-64_unix.S blake3_sse41_x86-64_unix.S blake3_avx2_x86-64_unix.S \
    blake3_avx512_x86-64_unix.S

The b3sum --check command acts as a drop-in replacement for md5sum --check. It consumes a checkfile (the output of a regular b3sum command), re-hashes the files listed, and returns success (exit status 0) if all hashes match. If files are missing or contents have changed, it returns a non-zero exit status and prints the failure details.

Security Warning: b3sum --check only verifies the specific filepaths listed in the checkfile. It cannot detect if a directory has changed (e.g., if new files were added to a directory). Therefore, it should not be used as a comprehensive security tool for directory integrity.

To enable multithreading for large-file performance, you must compile the blake3_tbb.cpp file using the BLAKE3_USE_TBB macro.

Requirements:

• You must use -fno-exceptions when compiling blake3_tbb.cpp.
• Link against libtbb and libstdc++.
• Using -fno-rtti is recommended to reduce code size.

g++ -c -O3 -fno-exceptions -fno-rtti -DBLAKE3_USE_TBB -o blake3_tbb.o blake3_tbb.cpp
gcc -O3 -o example_tbb -lstdc++ -ltbb -DBLAKE3_USE_TBB blake3_tbb.o example_tbb.c blake3.c \
    blake3_dispatch.c blake3_portable.c blake3_sse2_x86-64_unix.S blake3_sse41_x86-64_unix.S \
    blake3_avx2_x86-64_unix.S blake3_avx512_x86-64_unix.S

If you prefer using C intrinsics instead of assembly, you must compile each instruction set implementation separately with the corresponding compiler flags before linking them together.

Compiler Flags for MSVC:

• AVX2: /arch:AVX2
• AVX-512: /arch:AVX512
• SSE2 and SSE4.1: Enabled by default (no specific flag required).

Compiler Flags for GCC/Clang:

• SSE2: -msse2
• SSE4.1: -msse4.1
• AVX2: -mavx2
• AVX-512: -mavx512f -mavx512vl (both flags are required).

gcc -c -fPIC -O3 -msse2 blake3_sse2.c -o blake3_sse2.o
gcc -c -fPIC -O3 -msse4.1 blake3_sse41.c -o blake3_sse41.o
gcc -c -fPIC -O3 -mavx2 blake3_avx2.c -o blake3_avx2.o
gcc -c -fPIC -O3 -mavx512f -mavx512vl blake3_avx512.c -o blake3_avx512.o
gcc -shared -O3 -o libblake3.so blake3.c blake3_dispatch.c blake3_portable.c \
    blake3_avx2.o blake3_avx512.o blake3_sse41.o blake3_sse2.o