Commit 0205fd25 authored by Oleg Grenrus's avatar Oleg Grenrus Committed by GitHub

Merge pull request #6951 from phadej/pr-6936

PR #6936
parents 9d28c0c6 5a890bfc
......@@ -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)
......
......@@ -1361,7 +1361,7 @@ checkCabalVersion pkg =
-- * Checks on the GenericPackageDescription
-- ------------------------------------------------------------
-- | Check the build-depends fields for any weirdness or bad practise.
-- | Check the build-depends fields for any weirdness or bad practice.
--
checkPackageVersions :: GenericPackageDescription -> [PackageCheck]
checkPackageVersions pkg =
......@@ -1376,7 +1376,7 @@ checkPackageVersions pkg =
"The dependency 'build-depends: base' does not specify an upper "
++ "bound on the version number. Each major release of the 'base' "
++ "package changes the API in various ways and most packages will "
++ "need some changes to compile with it. The recommended practise "
++ "need some changes to compile with it. The recommended practice "
++ "is to specify an upper bound on the version of the 'base' "
++ "package. This ensures your package will continue to build when a "
++ "new major version of the 'base' package is released. If you are "
......
......@@ -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.
......@@ -1536,7 +1536,7 @@ system-dependent values for these fields.
In order to specify an intra-package dependency on an internal
library component you can use the unqualified name of the
component library component. Note that locally defined sub-library
library component. Note that locally defined sub-library
names shadow external package names of the same name. See section on
:ref:`Internal Libraries <sublibs>` for examples and more information.
......@@ -1556,7 +1556,7 @@ system-dependent values for these fields.
bar
Dependencies like ``foo >= 1.2.3 && < 1.3`` turn out to be very
common because it is recommended practise for package versions to
common because it is recommended practice for package versions to
correspond to API versions (see PVP_).
Since Cabal 1.6, there is a special wildcard syntax to help with
......@@ -1637,7 +1637,7 @@ system-dependent values for these fields.
.. Note::
One might expected the desugaring to truncate all version
One might expect the desugaring to truncate all version
components below (and including) the patch-level, i.e.
``^>= x.y.z.u`` == ``>= x.y.z && < x.(y+1)``,
as the major and minor version components alone are supposed to
......@@ -2262,7 +2262,7 @@ Example: A package containing a library and executable programs
Flag NewDirectory
description: Whether to build against @directory >= 1.2@
-- This is an automatic flag which the solver will be
-- This is an automatic flag which the solver will
-- assign automatically while searching for a solution
Library
......@@ -2530,8 +2530,8 @@ Meaning of field values when using conditionals
During the configuration phase, a flag assignment is chosen, all
conditionals are evaluated, and the package description is combined into
a flat package descriptions. If the same field both inside a conditional
and outside then they are combined using the following rules.
a flat package descriptions. If the same field is declared both inside
a conditional and outside then they are combined using the following rules.
- Boolean fields are combined using conjunction (logical "and").
......@@ -2621,7 +2621,7 @@ Source Repositories
:since: 1.6
It is often useful to be able to specify a source revision control
repository for a package. Cabal lets you specifying this information in
repository for a package. Cabal lets you specify this information in
a relatively structured form which enables other tools to interpret and
make effective use of the information. For example the information
should be sufficient for an automatic tool to checkout the sources.
......@@ -2704,7 +2704,7 @@ The exact fields are as follows:
Many source control systems support the notion of a branch, as a
distinct concept from having repositories in separate locations. For
example CVS, SVN and git use branches while for darcs uses different
example CVS, SVN and git use branches while darcs uses different
locations for different branches. If you need to specify a branch to
identify a your repository then specify it in this field.
......@@ -2727,7 +2727,7 @@ The exact fields are as follows:
package, i.e. the directory containing the package's ``.cabal``
file.
This field is optional. It default to empty which corresponds to the
This field is optional. It defaults to empty which corresponds to the
root directory of the repository.
Downloading a package's source
......@@ -2765,7 +2765,7 @@ Custom setup scripts
Since Cabal 1.24, custom ``Setup.hs`` are required to accurately track
their dependencies by declaring them in the ``.cabal`` file rather than
rely on dependencies being implicitly in scope. Please refer
rely on dependencies being implicitly in scope. Please refer to
`this article <https://www.well-typed.com/blog/2015/07/cabal-setup-deps/>`__
for more details.
......@@ -2889,7 +2889,7 @@ really on the package when distributed. This makes commands like sdist fail
because the file is not found.
These special modules must appear again on the :pkg-field:`autogen-modules`
field of the stanza that is using it, besides :pkg-field:`other-modules` or
field of the stanza that is using them, besides :pkg-field:`other-modules` or
:pkg-field:`library:exposed-modules`. With this there is no need to create
complex build hooks for this poweruser case.
......
......@@ -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
......
......@@ -60,7 +60,7 @@ will be no incompatible API changes. But minor versions increments, for
example 1.2.3, indicate compatible API additions.
The Package Versioning Policy does not require any API guarantees
between major releases, for example between 1.2.x and 1.4.x. In practise
between major releases, for example between 1.2.x and 1.4.x. In practice
of course not everything changes between major releases. Some parts of
the API are more prone to change than others. The rest of this section
gives some informal advice on what level of API stability you can expect
......
......@@ -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 :cfg-field:`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.
......@@ -262,7 +262,3 @@ 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.
......@@ -3,4 +3,4 @@ No 'category' field.
No 'maintainer' field.
No 'description' field.
The 'license' field is missing or is NONE.
The dependency 'build-depends: base' does not specify an upper bound on the version number. Each major release of the 'base' package changes the API in various ways and most packages will need some changes to compile with it. The recommended practise is to specify an upper bound on the version of the 'base' package. This ensures your package will continue to build when a new major version of the 'base' package is released. If you are not sure what upper bound to use then use the next major version. For example if you have tested your package with 'base' version 4.5 and 4.6 then use 'build-depends: base >= 4.5 && < 4.7'.
The dependency 'build-depends: base' does not specify an upper bound on the version number. Each major release of the 'base' package changes the API in various ways and most packages will need some changes to compile with it. The recommended practice is to specify an upper bound on the version of the 'base' package. This ensures your package will continue to build when a new major version of the 'base' package is released. If you are not sure what upper bound to use then use the next major version. For example if you have tested your package with 'base' version 4.5 and 4.6 then use 'build-depends: base >= 4.5 && < 4.7'.
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