Skip to content

CLAUDE.md

Latest commit

 

History

History
47 lines (39 loc) · 3.15 KB

CLAUDE.md

File metadata and controls

47 lines (39 loc) · 3.15 KB

Vortex

Development Guidelines

  • project is a monorepo Rust workspace, java bindings in /java, python bindings in /vortex-python
  • run cargo build -p to build a specific crate
  • use cargo clippy --all-targets --all-features to make sure a project is free of lint issues. Please do this every time you reach a stopping point or think you've finished work.
  • run cargo +nightly fmt --all to format Rust source files. Please do this every time you reach a stopping point or think you've finished work.
  • you can try running cargo fix --lib --allow-dirty --allow-staged && cargo clippy --fix --lib --allow-dirty --allow-staged to automatically many fix minor errors.

Architecture

  • vortex-buffer defines zero-copy aligned Buffer<T> and BufferMut<T> that are guaranteed to be aligned to T (or whatever requested runtime alignment).
  • vortex-dtype contains the basic DType logical type enum that is the basis of the Vortex type system
  • vortex-array contains the basic Array trait, as well as several encodings which impl that trait for each encoding. It includes all of most of the Apache Arrow encodings.
  • More exotic compressed encodings live in the crates inside of /encodings/*
  • File IO is defined in vortex-file. It uses the concept of a LayoutReader defined in vortex-layout crate.
  • /vortex-python contains the python bindings. rst flavored docs for the project are in /docs

Code Style

  • Prefer impl AsRef<T> to &T for public interfaces where possible, e.g. impl AsRef<Path>
  • Avoid usage of unsafe where not necessary, use zero-cost safe abstractions wherever possible, or cheap non-zero-cost abstractions.
  • Every new public API definition must have a doc comment. Examples are nice to have but not strictly required.
  • Use vortex_err! to create a VortexError with a format string and vortex_bail! to do the same but immediately return it as a VortexResult<T> to the surrounding context.
  • When writing tests, strongly consider using rstest cases to parameterize repetitive test logic.
  • If you want to create a large number of tests to an existing file module called foo.rs, and if you think doing so would be too many to inline in a tests submodule within foo.rs, then first promote foo to a directory module. You can do this by running mkdir foo && mv foo.rs foo/mod.rs. Then, you can create a test file foo/tests.rs that you include in foo/mod.rs with the appropriate test config flag.
  • If you encounter clippy errors in tests that should only pertain to production code (e.g., prohibiting panic/unwrap, possible numerical truncation, etc.), then consider allowing those lints at the test module level.
  • Prefer naming test modules tests, not test.
  • Prefer module-scoped imports over function-scoped imports. Only use function-scoped imports in situations where it is either (a) required, or (b) would be exceptionally verbose otherwise. An example where function-scoped imports is good is when writing an exhaustive match statement with a branch that matches many cases.

Other

  • When summarizing your work, please produce summaries in valid Markdown that can be easily copied/pasted to Github.