From 841ab4426963caac73bf0f4d87b2740eb7888deb Mon Sep 17 00:00:00 2001 From: Aditya Manthramurthy Date: Tue, 4 Oct 2022 10:57:19 -0700 Subject: [PATCH] Add `dev` flag to cabal file and update README This turns on the GHC option `-Werror` to ensure that warnings fail the build in dev mode. The flag is enabled in the CI. README is updated with cabal based instructions. --- .github/workflows/ci.yml | 16 ++++---- README.md | 79 +++++++++++++++++++++++++--------------- minio-hs.cabal | 29 ++++++++++----- 3 files changed, 78 insertions(+), 46 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c0e2bf3..0d7e171 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -80,7 +80,7 @@ jobs: - name: Configure run: | - cabal configure --enable-tests --enable-benchmarks --test-show-details=direct -fexamples -flive-test + cabal configure --enable-tests --enable-benchmarks --test-show-details=direct -fexamples -fdev -flive-test - name: Freeze run: | @@ -98,11 +98,11 @@ jobs: - name: Install dependencies run: | - cabal build all --only-dependencies -fexamples -flive-test + cabal build --only-dependencies - name: Build run: | - cabal build all -fexamples + cabal build - name: Setup MinIO for testing (Linux) if: matrix.os == 'ubuntu-latest' @@ -135,7 +135,7 @@ jobs: /tmp/minio/minio server --quiet --certs-dir /tmp/minio-config/certs data1 data2 data3 data4 2>&1 > minio.log & ghc --version cabal --version - cabal test all -flive-test + cabal test - name: Test (Windows) if: matrix.os == 'windows-latest' @@ -143,7 +143,7 @@ jobs: Start-Process -NoNewWindow -FilePath "$HOME/minio.exe" -ArgumentList "--certs-dir", "$env:temp/minio-config/certs", "server", "$env:temp/data1", "$env:temp/data2", "$env:temp/data3", "$env:temp/data4" ghc --version cabal --version - cabal test all -flive-test + cabal test stack: name: stack / ghc ${{ matrix.ghc }} @@ -188,7 +188,7 @@ jobs: - name: Build run: | - stack build --system-ghc --test --bench --no-run-tests --no-run-benchmarks --flag minio-hs:examples + stack build --system-ghc --test --bench --no-run-tests --no-run-benchmarks --flag minio-hs:examples --flag minio-hs:live-test --flag minio-hs:dev - name: Setup MinIO for testing (Linux) if: matrix.os == 'ubuntu-latest' @@ -221,7 +221,7 @@ jobs: /tmp/minio/minio server --quiet --certs-dir /tmp/minio-config/certs data1 data2 data3 data4 2>&1 > minio.log & ghc --version stack --version - stack test --system-ghc --flag minio-hs:live-test + stack test --system-ghc --flag minio-hs:live-test --flag minio-hs:dev - name: Test (Windows) if: matrix.os == 'windows-latest' @@ -229,4 +229,4 @@ jobs: Start-Process -NoNewWindow -FilePath "$HOME/minio.exe" -ArgumentList "--certs-dir", "$env:temp/minio-config/certs", "server", "$env:temp/data1", "$env:temp/data2", "$env:temp/data3", "$env:temp/data4" ghc --version cabal --version - stack test --system-ghc --flag minio-hs:live-test + stack test --system-ghc --flag minio-hs:live-test --flag minio-hs:dev diff --git a/README.md b/README.md index a2115f1..a6703c8 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,8 @@ -# MinIO Client SDK for Haskell [![Build Status](https://travis-ci.org/minio/minio-hs.svg?branch=master)](https://travis-ci.org/minio/minio-hs)[![Hackage](https://img.shields.io/hackage/v/minio-hs.svg)](https://hackage.haskell.org/package/minio-hs)[![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) +# MinIO Haskell Client SDK for Amazon S3 Compatible Cloud Storage [![Build Status](https://travis-ci.org/minio/minio-hs.svg?branch=master)](https://travis-ci.org/minio/minio-hs)[![Hackage](https://img.shields.io/hackage/v/minio-hs.svg)](https://hackage.haskell.org/package/minio-hs)[![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) -The MinIO Haskell Client SDK provides simple APIs to access [MinIO](https://min.io) and Amazon S3 compatible object storage server. +The MinIO Haskell Client SDK provides simple APIs to access [MinIO](https://min.io) and any Amazon S3 compatible object storage. -## Minimum Requirements - -- The Haskell [stack](https://docs.haskellstack.org/en/stable/README/) +This guide assumes that you have a working [Haskell development environment](https://www.haskell.org/downloads/). ## Installation @@ -12,20 +10,35 @@ The MinIO Haskell Client SDK provides simple APIs to access [MinIO](https://min. Simply add `minio-hs` to your project's `.cabal` dependencies section or if you are using hpack, to your `package.yaml` file as usual. -### Try it out directly with `ghci` +### Try it out in a [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) + +#### For a cabal based environment + +Download the library source and change to the extracted directory: + +``` sh +$ cabal get minio-hs +$ cd minio-hs-1.6.0/ # directory name could be different +``` + +Then load the `ghci` REPL environment with the library and browse the available APIs: + +``` sh +$ cabal repl +ghci> :browse Network.Minio +``` + +#### For a stack based environment From your home folder or any non-haskell project directory, just run: ```sh - stack install minio-hs - ``` Then start an interpreter session and browse the available APIs with: ```sh - $ stack ghci > :browse Network.Minio ``` @@ -134,44 +147,52 @@ main = do ### Development -To setup: +#### Download the source ```sh -git clone https://github.com/minio/minio-hs.git - -cd minio-hs/ +$ git clone https://github.com/minio/minio-hs.git +$ cd minio-hs/ +``` -stack install -``` +#### Build the package: -Tests can be run with: +With `cabal`: ```sh +$ # Configure cabal for development enabling all optional flags defined by the package. +$ cabal configure --enable-tests --test-show-details=direct -fexamples -fdev -flive-test +$ cabal build +``` -stack test +With `stack`: +``` sh +$ stack build --test --no-run-tests --flag minio-hs:live-test --flag minio-hs:dev --flag minio-hs:examples ``` +#### Running tests: -A section of the tests use the remote MinIO Play server at `https://play.min.io` by default. For library development, using this remote server maybe slow. To run the tests against a locally running MinIO live server at `http://localhost:9000`, just set the environment `MINIO_LOCAL` to any value (and unset it to switch back to Play). +A section of the tests use the remote MinIO Play server at `https://play.min.io` by default. For library development, using this remote server maybe slow. To run the tests against a locally running MinIO live server at `http://localhost:9000` with the credentials `access_key=minio` and `secret_key=minio123`, just set the environment `MINIO_LOCAL` to any value (and unset it to switch back to Play). -To run the live server tests, set a build flag as shown below: +With `cabal`: ```sh +$ export MINIO_LOCAL=1 # to run live tests against local MinIO server +$ cabal test +``` -stack test --flag minio-hs:live-test - -# OR against a local MinIO server with: - -MINIO_LOCAL=1 stack test --flag minio-hs:live-test +With `stack`: +``` sh +$ export MINIO_LOCAL=1 # to run live tests against local MinIO server +stack test --flag minio-hs:live-test --flag minio-hs:dev ``` -The configured CI system always runs both test-suites for every change. +This will run all the test suites. -Documentation can be locally built with: +#### Building documentation: ```sh - -stack haddock - +$ cabal haddock +$ # OR +$ stack haddock ``` diff --git a/minio-hs.cabal b/minio-hs.cabal index 1ac3120..45772cf 100644 --- a/minio-hs.cabal +++ b/minio-hs.cabal @@ -14,21 +14,28 @@ maintainer: dev@min.io category: Network, AWS, Object Storage build-type: Simple stability: Experimental -extra-source-files: +extra-doc-files: CHANGELOG.md CONTRIBUTING.md docs/API.md - examples/*.hs README.md +extra-source-files: + examples/*.hs stack.yaml -tested-with: GHC == 8.8.4 +tested-with: GHC == 8.6.5 + , GHC == 8.8.4 , GHC == 8.10.7 , GHC == 9.0.2 + , GHC == 9.2.4 source-repository head type: git location: https://github.com/minio/minio-hs.git +Flag dev + Description: Build package in development mode + Default: False + Manual: True common base-settings ghc-options: -Wall @@ -41,16 +48,20 @@ common base-settings ghc-options: -Wredundant-constraints if impl(ghc >= 8.2) ghc-options: -fhide-source-paths - - -- Add this when we have time. Fixing partial-fields requires major version - -- bump at this time. if impl(ghc >= 8.4) ghc-options: -Wpartial-fields -- -Wmissing-export-lists - if impl(ghc >= 8.8) ghc-options: -Wmissing-deriving-strategies -Werror=missing-deriving-strategies + -- if impl(ghc >= 8.10) + -- ghc-options: -Wunused-packages -- disabled due to bug related to mixin config + if impl(ghc >= 9.0) + ghc-options: -Winvalid-haddock + if impl(ghc >= 9.2) + ghc-options: -Wredundant-bang-patterns + if flag(dev) + ghc-options: -Werror default-language: Haskell2010 @@ -105,7 +116,6 @@ common base-settings , cryptonite-conduit >= 0.2 , digest >= 0.0.1 , directory - , exceptions , filepath >= 1.4 , http-client >= 0.5 , http-client-tls @@ -114,7 +124,6 @@ common base-settings , ini , memory >= 0.14 , network-uri - , raw-strings-qq >= 1 , resourcet >= 1.2 , retry , text >= 1.2 @@ -153,6 +162,7 @@ test-suite minio-hs-live-server-test , Network.Minio.XmlGenerator.Test , Network.Minio.XmlParser.Test build-depends: minio-hs + , raw-strings-qq , tasty , tasty-hunit , tasty-quickcheck @@ -167,6 +177,7 @@ test-suite minio-hs-test hs-source-dirs: test, src main-is: Spec.hs build-depends: minio-hs + , raw-strings-qq , QuickCheck , tasty , tasty-hunit