From 9450cf48e3ae1ea0c422803a7b5ede0c4db17839 Mon Sep 17 00:00:00 2001 From: Ellie Hermaszewska Date: Fri, 5 Nov 2021 20:03:51 +0800 Subject: [PATCH] Documentation changes to cope with haskell.lib.compose --- doc/frequently-asked-questions.rst | 25 ++++++++++++-------- doc/nixpkgs-users-guide.rst | 37 +++++++++++++++--------------- 2 files changed, 33 insertions(+), 29 deletions(-) diff --git a/doc/frequently-asked-questions.rst b/doc/frequently-asked-questions.rst index b44988d86..999b0478f 100644 --- a/doc/frequently-asked-questions.rst +++ b/doc/frequently-asked-questions.rst @@ -497,24 +497,29 @@ The solution is to add it as another package to the environment: Quality assurance ~~~~~~~~~~~~~~~~~ -The ``haskell.lib`` library includes a number of functions for checking -for various imperfections in Haskell packages. It’s useful to apply -these functions to your own Haskell packages and integrate that in a -Continuous Integration server like `hydra `__ -to assure your packages maintain a minimum level of quality. This -section discusses some of these functions. +The ``haskell.lib.compose`` library, (herein referred to as ``haskellLib``) +includes a number of functions for checking for various imperfections in +Haskell packages. It’s useful to apply these functions to your own Haskell +packages and integrate that in a Continuous Integration server like `hydra +`__ to assure your packages maintain a minimum level +of quality. This section discusses some of these functions. + +There also exists ``haskell.lib`` with the same functionality, but with a less +easy to compose argument ordering where the derivation being overridden comes +before any additional arguments, for this reason ``haskell.lib.compose`` is +preferred. failOnAllWarnings ^^^^^^^^^^^^^^^^^ -Applying ``haskell.lib.failOnAllWarnings`` to a Haskell package enables +Applying ``haskellLib.failOnAllWarnings`` to a Haskell package enables the ``-Wall`` and ``-Werror`` GHC options to turn all warnings into build failures. buildStrictly ^^^^^^^^^^^^^ -Applying ``haskell.lib.buildStrictly`` to a Haskell package calls +Applying ``haskellLib.buildStrictly`` to a Haskell package calls ``failOnAllWarnings`` on the given package to turn all warnings into build failures. Additionally the source of your package is gotten from first invoking ``cabal sdist`` to ensure all needed files are listed in @@ -523,7 +528,7 @@ the Cabal file. checkUnusedPackages ^^^^^^^^^^^^^^^^^^^ -Applying ``haskell.lib.checkUnusedPackages`` to a Haskell package +Applying ``haskellLib.checkUnusedPackages`` to a Haskell package invokes the `packunused `__ tool on the package. ``packunused`` complains when it finds packages listed as @@ -531,7 +536,7 @@ build-depends in the Cabal file which are redundant. For example: :: - $ nix-build -E 'let pkgs = import {}; in pkgs.haskell.lib.checkUnusedPackages {} pkgs.haskellPackages.scientific' + $ nix-build -E 'let pkgs = import {}; in pkgs.haskell.lib.compose.checkUnusedPackages {} pkgs.haskellPackages.scientific' these derivations will be built: /nix/store/3lc51cxj2j57y3zfpq5i69qbzjpvyci1-scientific-0.3.5.1.drv ... diff --git a/doc/nixpkgs-users-guide.rst b/doc/nixpkgs-users-guide.rst index c30cda104..eb9b149de 100644 --- a/doc/nixpkgs-users-guide.rst +++ b/doc/nixpkgs-users-guide.rst @@ -147,17 +147,17 @@ for hackage. You can use ``overrideSrc`` to override the source, for example: .. code:: nix - my-hledger-lib = (haskell.lib.overrideSrc haskellPackages.hledger-lib { + my-hledger-lib = (haskell.lib.compose.overrideSrc { src = /home/aengelen/dev/hledger/hledger-lib; - }); - my-hledger = (haskell.lib.overrideSrc haskellPackages.hledger { + }) haskellPackages.hledger-lib; + my-hledger = (haskell.lib.compose.overrideSrc { src = /home/aengelen/dev/hledger/hledger; - }).override { + } haskellPackages.hledger).override { hledger-lib = my-hledger-lib; }; - hledger-web = haskell.lib.justStaticExecutables ((haskell.lib.overrideSrc haskellPackages.hledger-web { + hledger-web = haskell.lib.compose.justStaticExecutables ((haskell.lib.compose.overrideSrc { src = /home/aengelen/dev/hledger/hledger-web; - }) + } haskellPackages.hledger-web) .override { hledger = my-hledger; hledger-lib = my-hledger-lib; @@ -541,17 +541,16 @@ way, or with extra environment variables. In these cases, you’ll need a enable: true shell-file: shell.nix -For more on how to write a ``shell.nix`` file see the below section. -You’ll need to express a derivation. Note that Nixpkgs ships with a -convenience wrapper function around ``mkDerivation`` called -``haskell.lib.buildStackProject`` to help you create this derivation in -exactly the way Stack expects. However for this to work you need to -disable the sandbox, which you can do by using -``--option sandbox relaxed`` or ``--option sandbox false`` to the Nix -command. All of the same inputs as ``mkDerivation`` can be provided. For -example, to build a Stack project that including packages that link -against a version of the R library compiled with special options turned -on: +For more on how to write a ``shell.nix`` file see the below section. You’ll +need to express a derivation. Note that Nixpkgs ships with a convenience +wrapper function around ``mkDerivation`` called +``haskell.lib.compose.buildStackProject`` to help you create this derivation in +exactly the way Stack expects. However for this to work you need to disable the +sandbox, which you can do by using ``--option sandbox relaxed`` or ``--option +sandbox false`` to the Nix command. All of the same inputs as ``mkDerivation`` +can be provided. For example, to build a Stack project that including packages +that link against a version of the R library compiled with special options +turned on: .. code:: nix @@ -559,7 +558,7 @@ on: let R = pkgs.R.override { enableStrictBarrier = true; }; in - haskell.lib.buildStackProject { + haskell.lib.compose.buildStackProject { name = "HaskellR"; buildInputs = [ R zeromq zlib ]; } @@ -577,7 +576,7 @@ specified in ``stack.yaml`` (only works with Stack >= 1.1.3): let R = pkgs.R.override { enableStrictBarrier = true; }; in - haskell.lib.buildStackProject { + haskell.lib.compose.buildStackProject { name = "HaskellR"; buildInputs = [ R zeromq zlib ]; inherit ghc;