Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation changes to cope with haskell.lib.compose #528

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Documentation changes to cope with haskell.lib.compose #528

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 15 additions & 10 deletions doc/frequently-asked-questions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://nixos.org/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
<https://nixos.org/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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
There also exists ``haskell.lib`` with the same functionality, but with a less
``haskell.lib`` also offers 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
Expand All @@ -523,15 +528,15 @@ the Cabal file.
checkUnusedPackages
^^^^^^^^^^^^^^^^^^^

Applying ``haskell.lib.checkUnusedPackages`` to a Haskell package
Applying ``haskellLib.checkUnusedPackages`` to a Haskell package
invokes the
`packunused <http://hackage.haskell.org/package/packunused>`__ tool on
the package. ``packunused`` complains when it finds packages listed as
build-depends in the Cabal file which are redundant. For example:

::

$ nix-build -E 'let pkgs = import <nixpkgs> {}; in pkgs.haskell.lib.checkUnusedPackages {} pkgs.haskellPackages.scientific'
$ nix-build -E 'let pkgs = import <nixpkgs> {}; in pkgs.haskell.lib.compose.checkUnusedPackages {} pkgs.haskellPackages.scientific'
these derivations will be built:
/nix/store/3lc51cxj2j57y3zfpq5i69qbzjpvyci1-scientific-0.3.5.1.drv
...
Expand Down
37 changes: 18 additions & 19 deletions doc/nixpkgs-users-guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -541,25 +541,24 @@ 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

with (import <nixpkgs> { });

let R = pkgs.R.override { enableStrictBarrier = true; };
in
haskell.lib.buildStackProject {
haskell.lib.compose.buildStackProject {
name = "HaskellR";
buildInputs = [ R zeromq zlib ];
}
Expand All @@ -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;
Expand Down