diff --git a/Changelog.md b/Changelog.md --- a/Changelog.md +++ b/Changelog.md @@ -1,3 +1,7 @@ +### 0.3.2.0 + +- Added docs on building with dependencies installed by *cabal v2-build*. + ### 0.3.1.0 - Use option *-flink-rts* only with GHC supporting this (GHC *8.10.6* and diff --git a/NgxExport/Distribution.hs b/NgxExport/Distribution.hs --- a/NgxExport/Distribution.hs +++ b/NgxExport/Distribution.hs @@ -20,6 +20,8 @@ module NgxExport.Distribution ( -- * Usage and examples -- $usage + + -- * Exported functions buildSharedLib ,patchAndCollectDependentLibs ,ngxExportHooks @@ -87,8 +89,16 @@ -- , 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 for building them with +-- /cabal v2-build/ inside GHC /package environments/. +-- -- ==== File /Setup.hs/ -- @ -- import __/NgxExport.Distribution/__ @@ -104,9 +114,16 @@ -- /rpath/ by utility /hslibdeps/) and explicit ghc option /-o/ at the build -- step which is as well used by /hslibdeps/ as the name of the target library. -- +-- ==== Building with cabal v1-commands +-- -- Let's build the example with commands /cabal v1-configure/ and --- /cabal v1-build/ (the /v2-/commands should probably work as well). +-- /cabal v1-build/. -- +-- > $ cabal v1-install --only-dependencies +-- > Resolving dependencies... +-- > All the requested packages are already installed: +-- > Use --reinstall if you want to reinstall anyway. +-- -- > $ cabal v1-configure --prefix=/var/lib/nginx -- > Resolving dependencies... -- > [1 of 1] Compiling Main ( dist/setup/setup.hs, dist/setup/Main.o ) @@ -157,22 +174,58 @@ -- shared library and the directory with dependent libraries: it is ready for -- installation in directory /\/var\/lib\/nginx/ at the target system. -- +-- ==== Building with Setup.hs commands +-- -- For building custom artifacts, options of /hslibdeps/ must be accessed --- directly. For this, command /runhaskell Setup.hs build/ can be used instead --- of /cabal v1-build/. Let's change the names of the directory with dependent --- libraries and the tar-file to /deps\// and /deps.tar.gz/ respectively, and --- also define the /rpath/ directory without using option /--prefix/. +-- directly. For this, commands /runhaskell Setup.hs configure \/ build/ can be +-- used instead of /cabal v1-configure \/ v1-build/. Let's change the names of +-- the directory with dependent libraries and the tar-file to /deps\// and +-- /deps.tar.gz/ respectively, and also define the /rpath/ directory without +-- using option /--prefix/. -- --- > $ cabal v1-configure +-- > $ runhaskell Setup.hs configure --user -- -- > $ runhaskell Setup.hs build --ghc-options="ngx_distribution_test.hs -o ngx_distribution_test.so -lHSrts_thr-ghc$(ghc --numeric-version)" --hslibdeps-options="-t/var/lib/nginx/deps -ddeps -adeps" -- --- With the building approaches shown above, the following list of drawbacks +-- ==== Building dependencies with cabal v2-build +-- +-- Nowadays, Cabal recommends building packages using /Nix-style local builds/. +-- This means that dependent packages do not get installed in places known to +-- GHC. However, they can be built inside GHC /package environments/. Let's +-- build dependencies and put them in a package environment in the current +-- working directory. +-- +-- > $ cabal v2-install --lib --only-dependencies --package-env . +-- +-- > $ cabal v2-install --lib ngx-export-distribution --package-env . +-- +-- > $ sed -i 's/\(^package-id \)/--\1/' .ghc.environment.x86_64-linux-8.10.5 +-- +-- This /sed/ command comments out all lines that start with word /package-id/ +-- in file /.ghc.environment.x86_64-linux-8.10.5/ which has been created by the +-- former commands. This prevents the target library from linking against +-- libraries listed in those lines thus making the overall number and the size +-- of dependent libraries as small as possible. If this command breaks the +-- following steps, some of the commented lines can be selectively uncommented. +-- +-- > $ runhaskell --ghc-arg=-package=base --ghc-arg=-package=ngx-export-distribution Setup.hs configure --package-db=clear --package-db=global --package-db="$HOME/.cabal/store/ghc-$(ghc --numeric-version)/package.db" --prefix=/var/lib/nginx +-- +-- Directory /$HOME\/.cabal\/store\/ghc-$(ghc --numeric-version)\/package.db/ +-- contains a GHC /package db/ with all packages built by /cabal v2-build/, it +-- gets also listed in file /.ghc.environment.x86_64-linux-8.10.5/. +-- +-- > $ 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 -lHSrts_thr-ghc$(ghc --numeric-version)" +-- +-- This should build library /ngx_distribution_test.so/ and link it against +-- Haskell libraries found in the global package db and +-- /$HOME\/.cabal\/store\/ghc-$(ghc --numeric-version)\/package.db/. +-- +-- With all building approaches shown above, the following list of drawbacks -- must be taken into account. -- -- - Utility /hslibdeps/ collects only libraries prefixed with /libHS/, --- - command /cabal v1-clean/ only deletes directory /dist/, it does not delete --- build artifacts in the current working directory, +-- - clean commands such as /cabal v1-clean/ do not delete build artifacts in +-- the current working directory, -- - behavior of Cabal commands other than /configure/, /build/ and /clean/ is -- not well defined. diff --git a/ngx-export-distribution.cabal b/ngx-export-distribution.cabal --- a/ngx-export-distribution.cabal +++ b/ngx-export-distribution.cabal @@ -1,5 +1,5 @@ name: ngx-export-distribution -version: 0.3.1.0 +version: 0.3.2.0 synopsis: Build custom libraries for Nginx haskell module description: Build custom libraries for .