Refactored package structure: use sublibraries

.github/workflows/cabal.project.local

@@ -6,20 +6,6 @@ package io-classes
   ghc-options: -Werror
   flags: +asserts
 
-package io-classes-mtl
-  ghc-options: -Werror
-
-package strict-mvar
-  ghc-options: -Werror
-
-package strict-stm
-  ghc-options: -Werror
-  flags: +asserts
-
 package io-sim
   ghc-options: -Werror
   flags: +asserts
-
-package si-timers
-  ghc-options: -Werror
-  flags: +asserts

.github/workflows/github-page.yaml

@@ -0,0 +1,74 @@
+name: "Haddock documentation"
+
+on:
+  schedule:
+    - cron:  '0 0 * * *'
+  workflow_dispatch:
+
+jobs:
+  haddocks:
+    name: "Haddocks"
+
+    runs-on: ${{ matrix.os }}
+
+    defaults:
+      run:
+        shell: bash
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ghc: ["9.10.1"]
+        os: [ubuntu-latest]
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+    - name: Checkout ouroboros-network repository
+      uses: actions/checkout@v3
+
+      # we need nix to later build the spec documents
+    - name: Install Nix
+      uses: cachix/install-nix-action@v20
+
+    - name: Install Haskell
+      uses: haskell/actions/setup@v2
+      id: setup-haskell
+      with:
+        ghc-version: ${{ matrix.ghc }}
+        # we need unpublished `cabal` version to support sublibraries
+        cabal-version: 'head'
+
+    - uses: actions/cache@v3
+      name: Cache cabal store
+      with:
+        path: ${{ steps.setup-haskell.outputs.cabal-store }}
+        key: cache-haddock-${{ runner.os }}-${{ matrix.ghc }}-v1-${{ hashFiles('cabal-cache.cabal') }}-${{ github.sha }}
+        restore-keys: cache-haddock-${{ runner.os }}-${{ matrix.ghc }}-v1-${{ hashFiles('cabal-cache.cabal') }}-
+
+    - name: Update Hackage index
+      run: cabal update
+
+    - name: Build plan
+      run: cabal build --dry-run --enable-tests all
+
+    - name: Build Haddock documentation 🔧
+      run: |
+        cabal haddock-project --hackage all
+
+    - name: Upload artifacts
+      uses: actions/upload-pages-artifact@v1
+      with:
+        path: ./haddocks
+
+    - name: Deploy 🚀
+      id: deployment
+      uses: actions/deploy-pages@v2
+
+

.github/workflows/haskell.yml

@@ -85,7 +85,8 @@ jobs:
 
     - name: Build dependencies
       run: |
-        cabal build --only-dependencies all
+        cabal build --only-dependencies io-classes
+        cabal build --only-dependencies io-sim
 
     - uses: actions/cache/save@v4
       name: "Save cabal store"
@@ -103,8 +104,8 @@ jobs:
     - name: io-sim [test]
       run: cabal run io-sim:test
 
-    - name: si-timers [test]
-      run: cabal run si-timers:test
+    - name: io-classes:si-timers [test]
+      run: cabal run io-classes:test-si-timers
 
-    - name: strict-mvar [test]
-      run: cabal run strict-mvar:test
+    - name: io-classes:strict-mvar [test]
+      run: cabal run io-classes:test-strict-mvar

README.md

@@ -18,23 +18,23 @@
 * tracing committed changes to `TVar`, `TMVar`s, etc.
 * labeling of threads, `TVar`'s, etc.
 
-[`io-classes`] provides an interface, which allows writing code that can be run
-in both real `IO` and [`IOSim`].  It is a drop-in replacement for `IO`, and
-supports interfaces commonly known from `base`, `exceptions`, `stm`, `async`,
-or `time` packages.
-
-One of the principles of `io-classes` was to stay as close to `IO` as possible,
-thus most of the `IO` instances are directly referring to `base` or `async`
-API.  However, we made some distinctions, which are reported below.
-
-[`io-classes`] supports a novel hierarchy for error-handling monads as well as
-more familiar `exception` style.  The new hierarchy provides `bracket` and
-`finally` functions in the `MonadThrow` class, while `catch` style operators
-are provided by a super-class `MonadCatch`.  Both `bracket` and `finally` are
-the most common functions used to write code with robust exception handling,
-exposing them through the more basic `MonadThrow` class informs the reader
-/ reviewer that no tricky error handling is done in that section of the code
-base.
+[`io-classes:io-classes`] provides an interface, which allows writing code that
+can be run in both real `IO` and [`IOSim`].  It is a drop-in replacement for
+`IO`, and supports interfaces commonly known from `base`, `exceptions`, `stm`,
+`async`, or `time` packages.
+
+One of the principles of `io-classes:io-classes` was to stay as close to `IO`
+as possible, thus most of the `IO` instances are directly referring to `base`
+or `async` API.  However, we made some distinctions, which are reported below.
+
+[`io-classes:io-classes`] supports a novel hierarchy for error-handling monads
+as well as more familiar `exception` style.  The new hierarchy provides
+`bracket` and `finally` functions in the `MonadThrow` class, while `catch`
+style operators are provided by a super-class `MonadCatch`.  Both `bracket` and
+`finally` are the most common functions used to write code with robust
+exception handling, exposing them through the more basic `MonadThrow` class
+informs the reader / reviewer that no tricky error handling is done in that
+section of the code base.
 
 [`IOSim`] exposes a detailed trace, which can be enhanced by labeling threads, or
 mutable variables, tracing `Dynamic` values (which can be recovered from the
@@ -58,16 +58,18 @@ a complex, highly concurrent, distributed system
 * [`io-sim`]: provides two simulator interpreters: [`IOSim`] and
   `IOSimPOR` - an enhanced [`IOSim`] version with schedule discovery
   capabilities.
-* [`io-classes`]: class bases interface, which allows to to abstract over the
+* [`io-classes:io-classes`]: class bases interface, which allows to to abstract over the
     monad
-* [`strict-stm`]: strict STM operations
-* [`si-timers`]: non-standard timers API
+* [`io-classes:strict-stm`]: strict STM operations
+* [`io-classes:si-timers`]: non-standard timers API
 
 ### Issues
 
 New issues should be reported in [this][io-sim-issues] repository.
 
-[`io-classes`]: https://hackage.haskell.org/package/io-classes
+[`io-classes:io-classes`]: https://hackage.haskell.org/package/io-classes
+[`io-classes:strict-stm`]:  https://hackage.haskell.org/package/io-classes
+[`io-classes:si-timers`]:  https://hackage.haskell.org/package/io-classes
 [`io-sim`]: https://hackage.haskell.org/package/io-sim
 
 [contra-tracer]: https://hackage.haskell.org/package/contra-tracer

cabal.project

@@ -3,9 +3,6 @@ index-state: hackage.haskell.org 2024-05-17T03:42:00Z
 packages: ./io-sim
           ./io-classes
           ./io-classes-mtl
-          ./strict-mvar
-          ./strict-stm
-          ./si-timers
 
 package io-sim
   flags: +asserts

io-classes-mtl/io-classes-mtl.cabal

@@ -44,8 +44,7 @@ library
                       array,
                       mtl,
 
-                      io-classes ^>=1.5,
-                      si-timers,
+                      io-classes:{io-classes,si-timers} ^>= 1.5
 
 
     hs-source-dirs:   src

io-classes/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Revsion history of io-classes
 
+### Next version
+
+### Breaking changes
+
+* `strict-stm`, `strict-mvar` and `si-timers` are now public sublibraries of `io-classes` package.
+
 ## 1.5.0.0
 
 ### Breaking changes
@@ -12,6 +18,19 @@
 
 * Add `writeTMVar` to `MonadSTM`.
 
+* `strict-stm`, `strict-mvar` and `si-timers` were moved to `io-classes` as
+  **public sublibraries**.  You can import then in `*.cabal` files with the
+  following syntax `io-classes:strict-stm` or `io-classes:{strict-stm,
+  si-timers}`.  See the _Multiple public libraries_ subsection of [_Internal
+  Libraries_][sublibs] section in the `cabal` documentation.
+
+  Note: some time in the future we will deprecate `Hackage` packages
+  `strict-stm`, `strict-mvar` and `si-timers`.  If one will want to use the
+  namespace for a non `io-classes` related packages please contact the
+  maintainer.
+
+[sublibs]: https://cabal.readthedocs.io/en/stable/cabal-package.html#sublibs
+
 ## 1.4.1.0
 
 ### Non-breaking changes

io-classes/README.md

@@ -10,17 +10,20 @@ constraints in mind:
   as timer API;
 * provide zero-cost abstractions.
 
-We provide also non-standard extensions of this API:
+We provide also non-standard extensions of this API in **sublibraries**:
 
-* [`strict-stm`]: strict `TVar`'s, and other mutable `STM` variables, with
+* [`io-classes:strict-stm`]: strict `TVar`'s, and other mutable `STM` variables, with
   support of the [`nothunks`] library;
-* [`si-timers`]: timers api:
+* [`io-classes:strict-mvar`]: strict `MVar`s
+* [`io-classes:si-timers`]: timers api:
     - 32-bit safe API using `DiffTime` measured in seconds (rather than time in
       microseconds represented as `Int` as in `base`)
     - cancellable timeouts.
+* [`io-classes-mtl`]: MTL instances.
 
-[`strict-stm`] and [`nothunks`] were successfully used in a large code base to
-eliminate space leaks and keep that property over long development cycles.
+[`io-classes:strict-stm`] and [`nothunks`] were successfully used in a large
+code base to eliminate space leaks and keep that property over long development
+cycles.
 
 ## Exception Class Hierarchy
 
@@ -61,15 +64,14 @@ delays & timers.
 ## Software Transactional Memory API
 
 We provide two interfaces to `stm` API: lazy, included in `io-classes`; and
-strict one provided by [`strict-stm`].
-
+strict one provided by [`io-classes:strict-stm`].
 
 ## Threads API
 
 We draw a line between `base` API and `async` API.  The former is provided by
 [MonadFork](https://hackage.haskell.org/package/io-classes/docs/Control-Monad-Class-MonadFork.html#t:MonadFork)
 the latter by
-[MonadAsync](https://hackage.haskell.org/package/io-classes/docs/Control-Monad-Class-MonadFork.html#t:MonadAsync).
+[MonadAsync](https://hackage.haskell.org/package/io-classes/docs/Control-Monad-Class-MonadAsync.html#t:MonadAsync).
 Both are shallow abstractions around APIs exposed by the `base` and `async`
 packages.
 
@@ -140,17 +142,21 @@ its limitations and so there might be some rough edges.  PRs are welcomed,
 [`base`]: https://hackage.haskell.org/package/base
 [`exceptions`]: https://hackage.haskell.org/package/exceptions
 [`io-sim`]: https://hackage.haskell.org/package/io-sim
-[`si-timers`]: https://hackage.haskell.org/package/si-timers
+[`io-classes-mtl`]: https://hackage.haskell.org/package/io-classes-mtl
 [`stm`]: https://hackage.haskell.org/package/stm
-[`strict-stm`]: https://hackage.haskell.org/package/strict-stm
-[`threadDelay`]: https://hackage.haskell.org/package/io-classes/docs/Control-Monad-Class-MonadTimer.html#v:threadDela
+[`threadDelay`]: https://hackage.haskell.org/package/io-classes/docs/Control-Monad-Class-MonadTimer.html#v:threadDelay
 [`time`]: https://hackage.haskell.org/package/time
 [contributing]: https://www.github.com/input-output-hk/io-sim/tree/master/CONTRIBUTING.md
 [`nothunks`]: https://hackage.haskell.org/package/nothunks
 [labelThread-base]: https://hackage.haskell.org/package/base-4.17.0.0/docs/GHC-Conc-Sync.html#v:labelThread
 [io-deadlock]: https://hackage.haskell.org/package/base-4.19.0.0/docs/Control-Exception.html#t:Deadlock
 
-[MonadEventlog]: https://hackage.haskell.org/package/io-sim-classes/docs/Control-Monad-Class-MonadEventlog.html#t:MonadEventlog
+<!-- these links need to be updated once haskell/hackage-server#1218 is done --!>
+[`io-classes:si-timers`]: https://hackage.haskell.org/package/io-classes
+[`io-classes:strict-stm`]: https://hackage.haskell.org/package/io-classes
+[`io-classes:strict-mvar`]: https://hackage.haskell.org/package/io-classes
+
+[MonadEventlog]: https://hackage.haskell.org/package/io-classes/docs/Control-Monad-Class-MonadEventlog.html#t:MonadEventlog
 [Debug.Trace]: https://hackage.haskell.org/package/base/docs/Debug-Trace.html
 [MonadST]: https://hackage.haskell.org/package/io-classes/docs/Control-Monad-Class-MonadST.html#t:MonadST
 [MonadSay]: https://hackage.haskell.org/package/io-classes/docs/Control-Monad-Class-MonadSay.html#t:MonadSay