diff options
Diffstat (limited to 'third_party/bazel/rules_haskell/docs/haskell.rst')
| -rw-r--r-- | third_party/bazel/rules_haskell/docs/haskell.rst | 364 |
1 files changed, 0 insertions, 364 deletions
diff --git a/third_party/bazel/rules_haskell/docs/haskell.rst b/third_party/bazel/rules_haskell/docs/haskell.rst deleted file mode 100644 index 353561111a..0000000000 --- a/third_party/bazel/rules_haskell/docs/haskell.rst +++ /dev/null @@ -1,364 +0,0 @@ -.. _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 |