diff --git a/Changelog.md b/Changelog.md --- a/Changelog.md +++ b/Changelog.md @@ -1,3 +1,7 @@ +### 0.3.2.4 + +- Improved docs. + ### 0.3.2.3 - Fixed docs on using *cabal-plan*. diff --git a/LICENSE b/LICENSE --- a/LICENSE +++ b/LICENSE @@ -1,7 +1,7 @@ The following license covers this documentation, and the source code, except where otherwise indicated. -Copyright 2021-2022, Alexey Radkov. All rights reserved. +Copyright 2021-2023, Alexey Radkov. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/NgxExport/Distribution.hs b/NgxExport/Distribution.hs --- a/NgxExport/Distribution.hs +++ b/NgxExport/Distribution.hs @@ -3,22 +3,22 @@ ----------------------------------------------------------------------------- -- | -- Module : NgxExport.Distribution --- Copyright : (c) Alexey Radkov 2021-2022 +-- Copyright : (c) Alexey Radkov 2021-2023 -- License : BSD-style -- -- Maintainer : alexey.radkov@gmail.com -- Stability : experimental -- Portability : portable -- --- Quick and dirty build of simple shared libraries and collecting --- dependencies. This was designed to build custom Haskell handlers for --- . +-- Quick and dirty approach to building regular shared libraries and collecting +-- dependencies. This module was designed to build custom Haskell handlers for +-- . -- ----------------------------------------------------------------------------- module NgxExport.Distribution ( - -- * Building simple shared libraries + -- * Building regular shared libraries -- $building-shared-libraries -- *** An example @@ -33,9 +33,6 @@ -- *** Building dependencies with cabal v2-build -- $deps-cabal-v2 - -- *** Collecting direct dependencies with cabal-plan - -- $cabal-plan - -- *** Drawbacks -- $drawbacks @@ -66,7 +63,8 @@ -- $building-shared-libraries -- --- This module allows for building simple shared libraries with Cabal. +-- This module allows for building regular shared libraries and collecting +-- Haskell libraries they depend on with Cabal. -- $example -- @@ -107,19 +105,8 @@ -- , aeson -- -- ghc-options: -Wall -O2 -no-keep-hi-files -no-keep-o-files --- /-package=base/ --- /-package=ngx-export/ --- /-package=bytestring/ --- /-package=aeson/ -- @ -- --- All packages listed in /build-depends/ get also wrapped inside options --- /-package/ in /ghc-options/: this is important when building them with --- /cabal v2-build/ and then using inside GHC /package environments/. However, --- this duplication can be avoided if there is a method to get the package list --- in the /ghc-options/ programmatically. One of such methods is based on --- collecting the direct dependencies with utility /cabal-plan/. --- -- ==== File /Setup.hs/ -- @ -- import __/NgxExport.Distribution/__ @@ -192,7 +179,7 @@ -- which is passed by the module internally, has first appeared in the said -- release, -- - clause /ghc-options/ in the Cabal file is a better place for such a generic --- option as /-threaded/. +-- option as /-threaded/, -- - if the base name of the source file (/__ngx_distribution_test__.hs/) had -- exactly matched the package name (/__ngx-distribution-test__/), then -- options /ngx_distribution_test.hs -o ngx_distribution_test.so/ could have @@ -248,24 +235,12 @@ -- /$HOME\/.cabal\/store\/ghc-$(ghc --numeric-version)\/package.db/ with all -- packages ever built by /cabal v2-build/. -- --- > $ runhaskell --ghc-arg=-package=base --ghc-arg=-package=ngx-export-distribution Setup.hs build --ghc-options="ngx_distribution_test.hs -o ngx_distribution_test.so -threaded" --- --- This should build library /ngx_distribution_test.so/ and link it against --- Haskell libraries found in the global package db and the Cabal's global --- package store. - --- $cabal-plan --- --- We listed build dependencies in both /build-depends/ and /ghc-options/ --- clauses in the Cabal file to let Cabal find dependencies built with --- /cabal v2-build/ at the /configure/ step and expose them to ghc at the --- /build/ step. This approach is tedious and error-prone. Fortunately, there is --- utility [cabal-plan](https://hackage.haskell.org/package/cabal-plan) which is --- aimed to figure out dependencies of built packages. Particularly, with --- /cabal-plan/ we can remove those /-package=.../ lines from the /ghc-options/ --- clause in the Cabal file and, instead, collect the direct dependencies --- programmatically and put them as /package-id/ records in the GHC environment --- file. +-- Before running the /configure/ command, we commented out all packages listed +-- in the GHC environment file. The build step requires linking the target +-- library against the direct dependencies and their dependencies in turn. With +-- [cabal-plan](https://hackage.haskell.org/package/cabal-plan), re-enabling +-- the direct dependencies in the GHC environment file can be done +-- automatically. -- -- The following bash script collects all direct dependencies reported by -- /cabal-plan/. @@ -292,7 +267,13 @@ -- > package-id ngx-export-1.7.5-17b83e3ac354cc52614227ba662f8c23a8ddd4e08f2a1a02b0d6b51b2dd849ea -- -- will appear at the end of file /.ghc.environment.x86_64-linux-9.4.1/. This --- shall expose the four dependent packages at the /build/ step. +-- shall expose the four dependent packages at the next step. +-- +-- > $ runhaskell --ghc-arg=-package=base --ghc-arg=-package=ngx-export-distribution Setup.hs build --ghc-options="ngx_distribution_test.hs -o ngx_distribution_test.so -threaded" +-- +-- This should build library /ngx_distribution_test.so/ and link it against +-- Haskell libraries found in the global package database and the Cabal's global +-- package store. -- $drawbacks -- diff --git a/ngx-export-distribution.cabal b/ngx-export-distribution.cabal --- a/ngx-export-distribution.cabal +++ b/ngx-export-distribution.cabal @@ -1,16 +1,16 @@ name: ngx-export-distribution -version: 0.3.2.3 +version: 0.3.2.4 synopsis: Build custom libraries for Nginx haskell module description: Build custom libraries for - . -homepage: http://github.com/lyokha/nginx-haskell-module + . +homepage: https://github.com/lyokha/nginx-haskell-module license: BSD3 license-file: LICENSE extra-source-files: Changelog.md author: Alexey Radkov maintainer: Alexey Radkov stability: experimental -copyright: 2021-2022 Alexey Radkov +copyright: 2021-2023 Alexey Radkov category: Network build-type: Simple cabal-version: 1.20