Commit ff9555f8 authored by Jan Hrček's avatar Jan Hrček Committed by Oleg Grenrus

Various docs improvements

parent 9d28c0c6
......@@ -4,12 +4,12 @@ Building Cabal for hacking
--------------------------
The current recommended way of developing Cabal is to use the
`new-build` feature which [shipped in cabal-install-1.24](http://blog.ezyang.com/2016/05/announcing-cabal-new-build-nix-style-local-builds/). Assuming
`v2-build` feature which [shipped in cabal-install-1.24](http://blog.ezyang.com/2016/05/announcing-cabal-new-build-nix-style-local-builds/). Assuming
that you have a sufficiently recent cabal-install (see above),
it is sufficient to run:
~~~~
cabal new-build cabal
cabal v2-build cabal
~~~~
To build a local, development copy of cabal-install. The location
......@@ -21,9 +21,9 @@ to find the binary (or just run `find -type f -executable -name cabal`).
Here are some other useful variations on the commands:
~~~~
cabal new-build Cabal # build library only
cabal new-build Cabal:unit-tests # build Cabal's unit test suite
cabal new-build cabal-tests # etc...
cabal v2-build Cabal # build library only
cabal v2-build Cabal:unit-tests # build Cabal's unit test suite
cabal v2-build cabal-tests # etc...
~~~~
**Dogfooding HEAD.**
......@@ -45,7 +45,7 @@ and `~/cabal-dev`, and you have a release copy of cabal installed at
~~~~
cd ~/cabal-prod
/opt/cabal/2.4/bin/cabal new-build cabal
/opt/cabal/2.4/bin/cabal v2-build cabal
~~~~
This will produce a cabal binary (see also: [Where are my build products?](http://cabal.readthedocs.io/en/latest/nix-local-build.html#where-are-my-build-products)
......@@ -54,7 +54,7 @@ and then use it to build your development copy:
~~~~
cd ~/cabal-dev
cabal new-build cabal
cabal v2-build cabal
~~~~
Running tests
......@@ -112,7 +112,7 @@ If none of these let you reproduce, there might be some race condition
or continuous integration breakage; please file a bug.
**Running tests locally.**
To run tests locally with `new-build`, you will need to know the
To run tests locally with `v2-build`, you will need to know the
name of the test suite you want. Cabal and cabal-install have
several. Also, you'll want to read [Where are my build products?](http://cabal.readthedocs.io/en/latest/nix-local-build.html#where-are-my-build-products)
......
......@@ -9,8 +9,8 @@ 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
``cabal v2-configure FLAGS; cabal v2-build`` is roughly equivalent to
``cabal v2-build FLAGS``, except that with ``v2-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
......@@ -178,7 +178,7 @@ 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.
See `the v2-build section <#cabal-v2-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.
......@@ -191,7 +191,7 @@ 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
``v2-run`` also supports running script files that use a certain format. With
a script that looks like:
::
......@@ -218,7 +218,7 @@ 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
the versions and flags 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
......@@ -336,7 +336,7 @@ 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
This command will modify the environment in the ``local.env`` file in the
current directory:
::
......
......@@ -208,7 +208,7 @@ don't follow this rule.
In the package description file, lines whose first non-whitespace
characters are "``--``" are treated as comments and ignored.
This file should contain of a number global property descriptions and
This file should contain a number global property descriptions and
several sections.
- The `package properties`_ describe the package
......@@ -338,8 +338,8 @@ describe the package as a whole:
The version of the Cabal specification that this package
description uses. The Cabal specification does slowly evolve (see
also :ref:`spec-history`), introducing new features and
occasionally changing the meaning of existing features. By
specifying which version of the specification you are using it
occasionally changing the meaning of existing features.
Specifying which version of the specification you are using
enables programs which process the package description to know
what syntax to expect and what each part means.
......@@ -732,7 +732,7 @@ Library
the :pkg-section:`library` section must be omitted.
Starting with Cabal 2.0, private internal sub-library components
can be defined by using setting the ``name`` field to a name
can be defined by setting the ``name`` field to a name
different from the current package's name; see section on
:ref:`Internal Libraries <sublibs>` for more information.
......@@ -773,7 +773,7 @@ The library section should contain the following fields:
.. pkg-field:: visibility: visibility specifiers
:since 3.0
:since: 3.0
:default: ``private`` for internal libraries. Cannot be set for public library.
......
......@@ -4,7 +4,7 @@ Quickstart
.. TIP::
If this is your first time using `cabal` you should check out the `Getting Started guide <getting-started.html>`__.
Lets assume we have created a project directory and already have a
Let's assume we have created a project directory and already have a
Haskell module or two.
Every project needs a name, we'll call this example "proglet".
......@@ -80,7 +80,7 @@ and ``Setup.hs`` files, and depending on your choice of license, a
You may want to edit the .cabal file and add a Description field.
As this stage the ``proglet.cabal`` is not quite complete and before you
At this stage the ``proglet.cabal`` is not quite complete and before you
are able to build the package you will need to edit the file and add
some build information about the library or executable.
......@@ -367,7 +367,7 @@ Unit of distribution
The Cabal package is the unit of distribution. What this means is that
each Cabal package can be distributed on its own in source or binary
form. Of course there may dependencies between packages, but there is
form. Of course there may be dependencies between packages, but there is
usually a degree of flexibility in which versions of packages can work
together so distributing them independently makes sense.
......
......@@ -177,7 +177,7 @@ The part of the path will be used to determine the cache key part.
.. note::
``cabal-install`` creates a ``.cache`` file, and will aggressively use
it contents if it exists. Therefore if you change the contents of
its contents if it exists. Therefore if you change the contents of
the directory, remember to wipe the cache too.
.. note::
......@@ -200,7 +200,7 @@ This is just syntactic sugar for
::
repository hackage.haskell.org
url: hackage.haskell.org:http://hackage.haskell.org/packages/archive
url: http://hackage.haskell.org/packages/archive
although, in (and only in) the specific case of Hackage, the URL
``http://hackage.haskell.org/packages/archive`` will be silently
......
......@@ -118,9 +118,9 @@ across projects. To be more precise:
1. A **local package** is one that is listed explicitly in the
``packages``, ``optional-packages`` or ``extra-packages`` field of a
project. Usually, these refer to packages whose source code lives
directly in a folder in your project (although, you can list an
arbitrary Hackage package in ``extra-packages`` to force it to be
treated as local).
directly in a folder in your project. But you can list an
arbitrary Hackage package in `extra-packages <cabal-project.html#cfg-field-extra-packages>`
to force it to be treated as local.
Local packages, as well as the external packages (below) which depend on
them, are built **inplace**, meaning that they are always built
......@@ -134,8 +134,8 @@ suitable for packages which you want to edit and recompile.
When an external package does not depend on an inplace package, it can
be built and installed to a **global** store, which can be shared across
projects. These build products are identified by a hash that over all of
the inputs which would influence the compilation of a package (flags,
projects. These build products are identified by a hash based on all of
the inputs which influence the compilation of a package (flags,
dependency selection, etc.). Just as in Nix, these hashes uniquely
identify the result of a build; if we compute this identifier and we
find that we already have this ID built, we can just use the already
......@@ -191,7 +191,7 @@ version of cabal-install:
``dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/c/pexe/build/pexe/pexe``
(you can see why we want this to be an implementation detail!)
- In cabal-install-2.2 and above, the ``/c/`` part of the above path
- In cabal-install-2.2 and above, the ``/c/`` part of the above path
is replaced with one of ``/l/``, ``/x/``, ``/f/``, ``/t/``, or
``/b/``, depending on the type of component (sublibrary,
executable, foreign library, test suite, or benchmark
......@@ -211,7 +211,7 @@ build products like executables.
Caching
-------
Nix-style local builds sport a robust caching system which help reduce
Nix-style local builds sport a robust caching system which helps to reduce
the time it takes to execute a rebuild cycle. While the details of how
``cabal-install`` does caching are an implementation detail and may
change in the future, knowing what gets cached is helpful for
......@@ -235,10 +235,10 @@ this folder (the most important two are first):
a local package are unchanged, ``cabal v2-build`` will skip
invoking ``setup build`` entirely (saving us from a possibly
expensive call to ``ghc --make``). The full list of source files
participating in compilation are determined using
``setup sdist --list-sources`` (thus, if you do not list all your
source files in a Cabal file, you may fail to recompile when you
edit them.)
participating in compilation is determined using
``cabal sdist --list-only``. Thus if you do not list all your
source files in a Cabal file, Cabal may fail to recompile when you
edit them.
``config`` (same format as ``cabal.project``)
The full project configuration, merged from ``cabal.project`` (and
friends) as well as the command line arguments.
......@@ -261,8 +261,4 @@ this folder (the most important two are first):
Note that every package also has a local cache managed by the Cabal
build system, e.g., in ``$distdir/cache``.
There is another useful file in ``dist-newstyle/cache``,
``plan.json``, which is a JSON serialization of the computed install
plan and is intended for integrating with external tooling.
build system, e.g., in ``$distdir/cache``.
\ No newline at end of file
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