doc/nix-local-build.rst

   1 .. highlight:: console
   2
   3 Quickstart
   4 ==========
   5
   6 Suppose that you are in a directory containing a single Cabal package
   7 which you wish to build (if you haven't set up a package yet check
   8 out :doc:`developing packages <developing-packages>` for
   9 instructions). You can configure and build it using Nix-style
  10 local builds with this command (configuring is not necessary):
  11
  12 ::
  13
  14     $ cabal v2-build
  15
  16 To open a GHCi shell with this package, use this command:
  17
  18 ::
  19
  20     $ cabal v2-repl
  21
  22 To run an executable defined in this package, use this command:
  23
  24 ::
  25
  26     $ cabal v2-run <executable name> [executable args]
  27
  28 Developing multiple packages
  29 ----------------------------
  30
  31 Many Cabal projects involve multiple packages which need to be built
  32 together. To build multiple Cabal packages, you need to first create a
  33 ``cabal.project`` file which declares where all the local package
  34 directories live. For example, in the Cabal repository, there is a root
  35 directory with a folder per package, e.g., the folders ``Cabal`` and
  36 ``cabal-install``. The ``cabal.project`` file specifies each folder as
  37 part of the project:
  38
  39 .. code-block:: cabal
  40
  41     packages: Cabal/
  42               cabal-install/
  43
  44 The expectation is that a ``cabal.project`` is checked into your source
  45 control, to be used by all developers of a project. If you need to make
  46 local changes, they can be placed in ``cabal.project.local`` (which
  47 should not be checked in.)
  48
  49 Then, to build every component of every package, from the top-level
  50 directory, run the command: (using cabal-install-2.0 or greater.)
  51
  52 ::
  53
  54     $ cabal v2-build all
  55
  56 To build a specific package, you can either run ``v2-build`` from the
  57 directory of the package in question:
  58
  59 ::
  60
  61     $ cd cabal-install
  62     $ cabal v2-build
  63
  64 or you can pass the name of the package as an argument to
  65 ``cabal v2-build`` (this works in any subdirectory of the project):
  66
  67 ::
  68
  69     $ cabal v2-build cabal-install
  70
  71 You can also specify a specific component of the package to build. For
  72 example, to build a test suite named ``package-tests``, use the command:
  73
  74 ::
  75
  76     $ cabal v2-build package-tests
  77
  78 Targets can be qualified with package names. So to request
  79 ``package-tests`` *from* the ``Cabal`` package, use
  80 ``Cabal-tests:package-tests``.
  81
  82 Unlike sandboxes, there is no need to setup a sandbox or ``add-source``
  83 projects; just check in ``cabal.project`` to your repository and
  84 ``v2-build`` will just work.
  85
  86 Cookbook
  87 ========
  88
  89 How can I profile my library/application?
  90 -----------------------------------------
  91
  92 Create or edit your ``cabal.project.local``, adding the following
  93 line::
  94
  95     profiling: True
  96
  97 Now, ``cabal v2-build`` will automatically build all libraries and
  98 executables with profiling.  You can fine-tune the profiling settings
  99 for each package using :cfg-field:`profiling-detail`::
 100
 101     package p
 102         profiling-detail: toplevel-functions
 103
 104 Alternately, you can call ``cabal v2-build --enable-profiling`` to
 105 temporarily build with profiling.
 106
 107 How can I have a reproducible set of versions for my dependencies?
 108 ------------------------------------------------------------------
 109
 110 You can use ``cabal freeze`` to save the solver results to a file.
 111
 112 Since Cabal 3.8, an alternative approach is to use a :ref:`remote project
 113 configuration file<conditionals and imports>`: to specify a set of versions for
 114 packages.
 115
 116 One provider of such package sets is Stackage_, and its package sets are called
 117 snapshots. The Stackage snapshots contain a set of packages from Hackage that
 118 have all been verified to build with a given version of GHC.
 119
 120 For example, the snapshot named lts-19.2 contains versioned packages which all
 121 compile on GHC 9.0.2. You can conveniently review the `versions of packages in
 122 lts-19.2`_. Using the following ``cabal.project`` file, Cabal will use the
 123 versions of packages that the this snapshot specifies:
 124
 125 ::
 126
 127     packages: .
 128     import: https://www.stackage.org/lts-19.2/cabal.config
 129
 130 Please note that project files do not get bundled in Cabal package tarballs,
 131 made using e.g. ``cabal sdist``. Project files are intended for use in local
 132 development environments.
 133
 134 .. _Stackage: https://stackage.org/
 135 .. _versions of packages in lts-19.2: https://www.stackage.org/lts-19.2
 136
 137 How it works
 138 ============
 139
 140 Local versus external packages
 141 ------------------------------
 142
 143 One of the primary innovations of Nix-style local builds is the
 144 distinction between local packages, which users edit and recompile and
 145 must be built per-project, versus external packages, which can be cached
 146 across projects. To be more precise:
 147
 148 1. A **local package** is one that is listed explicitly in the
 149    ``packages``, ``optional-packages`` or ``extra-packages`` fields of a
 150    project. Packages in the former two fields will usually have their
 151    source code stored in a folder in your project, while ``extra-packages`` lists
 152    packages residing on Hackage that are treated as being local anyway.
 153
 154 Local packages, as well as the external packages (below) which depend on
 155 them, are built **inplace**, meaning that they are always built
 156 specifically for the project and are not installed globally. Inplace
 157 packages are not cached and not given unique hashes, which makes them
 158 suitable for packages which you want to edit and recompile.
 159
 160 2. An **external package** is any package which is not listed in the
 161    ``packages``, ``optional-packages`` and ``extra-packages`` fields.
 162    The source code for external packages is usually retrieved from Hackage.
 163
 164 When an external package does not depend on an inplace package, it can
 165 be built and installed to a **global** store, which can be shared across
 166 projects. These build products are identified by a hash based on all of
 167 the inputs which influence the compilation of a package (flags,
 168 dependency selection, etc.). Just as in Nix, these hashes uniquely
 169 identify the result of a build; if we compute this identifier and we
 170 find that we already have this ID built, we can just use the already
 171 built version.
 172
 173 The global package store is ``~/.cabal/store`` (configurable via
 174 global `store-dir` option); if you need to clear your store for
 175 whatever reason (e.g., to reclaim disk space or because the global
 176 store is corrupted), deleting this directory is safe (``v2-build``
 177 will just rebuild everything it needs on its next invocation).
 178
 179 This split motivates some of the UI choices for Nix-style local build
 180 commands. For example, flags passed to ``cabal v2-build`` are only
 181 applied to *local* packages, so that adding a flag to
 182 ``cabal v2-build`` doesn't necessitate a rebuild of *every* transitive
 183 dependency in the global package store.
 184
 185 In cabal-install 2.0 and above, Nix-style local builds also take advantage of a
 186 new Cabal library feature, `per-component
 187 builds <https://github.com/ezyang/ghc-proposals/blob/master/proposals/0000-componentized-cabal.rst>`__,
 188 where each component of a package is configured and built separately.
 189 This can massively speed up rebuilds of packages with lots of components
 190 (e.g., a package that defines multiple executables), as only one
 191 executable needs to be rebuilt. Packages that use Custom setup scripts
 192 are not currently built on a per-component basis.
 193
 194 Where are my build products?
 195 ----------------------------
 196
 197 A major deficiency in the current implementation of v2-build is that
 198 there is no programmatic way to access the location of build products.
 199 The location of the build products is intended to be an internal
 200 implementation detail of v2-build, but we also understand that many
 201 unimplemented features can only be reasonably worked around by
 202 accessing build products directly.
 203
 204 The location where build products can be found varies depending on the
 205 version of cabal-install:
 206
 207 -  In cabal-install-1.24, the dist directory for a package ``p-0.1`` is
 208    stored in ``dist-newstyle/build/p-0.1``. For example, if you built an
 209    executable or test suite named ``pexe``, it would be located at
 210    ``dist-newstyle/build/p-0.1/build/pexe/pexe``.
 211
 212 -  In cabal-install-2.0, the dist directory for a package ``p-0.1``
 213    defining a library built with GHC 8.0.1 on 64-bit Linux is
 214    ``dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1``. When
 215    per-component builds are enabled (any non-Custom package), a
 216    subcomponent like an executable or test suite named ``pexe`` will be
 217    stored at
 218    ``dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/c/pexe``; thus,
 219    the full path of the executable is
 220    ``dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/c/pexe/build/pexe/pexe``
 221    (you can see why we want this to be an implementation detail!)
 222
 223 -  In cabal-install-2.2 and above, the ``/c/`` part of the above path
 224    is replaced with one of ``/l/``, ``/x/``, ``/f/``, ``/t/``, or
 225    ``/b/``, depending on the type of component (sublibrary,
 226    executable, foreign library, test suite, or benchmark
 227    respectively). So the full path to an executable named ``pexe``
 228    compiled with GHC 8.0.1 on a 64-bit Linux is now
 229    ``dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/x/pexe/build/pexe/pexe``;
 230    for a benchmark named ``pbench`` it now is
 231    ``dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/b/pbench/build/pbench/pbench``;
 232
 233
 234 The paths are a bit longer in 2.0 and above but the benefit is that you can
 235 transparently have multiple builds with different versions of GHC. We
 236 plan to add the ability to create aliases for certain build
 237 configurations, and more convenient paths to access particularly useful
 238 build products like executables.
 239
 240 Caching
 241 -------
 242
 243 Nix-style local builds support a robust caching system which helps to reduce
 244 the time it takes to execute a rebuild cycle. While the details of how
 245 ``cabal-install`` does caching are an implementation detail and may
 246 change in the future, knowing what gets cached is helpful for
 247 understanding the performance characteristics of invocations to
 248 ``v2-build``. The cached intermediate results are stored in
 249 ``dist-newstyle/cache``; this folder can be safely deleted to clear the
 250 cache.
 251
 252 The following intermediate results are cached in the following files in
 253 this folder (the most important two are first):
 254
 255 ``solver-plan`` (binary)
 256     The result of calling the dependency solver, assuming that the
 257     Hackage index, local ``cabal.project`` file, and local ``cabal``
 258     files are unmodified. (Notably, we do NOT have to dependency solve
 259     again if new build products are stored in the global store; the
 260     invocation of the dependency solver is independent of what is
 261     already available in the store.)
 262 ``source-hashes`` (binary)
 263     The hashes of all local source files. When all local source files of
 264     a local package are unchanged, ``cabal v2-build`` will skip
 265     invoking ``setup build`` entirely (saving us from a possibly
 266     expensive call to ``ghc --make``). The full list of source files
 267     participating in compilation is determined using
 268     ``cabal sdist --list-only``. Thus if you do not list all your
 269     source files in a Cabal file, Cabal may fail to recompile when you
 270     edit them.
 271 ``config`` (binary)
 272     The full project configuration, merged from ``cabal.project`` (and
 273     friends) as well as the command line arguments.
 274 ``compiler`` (binary)
 275     The configuration of the compiler being used to build the project.
 276 ``improved-plan`` (binary)
 277     Like ``solver-plan``, but with all non-inplace packages improved
 278     into pre-existing copies from the store.
 279 ``plan.json`` (JSON)
 280     A JSON serialization of the computed install plan intended
 281     for integrating ``cabal`` with external tooling.
 282     The `cabal-plan <http://hackage.haskell.org/package/cabal-plan>`__
 283     package provides a library for parsing ``plan.json`` files into a
 284     Haskell data structure as well as an example tool showing possible
 285     applications.
 286
 287     .. todo::
 288
 289         Document JSON schema (including version history of schema)
 290
 291
 292 Note that every package also has a local cache managed by the Cabal
 293 build system, e.g., in ``$distdir/cache``.