feat(third_party/bazel): Check in rules_haskell from Tweag r/17

1 files changed, 364 insertions, 0 deletions

diff --git a/third_party/bazel/rules_haskell/docs/haskell.rst b/third_party/bazel/rules_haskell/docs/haskell.rst
new file mode 100644
index 000000000000..353561111a21
--- /dev/null
+++ b/third_party/bazel/rules_haskell/docs/haskell.rst
@@ -0,0 +1,364 @@
+.. _guide:
+
+Introduction to Bazel: Building a Haskell project
+=================================================
+
+In this tutorial, you'll learn the basics of building Haskell
+applications with Bazel. You will set up your workspace and build
+a simple Haskell project that illustrates key Bazel concepts, such as
+targets and ``BUILD.bazel`` files. After completing this tutorial, take
+a look at :ref:`Common Haskell build use cases <use-cases>` for
+information on more advanced concepts such as writing and running
+Haskell tests.
+
+What you'll learn
+-----------------
+
+In this tutorial you'll learn how to:
+
+* build a target,
+* visualize the project's dependencies,
+* split the project into multiple targets and packages,
+* control target visibility across packages,
+* reference targets through labels.
+
+Before you begin
+----------------
+
+To prepare for the tutorial, first `install Bazel`_ if you don't have
+it installed already. Then, retrieve the ``rules_haskell`` GitHub
+repository::
+
+  git clone https://github.com/tweag/rules_haskell/
+
+The sample project for this tutorial is in the ``tutorial``
+directory and is structured as follows::
+
+  rules_haskell
+  └── tutorial
+     ├── WORKSPACE
+     ├── main
+     │  ├── BUILD.bazel
+     │  └── Main.hs
+     └── lib
+        ├── BUILD.bazel
+        └── Bool.hs
+
+The first thing to do is to::
+
+  $ cd tutorial
+
+Build with Bazel
+----------------
+
+Set up the workspace
+^^^^^^^^^^^^^^^^^^^^
+
+Before you can build a project, you need to set up its workspace.
+A workspace is a directory that holds your project's source files and
+Bazel's build outputs. It also contains files that Bazel recognizes as
+special:
+
+* the ``WORKSPACE`` file, which identifies the directory and its
+  contents as a Bazel workspace and lives at the root of the project's
+  directory structure,
+
+* one or more ``BUILD.bazel`` files, which tell Bazel how to build different
+  parts of the project. (A directory within the workspace that
+  contains a ``BUILD.bazel`` file is a *package*. You will learn about
+  packages later in this tutorial.)
+
+To designate a directory as a Bazel workspace, create an empty file
+named ``WORKSPACE`` in that directory.
+
+When Bazel builds the project, all inputs and dependencies must be in
+the same workspace. Files residing in different workspaces are
+independent of one another unless linked, which is beyond the scope of
+this tutorial.
+
+Understand the BUILD file
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is recommended to use a ``.bazel`` extension for each ``BUILD`` file to
+avoid clashing with files or folders already using that name.
+
+A ``BUILD.bazel`` file contains several different types of instructions for
+Bazel. The most important type is the *build rule*, which tells Bazel
+how to build the desired outputs, such as executable binaries or
+libraries. Each instance of a build rule in the ``BUILD.bazel`` file is
+called a *target* and points to a specific set of source files and
+dependencies. A target can also point to other targets.
+
+Take a look at the ``BUILD.bazel`` file in the ``tutorial/lib`` directory::
+
+  haskell_library(
+      name = "booleans",
+      srcs = ["Bool.hs"],
+  )
+
+In our example, the ``booleans`` target instantiates the
+`haskell_library`_ rule. The rule tells Bazel to build a reusable
+(statically or dynamically linked) library from the ``Bool.hs`` source
+file with no dependencies.
+
+The attributes in the target explicitly state its dependencies and
+options. While the ``name`` attribute is mandatory, many are optional.
+For example, in the ``booleans`` target, ``name`` is self-explanatory,
+and ``srcs`` specifies the source file(s) from which Bazel builds the
+target.
+
+Build the project
+^^^^^^^^^^^^^^^^^
+
+Let's build your sample project. Run the following command::
+
+  $ bazel build //lib:booleans
+
+Notice the target label - the ``//lib:`` part is the location of our
+``BUILD.bazel`` file relative to the root of the workspace, and ``booleans``
+is what we named that target in the ``BUILD.bazel`` file. (You will learn
+about target labels in more detail at the end of this tutorial.)
+
+Bazel produces output similar to the following::
+
+  INFO: Found 1 target...
+  Target //lib:booleans up-to-date:
+    bazel-bin/lib/libZSbooleans/libZSbooleans.conf
+    bazel-bin/lib/libZSbooleans/package.cache
+  INFO: Elapsed time: 2.288s, Critical Path: 0.68s
+
+Congratulations, you just built your first Bazel target! Bazel places
+build outputs in the ``bazel-bin`` directory at the root of the
+workspace. Browse through its contents to get an idea for Bazel's
+output structure.
+
+Review the dependency graph
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A successful build has all of its dependencies explicitly stated in
+the ``BUILD.bazel`` file. Bazel uses those statements to create the
+project's dependency graph, which enables accurate incremental builds.
+
+Let's visualize our sample project's dependencies. First, generate
+a text representation of the dependency graph (run the command at the
+workspace root)::
+
+  bazel query --nohost_deps --noimplicit_deps \
+    'deps(//lib:booleans)' --output graph
+
+The above command tells Bazel to look for all dependencies for the
+target ``//lib:booleans`` (excluding host and implicit dependencies)
+and format the output as a graph.
+
+Then, paste the text into GraphViz_.
+
+On Ubuntu, you can view the graph locally by installing GraphViz and the xdot
+Dot Viewer::
+
+  sudo apt update && sudo apt install graphviz xdot
+
+Then you can generate and view the graph by piping the text output above
+straight to xdot::
+
+  xdot <(bazel query --nohost_deps --noimplicit_deps \
+           'deps(//lib:booleans)' --output graph)
+
+As you can see, the first stage of the sample project has a single
+target that builds a single source file with no additional
+dependencies:
+
+.. digraph:: booleans
+
+   node [shape=box];
+   "//lib:booleans"
+   "//lib:booleans" -> "//lib:Bool.hs"
+   "//lib:Bool.hs"
+
+Now that you have set up your workspace, built your project, and
+examined its dependencies, let's add some complexity.
+
+Refine your Bazel build
+-----------------------
+
+While a single target is sufficient for small projects, you may want
+to split larger projects into multiple targets and packages to allow
+for fast incremental builds (that is, only rebuild what's changed) and
+to speed up your builds by building multiple parts of a project at
+once.
+
+Specify multiple build targets
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Let's split our sample project build into two targets. Take a look at
+the ``BUILD.bazel`` files in the ``tutorial/lib`` and ``tutorial/main``
+directories. The contents of both files could have been kept in
+a single ``BUILD.bazel`` as follows::
+
+  haskell_library(
+      name = "booleans",
+      srcs = ["Bool.hs"],
+  )
+
+  haskell_toolchain_library(name = "base")
+
+  haskell_binary(
+      name = "demorgan",
+      srcs = ["Main.hs"],
+      compiler_flags = ["-threaded"],
+      deps = [":base", ":booleans"],
+  )
+
+With this single ``BUILD.bazel`` file, Bazel first builds the ``booleans``
+library (using the `haskell_library`_ rule), then the ``demorgan``
+binary (which as an example uses the ``booleans`` library to check one
+of the De Morgan laws). The ``deps`` attribute in the ``demorgan``
+target tells Bazel that the ``:booleans`` library is required to build
+the ``demorgan`` binary. The binary also requires the ``base``
+built-in library that ships with GHC, to perform I/O among other
+things. Libraries like ``base``, ``bytestring`` and others that ship
+with GHC are special in that they are prebuilt outside of Bazel. To
+import them as regular targets, we use the `haskell_toolchain_library`_ rule.
+
+Let's build this new version of our project::
+
+  $ bazel build //main:demorgan
+
+Bazel produces output similar to the following::
+
+  INFO: Found 1 target...
+  Target //main:demorgan up-to-date:
+    bazel-bin/main/demorgan
+  INFO: Elapsed time: 2.728s, Critical Path: 1.23s
+
+Now test your freshly built binary::
+
+  $ bazel-bin/main/demorgan
+
+Or alternatively::
+
+  $ bazel run //main:demorgan
+
+If you now modify ``Bool.hs`` and rebuild the project, Bazel will
+usually only recompile that file.
+
+Looking at the dependency graph:
+
+.. digraph:: demorgan
+
+  node [shape=box];
+  "//main:demorgan"
+  "//main:demorgan" -> "//main:base\n//main:Main.hs"
+  "//main:demorgan" -> "//lib:booleans"
+  "//lib:booleans"
+  "//lib:booleans" -> "//lib:Bool.hs"
+  "//lib:Bool.hs"
+  "//main:base\n//main:Main.hs"
+
+You have now built the project with two targets. The ``demorgan``
+target builds one source file and depends on one other target
+(``//lib:booleans``), which builds one additional source file.
+
+Use multiple packages
+^^^^^^^^^^^^^^^^^^^^^
+
+Let’s now split the project into multiple packages.
+
+Notice that we actually have two sub-directories, and each contains
+a ``BUILD.bazel`` file. Therefore, to Bazel, the workspace contains two
+packages, ``lib`` and ``main``.
+
+Take a look at the ``lib/BUILD.bazel`` file::
+
+  haskell_library(
+      name = "booleans",
+      srcs = ["Bool.hs"],
+      visibility = ["//main:__pkg__"],
+  )
+
+And at the ``main/BUILD.bazel`` file::
+
+  haskell_toolchain_library(name = "base")
+
+  haskell_binary(
+      name = "demorgan",
+      srcs = ["Main.hs"],
+      compiler_flags = ["-threaded"],
+      deps = [":base", "//lib:booleans"],
+  )
+
+As you can see, the ``demorgan`` target in the ``main`` package
+depends on the ``booleans`` target in the ``lib`` package (hence the
+target label ``//lib:booleans``) - Bazel knows this through the
+``deps`` attribute.
+
+Notice that for the build to succeed, we make the ``//lib:booleans``
+target in ``lib/BUILD.bazel`` explicitly visible to targets in
+``main/BUILD.bazel`` using the ``visibility`` attribute. This is because by
+default targets are only visible to other targets in the same
+``BUILD.bazel`` file. (Bazel uses target visibility to prevent issues such
+as libraries containing implementation details leaking into public
+APIs.)
+
+You have built the project as two packages with three targets and
+understand the dependencies between them.
+
+Use labels to reference targets
+-------------------------------
+
+In ``BUILD.bazel`` files and at the command line, Bazel uses *labels* to
+reference targets - for example, ``//main:demorgan`` or
+``//lib:booleans``. Their syntax is::
+
+  //path/to/package:target-name
+
+If the target is a rule target, then ``path/to/package`` is the path
+to the directory containing the ``BUILD.bazel`` file, and ``target-name`` is
+what you named the target in the ``BUILD.bazel`` file (the ``name``
+attribute). If the target is a file target, then ``path/to/package``
+is the path to the root of the package, and ``target-name`` is the
+name of the target file, including its full path.
+
+When referencing targets within the same package, you can skip the
+package path and just use ``//:target-name``. When referencing targets
+within the same ``BUILD.bazel`` file, you can even skip the ``//`` workspace
+root identifier and just use ``:target-name``.
+
+Further reading
+---------------
+
+Congratulations! You now know the basics of building a Haskell project
+with Bazel. Next, read up on the most common :ref:`Common Haskell
+build use cases <use-cases>`. Then, check out the following:
+
+* `External Dependencies`_ to learn more about working with local and
+   remote repositories.
+
+* The `Build Encyclopedia`_ to learn more about Bazel.
+
+* The `C++ build tutorial`_ to get started with building C++
+  applications with Bazel.
+
+* The `Java build tutorial`_ to get started with building Java
+  applications with Bazel.
+
+* The `Android application tutorial`_ to get started with building
+  mobile applications for Android with Bazel.
+
+* The `iOS application tutorial`_ to get started with building mobile
+  applications for iOS with Bazel.
+
+Happy building!
+
+.. note:: This tutorial is adapted from the Bazel `C++ build tutorial`_.
+
+.. _install Bazel: https://docs.bazel.build/versions/master/install.html
+.. _haskell_binary: http://api.haskell.build/haskell/haskell.html#haskell_binary
+.. _haskell_toolchain_library: http://api.haskell.build/haskell/haskell.html#haskell_toolchain_library
+.. _haskell_library: http://api.haskell.build/haskell/haskell.html#haskell_library
+.. _graphviz: https://www.graphviz.org/
+.. _external dependencies: https://docs.bazel.build/versions/master/external.html
+.. _build encyclopedia: https://docs.bazel.build/versions/master/be/overview.html
+.. _C++ build tutorial: https://docs.bazel.build/versions/master/tutorial/cpp.html
+.. _Java build tutorial: https://docs.bazel.build/versions/master/tutorial/java.html
+.. _Android application tutorial: https://docs.bazel.build/versions/master/tutorial/android-app.html
+.. _iOS application tutorial: https://docs.bazel.build/versions/master/tutorial/ios-app.html