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):
16 To open a GHCi shell with this package, use this command:
22 To run an executable defined in this package, use this command:
26 $ cabal v2-run <executable name> [executable args]
28 Developing multiple packages
29 ----------------------------
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
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.)
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.)
56 To build a specific package, you can either run ``v2-build`` from the
57 directory of the package in question:
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):
69 $ cabal v2-build cabal-install
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:
76 $ cabal v2-build package-tests
78 Targets can be qualified with package names. So to request
79 ``package-tests`` *from* the ``Cabal`` package, use
80 ``Cabal-tests:package-tests``.
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.
89 How can I profile my library/application?
90 -----------------------------------------
92 Create or edit your ``cabal.project.local``, adding the following
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`::
102 profiling-detail: toplevel-functions
104 Alternately, you can call ``cabal v2-build --enable-profiling`` to
105 temporarily build with profiling.
107 How can I have a reproducible set of versions for my dependencies?
108 ------------------------------------------------------------------
110 You can use ``cabal freeze`` to save the solver results to a file.
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
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.
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:
128 import: https://www.stackage.org/lts-19.2/cabal.config
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.
134 .. _Stackage: https://stackage.org/
135 .. _versions of packages in lts-19.2: https://www.stackage.org/lts-19.2
140 Local versus external packages
141 ------------------------------
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:
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.
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.
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.
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
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).
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.
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.
194 Where are my build products?
195 ----------------------------
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.
204 The location where build products can be found varies depending on the
205 version of cabal-install:
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``.
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
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!)
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``;
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.
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
252 The following intermediate results are cached in the following files in
253 this folder (the most important two are first):
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
271 ``config`` (same format as ``cabal.project``)
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.
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
289 Document JSON schema (including version history of schema)
292 Note that every package also has a local cache managed by the Cabal
293 build system, e.g., in ``$distdir/cache``.