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`` field of a
 150    project. Usually, these refer to packages whose source code lives
 151    directly in a folder in your project. But you can list an
 152    arbitrary Hackage package in :cfg-field:`packages`
 153    to force it to be treated as local.
 154
 155 Local packages, as well as the external packages (below) which depend on
 156 them, are built **inplace**, meaning that they are always built
 157 specifically for the project and are not installed globally. Inplace
 158 packages are not cached and not given unique hashes, which makes them
 159 suitable for packages which you want to edit and recompile.
 160
 161 2. An **external package** is any package which is not listed in the
 162    ``packages`` field. The source code for external packages is usually
 163    retrieved from Hackage.
 164
 165 When an external package does not depend on an inplace package, it can
 166 be built and installed to a **global** store, which can be shared across
 167 projects. These build products are identified by a hash based on all of
 168 the inputs which influence the compilation of a package (flags,
 169 dependency selection, etc.). Just as in Nix, these hashes uniquely
 170 identify the result of a build; if we compute this identifier and we
 171 find that we already have this ID built, we can just use the already
 172 built version.
 173
 174 The global package store is ``~/.cabal/store`` (configurable via
 175 global `store-dir` option); if you need to clear your store for
 176 whatever reason (e.g., to reclaim disk space or because the global
 177 store is corrupted), deleting this directory is safe (``v2-build``
 178 will just rebuild everything it needs on its next invocation).
 179
 180 This split motivates some of the UI choices for Nix-style local build
 181 commands. For example, flags passed to ``cabal v2-build`` are only
 182 applied to *local* packages, so that adding a flag to
 183 ``cabal v2-build`` doesn't necessitate a rebuild of *every* transitive
 184 dependency in the global package store.
 185
 186 In cabal-install 2.0 and above, Nix-style local builds also take advantage of a
 187 new Cabal library feature, `per-component
 188 builds <https://github.com/ezyang/ghc-proposals/blob/master/proposals/0000-componentized-cabal.rst>`__,
 189 where each component of a package is configured and built separately.
 190 This can massively speed up rebuilds of packages with lots of components
 191 (e.g., a package that defines multiple executables), as only one
 192 executable needs to be rebuilt. Packages that use Custom setup scripts
 193 are not currently built on a per-component basis.
 194
 195 Where are my build products?
 196 ----------------------------
 197
 198 A major deficiency in the current implementation of v2-build is that
 199 there is no programmatic way to access the location of build products.
 200 The location of the build products is intended to be an internal
 201 implementation detail of v2-build, but we also understand that many
 202 unimplemented features can only be reasonably worked around by
 203 accessing build products directly.
 204
 205 The location where build products can be found varies depending on the
 206 version of cabal-install:
 207
 208 -  In cabal-install-1.24, the dist directory for a package ``p-0.1`` is
 209    stored in ``dist-newstyle/build/p-0.1``. For example, if you built an
 210    executable or test suite named ``pexe``, it would be located at
 211    ``dist-newstyle/build/p-0.1/build/pexe/pexe``.
 212
 213 -  In cabal-install-2.0, the dist directory for a package ``p-0.1``
 214    defining a library built with GHC 8.0.1 on 64-bit Linux is
 215    ``dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1``. When
 216    per-component builds are enabled (any non-Custom package), a
 217    subcomponent like an executable or test suite named ``pexe`` will be
 218    stored at
 219    ``dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/c/pexe``; thus,
 220    the full path of the executable is
 221    ``dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/c/pexe/build/pexe/pexe``
 222    (you can see why we want this to be an implementation detail!)
 223
 224 -  In cabal-install-2.2 and above, the ``/c/`` part of the above path
 225    is replaced with one of ``/l/``, ``/x/``, ``/f/``, ``/t/``, or
 226    ``/b/``, depending on the type of component (sublibrary,
 227    executable, foreign library, test suite, or benchmark
 228    respectively). So the full path to an executable named ``pexe``
 229    compiled with GHC 8.0.1 on a 64-bit Linux is now
 230    ``dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/x/pexe/build/pexe/pexe``;
 231    for a benchmark named ``pbench`` it now is
 232    ``dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/b/pbench/build/pbench/pbench``;
 233
 234
 235 The paths are a bit longer in 2.0 and above but the benefit is that you can
 236 transparently have multiple builds with different versions of GHC. We
 237 plan to add the ability to create aliases for certain build
 238 configurations, and more convenient paths to access particularly useful
 239 build products like executables.
 240
 241 Caching
 242 -------
 243
 244 Nix-style local builds support a robust caching system which helps to reduce
 245 the time it takes to execute a rebuild cycle. While the details of how
 246 ``cabal-install`` does caching are an implementation detail and may
 247 change in the future, knowing what gets cached is helpful for
 248 understanding the performance characteristics of invocations to
 249 ``v2-build``. The cached intermediate results are stored in
 250 ``dist-newstyle/cache``; this folder can be safely deleted to clear the
 251 cache.
 252
 253 The following intermediate results are cached in the following files in
 254 this folder (the most important two are first):
 255
 256 ``solver-plan`` (binary)
 257     The result of calling the dependency solver, assuming that the
 258     Hackage index, local ``cabal.project`` file, and local ``cabal``
 259     files are unmodified. (Notably, we do NOT have to dependency solve
 260     again if new build products are stored in the global store; the
 261     invocation of the dependency solver is independent of what is
 262     already available in the store.)
 263 ``source-hashes`` (binary)
 264     The hashes of all local source files. When all local source files of
 265     a local package are unchanged, ``cabal v2-build`` will skip
 266     invoking ``setup build`` entirely (saving us from a possibly
 267     expensive call to ``ghc --make``). The full list of source files
 268     participating in compilation is determined using
 269     ``cabal sdist --list-only``. Thus if you do not list all your
 270     source files in a Cabal file, Cabal may fail to recompile when you
 271     edit them.
 272 ``config`` (same format as ``cabal.project``)
 273     The full project configuration, merged from ``cabal.project`` (and
 274     friends) as well as the command line arguments.
 275 ``compiler`` (binary)
 276     The configuration of the compiler being used to build the project.
 277 ``improved-plan`` (binary)
 278     Like ``solver-plan``, but with all non-inplace packages improved
 279     into pre-existing copies from the store.
 280 ``plan.json`` (JSON)
 281     A JSON serialization of the computed install plan intended
 282     for integrating ``cabal`` with external tooling.
 283     The `cabal-plan <http://hackage.haskell.org/package/cabal-plan>`__
 284     package provides a library for parsing ``plan.json`` files into a
 285     Haskell data structure as well as an example tool showing possible
 286     applications.
 287
 288     .. todo::
 289
 290         Document JSON schema (including version history of schema)
 291
 292
 293 Note that every package also has a local cache managed by the Cabal
 294 build system, e.g., in ``$distdir/cache``.