Merge pull request #9701 from cabalism/doc/compare-source-repos-9665

source-repository versus source-repository-package

Author: mergify[bot]

doc/cabal-commands.rst

@@ -457,6 +457,8 @@ e.g. you plan to work on a project with unreliable or no internet access.
 
 Check ``cabal fetch --help`` for a complete list of options.
 
+.. _cabal-get:
+
 cabal get
 ^^^^^^^^^
 
@@ -1399,6 +1401,7 @@ A list of all warnings with their constructor:
 - ``no-docs``: missing expected documentation files (changelog).
 - ``doc-place``: documentation files listed in ``extra-source-files`` instead of ``extra-doc-files``.
 
+.. _cabal-sdist:
 
 cabal sdist
 ^^^^^^^^^^^

doc/cabal-package-description-file.rst

@@ -2676,43 +2676,32 @@ Starting with Cabal-2.2 it's possible to use common build info stanzas.
 
     TBW
 
-Source Repositories
-^^^^^^^^^^^^^^^^^^^
+
+.. _pkg-author-source:
+
+*Source code* repository marker
+-------------------------------
 
 .. pkg-section:: source-repository
     :since: 1.6
 
-It is often useful to be able to specify a source revision control
-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.
-
-Cabal supports specifying different information for various common
-source control systems. Obviously not all automated tools will support
-all source control systems.
+A marker that points to the *source code* for this package within a
+**source code repository**.
 
-Cabal supports specifying repositories for different use cases. By
-declaring which case we mean automated tools can be more useful. There
-are currently two kinds defined:
+There are two kinds. You can specify one or the other or both at once:
 
 -  The ``head`` kind refers to the latest development branch of the
    package. This may be used for example to track activity of a project
    or as an indication to outside developers what sources to get for
    making new contributions.
 
 -  The ``this`` kind refers to the branch and tag of a repository that
-   contains the sources for this version or release of a package. For
-   most source control systems this involves specifying a tag, id or
-   hash of some form and perhaps a branch. The purpose is to be able to
-   reconstruct the sources corresponding to a particular package
-   version. This might be used to indicate what sources to get if
-   someone needs to fix a bug in an older branch that is no longer an
-   active head branch.
-
-You can specify one kind or the other or both. As an example here are
-the repositories for the Cabal library. Note that the ``this`` kind of
-repository specifies a tag.
+   contains the sources for this version or release of a package.  For most
+   source control systems this involves specifying a tag, id or hash of some
+   form and perhaps a branch.
+
+As an example, here are the repositories for the Cabal library. Note that the
+``this`` kind of repository specifies a tag.
 
 ::
 
@@ -2725,32 +2714,29 @@ repository specifies a tag.
       location: https://github.com/haskell/cabal
       tag:      1.6.1
 
-The exact fields are as follows:
-
-.. pkg-field:: type: token
+The :ref:`cabal get<cabal-get>` command uses the kind of repository with
+its ``--source-repository`` option, if provided.
 
-    The name of the source control system used for this repository. The
-    currently recognised types are:
+.. _source-repository-fields:
 
-    -  ``darcs``
-    -  ``git``
-    -  ``svn``
-    -  ``cvs``
-    -  ``mercurial`` (or alias ``hg``)
-    -  ``bazaar`` (or alias ``bzr``)
-    -  ``arch``
-    -  ``monotone``
+The :ref:`VCS fields<vcs-fields>` of ``source-repository`` are:
 
-    This field is required.
+..
+  data SourceRepo = SourceRepo
+    { repoKind :: RepoKind
+    , repoType :: Maybe RepoType
+    , repoLocation :: Maybe String
+    , repoModule :: Maybe String
+    , repoBranch :: Maybe String
+    , repoTag :: Maybe String
+    , repoSubdir :: Maybe FilePath
+    }
 
-.. pkg-field:: location: URL
+.. pkg-field:: type: VCS kind
 
-    The location of the repository. The exact form of this field depends
-    on the repository type. For example:
+    This field is required.
 
-    -  for darcs: ``http://code.haskell.org/foo/``
-    -  for git: ``git://github.com/foo/bar.git``
-    -  for CVS: ``[email protected]:/cvs``
+.. pkg-field:: location: VCS location
 
     This field is required.
 
@@ -2762,35 +2748,20 @@ The exact fields are as follows:
     This field is required for the CVS repository type and should not be
     used otherwise.
 
-.. pkg-field:: branch: token
-
-    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 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.
+.. pkg-field:: branch: VCS branch
 
     This field is optional.
 
-.. pkg-field:: tag: token
-
-    A tag identifies a particular state of a source repository. The tag
-    can be used with a ``this`` repository kind to identify the state of
-    a repository corresponding to a particular package version or
-    release. The exact form of the tag depends on the repository type.
+.. pkg-field:: tag: VCS tag
 
     This field is required for the ``this`` repository kind.
 
-.. pkg-field:: subdir: directory
+    This might be used to indicate what sources to get if someone needs to fix a
+    bug in an older branch that is no longer an active head branch.
 
-    Some projects put the sources for multiple packages under a single
-    source repository. This field lets you specify the relative path
-    from the root of the repository to the top directory for the
-    package, i.e. the directory containing the package's ``.cabal``
-    file.
+.. pkg-field:: subdir: VCS subdirectory
 
-    This field is optional. It defaults to empty which corresponds to the
-    root directory of the repository.
+    This field is optional but, if given, specifies a single subdirectory.
 
 
 .. _setup-hooks:

doc/cabal-project-description-file.rst

@@ -205,8 +205,10 @@ Formally, the format is described by the following BNF:
                 | "{" Glob "," ... "," Glob "}" # union (match any of these)
 
 
-Specifying Packages from Remote Version Control Locations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. _pkg-consume-source:
+
+Taking a dependency from a *source code* repository
+---------------------------------------------------
 
 Since version 2.4, the ``source-repository-package`` stanza allows for
 specifying packages in a remote version control system that cabal should
@@ -238,18 +240,43 @@ Hackage.
 Since version 3.4, cabal-install creates tarballs for each package coming
 from a ``source-repository-package`` stanza (effectively applying cabal
 sdists to such packages). It gathers the names of the packages from the
-appropriate .cabal file in the version control repository, and allows
+appropriate ``.cabal`` file in the version control repository, and allows
 their use just like Hackage or locally defined packages.
 
+.. _source-repository-package-fields:
+
+The :ref:`VCS fields<vcs-fields>` of ``source-repository-package`` are:
+
+..
+  data SourceRepositoryPackage f = SourceRepositoryPackage
+    { srpType :: !RepoType
+    , srpLocation :: !String
+    , srpTag :: !(Maybe String)
+    , srpBranch :: !(Maybe String)
+    , srpSubdir :: !(f FilePath)
+    , srpCommand :: ![String]
+    }
+
 .. cfg-field:: type: VCS kind
 
-.. cfg-field:: location: VCS location (usually URL)
+    This field is required.
+
+.. cfg-field:: location: VCS location
+
+    This field is required.
+
+.. cfg-field:: branch: VCS branch
+
+    This field is optional.
 
 .. cfg-field:: tag: VCS tag
 
-.. cfg-field:: subdir: subdirectory list
+    This field is optional.
+
+.. cfg-field:: subdir: VCS subdirectory list
 
-    Look in one or more subdirectories of the repository for cabal files, rather than the root.
+    Look in one or more subdirectories of the repository for cabal files, rather
+    than the root. This field is optional.
 
 .. cfg-field:: post-checkout-command: command