Merge pull request #6951 from phadej/pr-6936

PR #6936

CONTRIBUTING.md

@@ -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)
 

Cabal/Distribution/PackageDescription/Check.hs

@@ -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 "

Cabal/doc/cabal-commands.rst

@@ -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:
 
 ::

Cabal/doc/cabal-package.rst

@@ -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.
 

Cabal/doc/developing-packages.rst

@@ -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.
 

Cabal/doc/installing-packages.rst

@@ -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

Cabal/doc/misc.rst

@@ -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

Cabal/doc/nix-local-build.rst

@@ -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
@@ -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.

Cabal/tests/ParserTests/regressions/multiple-libs-2.check

@@ -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'.