Skip to content

README_DEVELOPERS.md

Latest commit

 

History

History
117 lines (81 loc) · 2.98 KB

README_DEVELOPERS.md

File metadata and controls

117 lines (81 loc) · 2.98 KB

Requirements for developers

We are using Ruff as code formatter and as a linter. It is automatically enforced if you activate these as plugins for pre-commit. You can activate the pre-commit actions by following the instructions. As the config files are already there, this essentially boils down to:

  python -m pip install pre-commit
  pre-commit install

You are done!

Building from sources

python-blosc2 includes the C-Blosc2 source code and can be built in place:

    git clone https://github.com/Blosc/python-blosc2/
    cd python-blosc2
    pip install .   # add -e for editable mode

On Windows, clang-cl is required (OpenZL depends on C11 support). Make sure LLVM is on PATH and build with Ninja, for example:

CMAKE_GENERATOR=Ninja \
CC=clang-cl \
CXX=clang-cl \
pip install -e .

There are situations where you may want to build the C-Blosc2 library separately, for example, when debugging issues in the C library. In that case, let's assume you have the C-Blosc2 library installed in /usr/local:

CMAKE_PREFIX_PATH=/usr/local USE_SYSTEM_BLOSC2=1 pip install -e .

and then, you can run the tests with:

LD_LIBRARY_PATH=/usr/local/lib pytest

[replace LD_LIBRARY_PATH with the appropriate environment variable for your system, such as DYLD_LIBRARY_PATH on macOS or PATH on Windows, if necessary].

That's it! You can now proceed to the testing section.

Speeding up local builds (sccache + Ninja)

If you do frequent local rebuilds, sccache can significantly speed up C/C++ rebuilds.

brew install sccache ninja

Then run:

CMAKE_C_COMPILER_LAUNCHER=sccache \
SKBUILD_BUILD_DIR=build \
pip install -e . --no-build-isolation

Using SKBUILD_BUILD_DIR keeps a stable build directory between runs, which improves incremental rebuilds and sccache hit rates.

Check cache stats with:

sccache --show-stats

Testing

We are using pytest for testing. You can run the tests by executing

  pytest

If you want to run a heavyweight version of the tests, you can use the following command:

  pytest -m "heavy"

If you want to run the network tests, you can use the following command:

  pytest -m "network"

Documentation

We are using Sphinx for documentation. You can build the documentation by executing:

  cd doc
  rm -rf ../html _build
  python -m sphinx . ../html

[You may need to install the pandoc package first: https://pandoc.org/installing.html]

You will find the documentation in the ../html directory.

Array API tests compatibility

You can test array API compatibility with the array-api-tests module. Use the tests/array-api-xfails.txt to skip the tests that are not supported and run pytest from the array-api-tests source dir like this:

ARRAY_API_TESTS_MODULE=blosc2 pytest array_api_tests --xfails-file ${BLOSC2_DIR}/tests/array-api-xfails.txt -xs