diff options
Diffstat (limited to 'third_party/bazel/rules_haskell/docs/haskell-use-cases.rst')
| -rw-r--r-- | third_party/bazel/rules_haskell/docs/haskell-use-cases.rst | 283 |
1 files changed, 283 insertions, 0 deletions
diff --git a/third_party/bazel/rules_haskell/docs/haskell-use-cases.rst b/third_party/bazel/rules_haskell/docs/haskell-use-cases.rst new file mode 100644 index 000000000000..a8c4340cf70f --- /dev/null +++ b/third_party/bazel/rules_haskell/docs/haskell-use-cases.rst @@ -0,0 +1,283 @@ +.. _use-cases: + +Common Haskell Build Use Cases +============================== + +Picking a compiler +------------------ + +Unlike Bazel's native C++ rules, rules_haskell does not auto-detect +a Haskell compiler toolchain from the environment. This is by design. +We require that you declare a compiler to use in your ``WORKSPACE`` +file. + +There are two common sources for a compiler. One is to use the +official binary distributions from `haskell.org`_. This is done using +the `ghc_bindist`_ rule. + +The compiler can also be pulled from Nixpkgs_, a set of package +definitions for the `Nix package manager`_. Pulling the compiler from +Nixpkgs makes the build more hermetic, because the transitive closure +of the compiler and all its dependencies is precisely defined in the +``WORKSPACE`` file. Use `rules_nixpkgs`_ to do so (where ``X.Y.Z`` +stands for any recent release):: + + load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") + + http_archive( + name = "io_tweag_rules_nixpkgs", + strip_prefix = "rules_nixpkgs-X.Y.Z", + urls = ["https://github.com/tweag/rules_nixpkgs/archive/vX.Y.Z.tar.gz"], + ) + + load( + "@io_tweag_rules_nixpkgs//nixpkgs:nixpkgs.bzl", + "nixpkgs_git_repository", + "nixpkgs_package" + ) + + nixpkgs_git_repository( + name = "nixpkgs", + revision = "18.09", # Any tag or commit hash + ) + + nixpkgs_package( + name = "ghc", + repositories = { "nixpkgs": "@nixpkgs//:default.nix" } + attribute_path = "haskell.compiler.ghc843", # Any compiler version + build_file = "@io_tweag_rules_haskell//haskell:ghc.BUILD", + ) + + register_toolchains("//:ghc") + +This workspace description specifies which Nixpkgs version to use, +then exposes a Nixpkgs package containing the GHC compiler. The +description assumes that there exists a ``BUILD`` file at the root of +the repository that includes the following:: + + haskell_toolchain( + name = "ghc", + # Versions here and in WORKSPACE must match. + version = "8.4.3", + # Use binaries from @ghc//:bin to define //:ghc toolchain. + tools = ["@ghc//:bin"], + ) + +.. _Bazel+Nix blog post: https://www.tweag.io/posts/2018-03-15-bazel-nix.html +.. _Nix package manager: https://nixos.org/nix +.. _Nixpkgs: https://nixos.org/nixpkgs/manual/ +.. _ghc_bindist: http://api.haskell.build/haskell/ghc_bindist.html#ghc_bindist +.. _haskell.org: https://haskell.org +.. _haskell_binary: http://api.haskell.build/haskell/haskell.html#haskell_binary +.. _haskell_library: http://api.haskell.build/haskell/haskell.html#haskell_library +.. _rules_nixpkgs: https://github.com/tweag/rules_nixpkgs + +Loading targets in a REPL +------------------------- + +Rebuilds are currently not incremental *within* a binary or library +target (rebuilds are incremental across targets of course). Any change +in any source file will trigger a rebuild of all source files listed +in a target. In Bazel, it is conventional to decompose libraries into +small units. In this way, libraries require less work to rebuild. +Still, for interactive development full incrementality and fast +recompilation times are crucial for a good developer experience. We +recommend making all development REPL-driven for fast feedback when +source files change. + +Every `haskell_binary`_ and every `haskell_library`_ target has an +optional executable output that can be run to drop you into an +interactive session. If the target's name is ``foo``, then the REPL +output is called ``foo@repl``. + +Consider the following binary target:: + + haskell_binary( + name = "hello", + srcs = ["Main.hs", "Other.hs"], + deps = ["//lib:some_lib"], + ) + +The target above also implicitly defines ``hello@repl``. You can call +the REPL like this (requires Bazel 0.15 or later):: + + $ bazel run //:hello@repl + +This works for any ``haskell_binary`` or ``haskell_library`` target. +Modules of all libraries will be loaded in interpreted mode and can be +reloaded using the ``:r`` GHCi command when source files change. + +Building code with Hackage dependencies (using Nix) +--------------------------------------------------- + +Each Haskell library or binary needs a simple build description to +tell Bazel what source files to use and what the dependencies are, if +any. Packages on Hackage don't usually ship with `BUILD.bazel` files. +So if your code depends on them, you either need to write a build +description for each package, generate one (see next section), or +decide not to use Bazel to build packages published on Hackage. This +section documents one way to do the latter. + +Nix is a package manager. The set of package definitions is called +Nixpkgs. This repository contains definitions for most actively +maintained Cabal packages published on Hackage. Where these packages +depend on system libraries like zlib, ncurses or libpng, Nixpkgs also +contains package descriptions for those, and declares those as +dependencies of the Cabal packages. Since these definitions already +exist, we can reuse them instead of rewriting these definitions as +build definitions in Bazel. See the `Bazel+Nix blog post`_ for a more +detailed rationale. + +To use Nixpkgs in Bazel, we need `rules_nixpkgs`_. See `Picking +a compiler`_ for how to import Nixpkgs rules into your workspace and +how to use a compiler from Nixpkgs. To use Cabal packages from +Nixpkgs, replace the compiler definition with the following:: + + nixpkgs_package( + name = "ghc", + repositories = { "nixpkgs": "@nixpkgs//:default.nix" }, + nix_file = "//:ghc.nix", + build_file = "@io_tweag_rules_haskell//haskell:ghc.BUILD", + ) + +This definition assumes a ``ghc.nix`` file at the root of the +repository. In this file, you can use the Nix expression language to +construct a compiler with all the packages you depend on in scope:: + + with (import <nixpkgs> {}); + + haskellPackages.ghcWithPackages (p: with p; [ + containers + lens + text + ]) + +Each package mentioned in ``ghc.nix`` can then be imported using +`haskell_toolchain_library`_ in ``BUILD`` files. + +.. _haskell_toolchain_library: http://api.haskell.build/haskell/haskell.html#haskell_toolchain_library + +Building code with Hackage dependencies (using Hazel) +----------------------------------------------------- + +.. todo:: + + Explain how to use Hazel instead of Nix + +Generating API documentation +---------------------------- + +The `haskell_doc`_ rule can be used to build API documentation for +a given library (using Haddock). Building a target called +``//my/pkg:mylib_docs`` would make the documentation available at +``bazel-bin/my/pkg/mylib_docs/index/index.html``. + +Alternatively, you can use the +``@io_tweag_rules_haskell//haskell:haskell.bzl%haskell_doc_aspect`` +aspect to ask Bazel from the command-line to build documentation for +any given target (or indeed all targets), like in the following: + +.. code-block:: console + + $ bazel build //my/pkg:mylib \ + --aspects @io_tweag_rules_haskell//haskell:haskell.bzl%haskell_doc_aspect + +.. _haskell_doc: http://api.haskell.build/haskell/haddock.html#haskell_doc + +Linting your code +----------------- + +The `haskell_lint`_ rule does not build code but runs the GHC +typechecker on all listed dependencies. Warnings are treated as +errors. + +Alternatively, you can directly check a target using + +.. code-block:: console + + $ bazel build //my/haskell:target \ + --aspects @io_tweag_rules_haskell//haskell:haskell.bzl%haskell_lint_aspect + +.. _haskell_lint: http://api.haskell.build/haskell/lint.html#haskell_lint + +Checking code coverage +---------------------- + +"Code coverage" is the name given to metrics that describe how much source +code is covered by a given test suite. A specific code coverage metric +implemented here is expression coverage, or the number of expressions in +the source code that are explored when the tests are run. + +Haskell's ``ghc`` compiler has built-in support for code coverage analysis, +through the hpc_ tool. The Haskell rules allow the use of this tool to analyse +``haskell_library`` coverage by ``haskell_test`` rules. To do so, you have a +few options. You can add +``expected_covered_expressions_percentage=<some integer between 0 and 100>`` to +the attributes of a ``haskell_test``, and if the expression coverage percentage +is lower than this amount, the test will fail. Alternatively, you can add +``expected_uncovered_expression_count=<some integer greater or equal to 0>`` to +the attributes of a ``haskell_test``, and instead the test will fail if the +number of uncovered expressions is greater than this amount. Finally, you could +do both at once, and have both of these checks analyzed by the coverage runner. +To see the coverage details of the test suite regardless of if the test passes +or fails, add ``--test_output=all`` as a flag when invoking the test, and there +will be a report in the test output. You will only see the report if you +required a certain level of expression coverage in the rule attributes. + +For example, your BUILD file might look like this: :: + + haskell_library( + name = "lib", + srcs = ["Lib.hs"], + deps = [ + "//tests/hackage:base", + ], + ) + + haskell_test( + name = "test", + srcs = ["Main.hs"], + deps = [ + ":lib", + "//tests/hackage:base", + ], + expected_covered_expressions_percentage = 80, + expected_uncovered_expression_count = 10, + ) + +And if you ran ``bazel coverage //somepackage:test --test_output=all``, you +might see a result like this: :: + + INFO: From Testing //somepackage:test: + ==================== Test output for //somepackage:test: + Overall report + 100% expressions used (9/9) + 100% boolean coverage (0/0) + 100% guards (0/0) + 100% 'if' conditions (0/0) + 100% qualifiers (0/0) + 100% alternatives used (0/0) + 100% local declarations used (0/0) + 100% top-level declarations used (3/3) + ============================================================================= + +Here, the test passes because it actually has 100% expression coverage and 0 +uncovered expressions, which is even better than we expected on both counts. + +There is an optional ``haskell_test`` attribute called +``strict_coverage_analysis``, which is a boolean that changes the coverage +analysis such that even having better coverage than expected fails the test. +This can be used to enforce that developers must upgrade the expected test +coverage when they improve it. On the other hand, it requires changing the +expected coverage for almost any change. + +There a couple of notes regarding the coverage analysis functionality: + +- Coverage analysis currently is scoped to all source files and all + locally-built Haskell dependencies (both direct and transitive) for a given + test rule. +- Coverage-enabled build and execution for ``haskell_test`` targets may take + longer than regular. However, this has not effected regular ``run`` / + ``build`` / ``test`` performance. + +.. _hpc: <http://hackage.haskell.org/package/hpc> |