CONTRIBUTING.md

Contributing

• Contributing
  • Setup
    • Using a dev container environment
    • Bring your own toolbox
  • Build
  • Test
  • Doc
  • Misc

Setup

Using a dev container environment

OpenDAL provides a pre-configured dev container that could be used in GitHub Codespaces, VSCode, JetBrains, JuptyerLab. Please pick up your favourite runtime environment.

The fastest way is:

Bring your own toolbox

The haskell binding requires haskell and cabal to be built. We recommend using the latest stable version for development.

If you are new to haskell, we recommend using GHCup to install haskell and cabal.

For Unix-like systems:

curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh

For Windows:

Set-ExecutionPolicy Bypass -Scope Process -Force;[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; try { Invoke-Command -ScriptBlock ([ScriptBlock]::Create((Invoke-WebRequest https://www.haskell.org/ghcup/sh/bootstrap-haskell.ps1 -UseBasicParsing))) -ArgumentList $true } catch { Write-Error $_ }

To verify that everything is working properly, run ghc -V and cabal -V:

> ghc -V
The Glorious Glasgow Haskell Compilation System, version 9.6.1
> cabal -V
cabal-install version 3.10.1.0
compiled using version 3.10.1.0 of the Cabal library

Build

cargo build
LIBRARY_PATH=../../target/debug cabal build

To clean up the build:

cargo clean
cabal clean

Test

We use tasty as the test framework. To run the tests:

LD_LIBRARY_PATH=../../target/debug cabal test

...(Build Info)
Test suite opendal-test: RUNNING...
Test suite opendal-test: PASS
Test suite logged to: 
...(Log Path)
1 of 1 test suites (1 of 1 test cases) passed.

Doc

To generate the documentation:

cabal haddock

If your cabal version is greater than 3.8, you can use cabal haddock --open to open the documentation in your browser. Otherwise, you can visit the documentation from dist-newstyle/build/$ARCH/ghc-$VERSION/opendal-$VERSION/doc/html/opendal/index.html.

Misc

If you don't want to specify LIBRARY_PATH and LD_LIBRARY_PATH every time, you can use direnv to set the environment variable automatically. Add the following to your .envrc:

export LIBRARY_PATH=../../target/debug:$LIBRARY_PATH
export LD_LIBRARY_PATH=../../target/debug:$LD_LIBRARY_PATH

If you are using Haskell in VSCode, you may need to add the following configuration to your settings.json:

"haskell.serverEnvironment": {
    "LIBRARY_PATH": "../../target/debug:$LIBRARY_PATH"
},