Commit 3752c3e5 authored by Oleg Grenrus's avatar Oleg Grenrus

Separate reference parts from tutorial parts

parent 10088050
.. _buildinfo-field-reference:
==================================================
BuildInfo field reference
==================================================
Field Syntax Reference
======================
Notation
---------------
......
cabal-install Commands
======================
We now give an in-depth description of all the commands, describing the
arguments and flags they accept.
cabal v2-configure
-------------------
``cabal v2-configure`` takes a set of arguments and writes a
``cabal.project.local`` file based on the flags passed to this command.
``cabal v2-configure FLAGS; cabal new-build`` is roughly equivalent to
``cabal v2-build FLAGS``, except that with ``new-configure`` the flags
are persisted to all subsequent calls to ``v2-build``.
``cabal v2-configure`` is intended to be a convenient way to write out
a ``cabal.project.local`` for simple configurations; e.g.,
``cabal v2-configure -w ghc-7.8`` would ensure that all subsequent
builds with ``cabal v2-build`` are performed with the compiler
``ghc-7.8``. For more complex configuration, we recommend writing the
``cabal.project.local`` file directly (or placing it in
``cabal.project``!)
``cabal v2-configure`` inherits options from ``Cabal``. semantics:
- Any flag accepted by ``./Setup configure``.
- Any flag accepted by ``cabal configure`` beyond
``./Setup configure``, namely ``--cabal-lib-version``,
``--constraint``, ``--preference`` and ``--solver.``
- Any flag accepted by ``cabal install`` beyond ``./Setup configure``.
- Any flag accepted by ``./Setup haddock``.
The options of all of these flags apply only to *local* packages in a
project; this behavior is different than that of ``cabal install``,
which applies flags to every package that would be built. The motivation
for this is to avoid an innocuous addition to the flags of a package
resulting in a rebuild of every package in the store (which might need
to happen if a flag actually applied to every transitive dependency). To
apply options to an external package, use a ``package`` stanza in a
``cabal.project`` file.
cabal v2-update
----------------
``cabal v2-update`` updates the state of the package index. If the
project contains multiple remote package repositories it will update
the index of all of them (e.g. when using overlays).
Some examples:
::
$ cabal v2-update # update all remote repos
$ cabal v2-update head.hackage # update only head.hackage
cabal v2-build
---------------
``cabal v2-build`` takes a set of targets and builds them. It
automatically handles building and installing any dependencies of these
targets.
A target can take any of the following forms:
- A package target: ``package``, which specifies that all enabled
components of a package to be built. By default, test suites and
benchmarks are *not* enabled, unless they are explicitly requested
(e.g., via ``--enable-tests``.)
- A component target: ``[package:][ctype:]component``, which specifies
a specific component (e.g., a library, executable, test suite or
benchmark) to be built.
- All packages: ``all``, which specifies all packages within the project.
- Components of a particular type: ``package:ctypes``, ``all:ctypes``:
which specifies all components of the given type. Where valid
``ctypes`` are:
- ``libs``, ``libraries``,
- ``flibs``, ``foreign-libraries``,
- ``exes``, ``executables``,
- ``tests``,
- ``benches``, ``benchmarks``.
In component targets, ``package:`` and ``ctype:`` (valid component types
are ``lib``, ``flib``, ``exe``, ``test`` and ``bench``) can be used to
disambiguate when multiple packages define the same component, or the
same component name is used in a package (e.g., a package ``foo``
defines both an executable and library named ``foo``). We always prefer
interpreting a target as a package name rather than as a component name.
Some example targets:
::
$ cabal v2-build lib:foo-pkg # build the library named foo-pkg
$ cabal v2-build foo-pkg:foo-tests # build foo-tests in foo-pkg
(There is also syntax for specifying module and file targets, but it
doesn't currently do anything.)
Beyond a list of targets, ``cabal v2-build`` accepts all the flags that
``cabal v2-configure`` takes. Most of these flags are only taken into
consideration when building local packages; however, some flags may
cause extra store packages to be built (for example,
``--enable-profiling`` will automatically make sure profiling libraries
for all transitive dependencies are built and installed.)
In addition ``cabal v2-build`` accepts these flags:
- ``--only-configure``: When given we will forgoe performing a full build and
abort after running the configure phase of each target package.
cabal v2-repl
--------------
``cabal v2-repl TARGET`` loads all of the modules of the target into
GHCi as interpreted bytecode. In addition to ``cabal v2-build``'s flags,
it takes an additional ``--repl-options`` flag.
To avoid ``ghci`` specific flags from triggering unneeded global rebuilds these
flags are now stripped from the internal configuration. As a result
``--ghc-options`` will no longer (reliably) work to pass flags to ``ghci`` (or
other repls). Instead, you should use the new ``--repl-options`` flag to
specify these options to the invoked repl. (This flag also works on ``cabal
repl`` and ``Setup repl`` on sufficiently new versions of Cabal.)
Currently, it is not supported to pass multiple targets to ``v2-repl``
(``v2-repl`` will just successively open a separate GHCi session for
each target.)
It also provides a way to experiment with libraries without needing to download
them manually or to install them globally.
This command opens a REPL with the current default target loaded, and a version
of the ``vector`` package matching that specification exposed.
::
$ cabal v2-repl --build-depends "vector >= 0.12 && < 0.13"
Both of these commands do the same thing as the above, but only exposes ``base``,
``vector``, and the ``vector`` package's transitive dependencies even if the user
is in a project context.
::
$ cabal v2-repl --ignore-project --build-depends "vector >= 0.12 && < 0.13"
$ cabal v2-repl --project='' --build-depends "vector >= 0.12 && < 0.13"
This command would add ``vector``, but not (for example) ``primitive``, because
it only includes the packages specified on the command line (and ``base``, which
cannot be excluded for technical reasons).
::
$ cabal v2-repl --build-depends vector --no-transitive-deps
cabal v2-run
-------------
``cabal v2-run [TARGET [ARGS]]`` runs the executable specified by the
target, which can be a component, a package or can be left blank, as
long as it can uniquely identify an executable within the project.
Tests and benchmarks are also treated as executables.
See `the v2-build section <#cabal-new-build>`__ for the target syntax.
Except in the case of the empty target, the strings after it will be
passed to the executable as arguments.
If one of the arguments starts with ``-`` it will be interpreted as
a cabal flag, so if you need to pass flags to the executable you
have to separate them with ``--``.
::
$ cabal v2-run target -- -a -bcd --argument
'v2-run' also supports running script files that use a certain format. With
a script that looks like:
::
#!/usr/bin/env cabal
{- cabal:
build-depends: base ^>= 4.11
, shelly ^>= 1.8.1
-}
main :: IO ()
main = do
...
It can either be executed like any other script, using ``cabal`` as an
interpreter, or through this command:
::
$ cabal v2-run script.hs
$ cabal v2-run script.hs -- --arg1 # args are passed like this
cabal v2-freeze
----------------
``cabal v2-freeze`` writes out a **freeze file** which records all of
the versions and flags which that are picked by the solver under the
current index and flags. Default name of this file is
``cabal.project.freeze`` but in combination with a
``--project-file=my.project`` flag (see :ref:`project-file
<cmdoption-project-file>`)
the name will be ``my.project.freeze``.
A freeze file has the same syntax as ``cabal.project`` and looks
something like this:
.. highlight:: cabal
::
constraints: HTTP ==4000.3.3,
HTTP +warp-tests -warn-as-error -network23 +network-uri -mtl1 -conduit10,
QuickCheck ==2.9.1,
QuickCheck +templatehaskell,
-- etc...
For end-user executables, it is recommended that you distribute the
``cabal.project.freeze`` file in your source repository so that all
users see a consistent set of dependencies. For libraries, this is not
recommended: users often need to build against different versions of
libraries than what you developed against.
cabal v2-bench
---------------
``cabal v2-bench [TARGETS] [OPTIONS]`` runs the specified benchmarks
(all the benchmarks in the current package by default), first ensuring
they are up to date.
cabal v2-test
--------------
``cabal v2-test [TARGETS] [OPTIONS]`` runs the specified test suites
(all the test suites in the current package by default), first ensuring
they are up to date.
cabal v2-haddock
-----------------
``cabal v2-haddock [FLAGS] [TARGET]`` builds Haddock documentation for
the specified packages within the project.
If a target is not a library :cfg-field:`haddock-benchmarks`,
:cfg-field:`haddock-executables`, :cfg-field:`haddock-internal`,
:cfg-field:`haddock-tests` will be implied as necessary.
cabal v2-exec
---------------
``cabal v2-exec [FLAGS] [--] COMMAND [--] [ARGS]`` runs the specified command
using the project's environment. That is, passing the right flags to compiler
invocations and bringing the project's executables into scope.
cabal v2-install
-----------------
``cabal v2-install [FLAGS] PACKAGES`` builds the specified packages and
symlinks/copies their executables in ``installdir`` (usually ``~/.cabal/bin``).
For example this command will build the latest ``cabal-install`` and symlink
its ``cabal`` executable:
::
$ cabal v2-install cabal-install
In addition, it's possible to use ``cabal v2-install`` to install components
of a local project. For example, with an up-to-date Git clone of the Cabal
repository, this command will build cabal-install HEAD and symlink the
``cabal`` executable:
::
$ cabal v2-install exe:cabal
Where symlinking is not possible (eg. on some Windows versions) the ``copy``
method is used by default. You can specify the install method
by using ``--install-method`` flag:
::
$ cabal v2-install exe:cabal --install-method=copy --installdir=$HOME/bin
Note that copied executables are not self-contained, since they might use
data-files from the store.
It is also possible to "install" libraries using the ``--lib`` flag. For
example, this command will build the latest Cabal library and install it:
::
$ cabal v2-install --lib Cabal
This works by managing GHC environments. By default, it is writing to the
global environment in ``~/.ghc/$ARCH-$OS-$GHCVER/environments/default``.
``v2-install`` provides the ``--package-env`` flag to control which of
these environments is modified.
This command will modify the environment file in the current directory:
::
$ cabal v2-install --lib Cabal --package-env .
This command will modify the environment file in the ``~/foo`` directory:
::
$ cabal v2-install --lib Cabal --package-env foo/
Do note that the results of the previous two commands will be overwritten by
the use of other v2-style commands, so it is not recommended to use them inside
a project directory.
This command will modify the environment in the "local.env" file in the
current directory:
::
$ cabal v2-install --lib Cabal --package-env local.env
This command will modify the ``myenv`` named global environment:
::
$ cabal v2-install --lib Cabal --package-env myenv
If you wish to create a named environment file in the current directory where
the name does not contain an extension, you must reference it as ``./myenv``.
You can learn more about how to use these environments in `this section of the
GHC manual <https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/packages.html#package-environments>`_.
cabal v2-clean
---------------
``cabal v2-clean [FLAGS]`` cleans up the temporary files and build artifacts
stored in the ``dist-newstyle`` folder.
By default, it removes the entire folder, but it can also spare the configuration
and caches if the ``--save-config`` option is given, in which case it only removes
the build artefacts (``.hi``, ``.o`` along with any other temporary files generated
by the compiler, along with the build output).
cabal v2-sdist
---------------
``cabal v2-sdist [FLAGS] [TARGETS]`` takes the crucial files needed to build ``TARGETS``
and puts them into an archive format ready for upload to Hackage. These archives are stable
and two archives of the same format built from the same source will hash to the same value.
``cabal v2-sdist`` takes the following flags:
- ``-l``, ``--list-only``: Rather than creating an archive, lists files that would be included.
Output is to ``stdout`` by default. The file paths are relative to the project's root
directory.
- ``-o``, ``--output-dir``: Sets the output dir, if a non-default one is desired. The default is
``dist-newstyle/sdist/``. ``--output-dir -`` will send output to ``stdout``
unless multiple archives are being created.
- ``-z``, ``--null``: Only used with ``--list-only``. Separates filenames with a NUL
byte instead of newlines.
``v2-sdist`` is inherently incompatible with sdist hooks, not due to implementation but due
to fundamental core invariants (same source code should result in the same tarball, byte for
byte) that must be satisfied for it to function correctly in the larger v2-build ecosystem.
``autogen-modules`` is able to replace uses of the hooks to add generated modules, along with
the custom publishing of Haddock documentation to Hackage.
.. warning::
Packages that use Backpack will stop working if uploaded to
Hackage, due to `issue #6005 <https://github.com/haskell/cabal/issues/6005>`_.
While this is happening, we recommend not uploading these packages
to Hackage (and instead referencing the package directly
as a ``source-repository-package``).
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
......@@ -9,8 +9,12 @@ Welcome to the Cabal User Guide
intro
config-and-install
concepts-and-development
bugs-and-stability
nix-local-build-overview
nix-integration
cabal-commands
cabal-package
cabal-project
setup-commands
file-format-changelog
buildinfo-fields-reference
bugs-and-stability
nix-integration
This diff is collapsed.
Nix Integration
===============
.. note::
This functionality doesn't work with nix-style builds.
Nix-style builds are not related to Nix integration.
`Nix <http://nixos.org/nix/>`_ is a package manager popular with some Haskell developers due to its focus on reliability and reproducibility. ``cabal`` now has the ability to integrate with Nix for dependency management during local package development.
Enabling Nix Integration
......
Nix-style Local Builds
======================
.. _nix-style-builds
Nix-style local builds are a new build system implementation inspired by Nix.
The Nix-style local build system is commonly called "v2-build" for short
after the ``cabal v2-*`` family of commands that control it. However, those
......@@ -16,7 +18,7 @@ until such a point as it is completely removed from Cabal.
Nix-style local builds combine the best of non-sandboxed and sandboxed Cabal:
1. Like sandboxed Cabal today, we build sets of independent local
1. Like sandboxed Cabal previously, we build sets of independent local
packages deterministically and independent of any global state.
v2-build will never tell you that it can't build your package
because it would result in a "dangerous reinstall." Given a
......
This diff is collapsed.
This diff is collapsed.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment