Skip to main content

Contributing

Issues and pull requests are welcome on GitHub.

Development rules​

  • Test-driven development. Write a failing test in Tests/MatftTests/ first (the expected values should follow Numpy's outputs as much as possible), make it pass with a minimal implementation, then refactor with all tests passing.
  • Naming. Function names, arguments and behaviors follow Numpy (e.g. np.expand_dims → Matft.expand_dims).
swift test                               # all tests
swift test --filter MatftTests.MathTest  # a specific test class

Build scripts​

iOS/macOS build & test​

./scripts/build-and-test-ios.sh

This script builds the project using swift build and runs all tests using swift test.

WebAssembly build & test​

./scripts/build-and-test-wasm.sh

This script will:

  • Check and install the required Swift development toolchain (DEVELOPMENT-SNAPSHOT-2025-11-03-a, ~1.8GB) into ~/Library/Developer/Toolchains on macOS if needed (no sudo required)
  • Check and install the matching Swift WASM SDK (wasm32-unknown-wasip1-threads) if needed
  • Check and install the wasmtime runtime if needed
  • Build the project for WebAssembly
  • Build and run tests using wasmtime

The WASM script automatically handles toolchain, SDK and runtime installation, so you can run it on a fresh machine without any prior setup.

MatftMLX build & test​

To build and test MatftMLX (Apple silicon and Xcode with the Metal Toolchain are required, swift test cannot build MLX's Metal shaders):

xcodebuild -downloadComponent MetalToolchain  # only once
./scripts/build-and-test-mlx.sh
./scripts/run-mlx-demo.sh                      # demos: Matft preprocessing -> MLX

Requirements​

  • iOS/macOS: Swift 6.1 or later
  • WebAssembly: Swift DEVELOPMENT-SNAPSHOT-2025-11-03-a toolchain (toolchain, SDK and wasmtime will be automatically installed)

Benchmarks​

See Performance. The tables are generated by scripts/benchmark.py on a local Mac.

Documentation​

This site is built with Docusaurus from website/, and the API reference with Swift-DocC from the documentation comments in Sources/Matft.

./scripts/build-docs.sh            # API reference -> website/static/api
./scripts/build-docs.sh --preview  # or preview only the API reference

cd website
npm ci
npm run build && npm run serve     # http://localhost:3000/Matft/

Document every public symbol with a summary line, - Parameters:, - Returns: and, where one exists, the Numpy counterpart (e.g. "Equivalent to numpy.transpose."). DOCC_WARNINGS_AS_ERRORS=1 ./scripts/build-docs.sh fails on documentation warnings such as undocumented or misspelled parameters.

Contact​

Feel free to ask about this project or anything via junnosuke.kado.git@gmail.com.