diff --git a/doc/cabal-package-description-file.rst b/doc/cabal-package-description-file.rst index 6ae467b4774..5eeedaec0fc 100644 --- a/doc/cabal-package-description-file.rst +++ b/doc/cabal-package-description-file.rst @@ -2693,87 +2693,137 @@ Starting with Cabal-2.2 it's possible to use common build info stanzas. *Source code* repository marker ------------------------------- -.. pkg-section:: source-repository +.. pkg-section:: source-repository notation-variant :since: 1.6 -A marker that points to the *source code* for this package within a -**source code repository**. +A metadata marker that helps users of your package find its source code. +This marker points to a *source code* snapshot within a +version control systems (VCS) **repository** like Git. -There are two kinds. You can specify one or the other or both at once: +Here are some examples that point to snapshots of the Cabal library in +its Git repository: -- 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. +:: -As an example, here are the repositories for the Cabal library. Note that the -``this`` kind of repository specifies a tag. + -- Snapshot via Git commit hash + source-repository this + type: git + location: https://github.com/haskell/cabal + tag: 260ecdc3d848782d4df49e629cb0a5dc9e96ca9e -:: + -- Snapshot via Git tag + source-repository this + type: git + location: https://github.com/haskell/cabal + tag: cabal-install-v3.12.1.0 + -- Snapshot via latest commit (head) of the default (master) branch source-repository head type: git location: https://github.com/haskell/cabal - source-repository this + -- Snapshot via latest commit (head) of the specified branch + source-repository head type: git location: https://github.com/haskell/cabal - tag: 1.6.1 + branch: 3.12 + + -- Snapshot via latest commit (head) in subdirectory of a monorepo + source-repository head + type: git + location: https://github.com/haskell/vector.git + subdir: vector + +Note the two notation variants ``this`` and ``head``: + +- The ``this`` variants refers to a specific snapshot of a repository + that contains the sources for this version or release of your package. + For most source control systems this involves specifying a tag, id or + hash of some commit and perhaps a branch. + +- The ``head`` variant refers to the latest source code snapshot + in a repository branch of your 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 :ref:`cabal get` command uses the kind of repository with its ``--source-repository`` option, if provided. .. _source-repository-fields: -The :ref:`VCS fields` of ``source-repository`` are: - -.. - data SourceRepo = SourceRepo - { repoKind :: RepoKind - , repoType :: Maybe RepoType - , repoLocation :: Maybe String - , repoModule :: Maybe String - , repoBranch :: Maybe String - , repoTag :: Maybe String - , repoSubdir :: Maybe FilePath - } +The fields of ``source-repository`` are: -.. pkg-field:: type: VCS kind +.. pkg-field:: type: VCS tool - This field is required. + :required: always -.. pkg-field:: location: VCS location + The name of the source control system tool used for a repository. + Cabal supports the following common version control systems (VCS): - This field is required. + - ``git`` + - ``darcs`` + - ``svn`` + - ``cvs`` + - ``mercurial`` (or alias ``hg``) + - ``bazaar`` (or alias ``bzr``) + - ``arch`` + - ``monotone`` + - ``pijul`` -.. pkg-field:: module: token + The chosen VCS type determines what other fields are + appropriate to specify for a particular version control system. - CVS requires a named module, as each CVS server can host multiple - named repositories. +.. pkg-field:: location: VCS location - This field is required for the CVS repository type and should not be - used otherwise. + :required: always + + The location of the repository, usually a URL but the exact form of this field + depends on the repository type. For example: + + - Git: ``https://github.com/foo/bar.git`` + - Darcs: ``http://code.haskell.org/foo/`` + - CVS: ``anoncvs@cvs.foo.org:/cvs`` .. pkg-field:: branch: VCS branch This field is optional. + 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:: tag: VCS tag - This field is required for the ``this`` repository kind. + :required: only for the ``this`` notation variant - This might be used to indicate what sources to get if someone needs to fix a + A tag identifies a particular snapshot of a source repository. + The exact form of the tag depends on the repository type. When using Git + this is typically a commit hash or a Git tag. + This field 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. .. pkg-field:: subdir: VCS subdirectory This field is optional but, if given, specifies a single subdirectory. + Otherwise it corresponds to the root directory of the repository and is the same as + specifying ``.`` explicitly. + Some projects are structured as a "monorepo" and put the sources for multiple + packages inside a single repository. + This field lets you specify the relative path from the root of the + repository to the top directory for the package, i.e. to the directory containing + the package's ``.cabal`` file. + +.. pkg-field:: module: CVS token + + :required: if repository type is CVS + + CVS requires a named module, as each CVS server can host multiple + named repositories. + + This field is required for the CVS repository type and should not be + used otherwise. .. _setup-hooks: diff --git a/doc/cabal-project-description-file.rst b/doc/cabal-project-description-file.rst index f024e540010..17c4dd727a5 100644 --- a/doc/cabal-project-description-file.rst +++ b/doc/cabal-project-description-file.rst @@ -216,35 +216,48 @@ Formally, the format is described by the following BNF: 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 -consider during package retrieval. This allows use of a package from a -remote version control system, rather than looking for that package in -Hackage. +Since version 2.4, the ``source-repository-package`` stanza allows you +to specify packages in a remote version control system (VCS) that Cabal should +consider during package retrieval. This allows you to use +a specific package snapshot as a dependency, e.g. one with the latest fix that may not +yet be published on Hackage, or a package that may not exist on Hackage at all +for intellectual property reasons in business settings. 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 their use just like Hackage +packages). It gathers the names of the packages from the appropriate ``.cabal`` +file in the repository, and allows their use just like Hackage or locally defined packages. There is no command line variant of this stanza. +Here are some examples from a ``cabal.project`` file +that point to snapshots of different libraries in Git repositories: + .. code-block:: cabal packages: . + -- Snapshot via Git commit hash source-repository-package type: git location: https://github.com/hvr/HsYAML.git tag: e70cf0c171c9a586b62b3f75d72f1591e4e6aaa1 + -- Snapshot via Git tag + source-repository-package + type: git + location: https://github.com/haskell/cabal + tag: cabal-install-v3.12.1.0 + + -- Snapshot via Git commit hash in subdirectory of a monorepo source-repository-package type: git location: https://github.com/well-typed/cborg tag: 3d274c14ca3077c3a081ba7ad57c5182da65c8c1 subdir: cborg + -- Snapshot via Git commit hash with post-checkout command source-repository-package type: git location: https://github.com/haskell/network.git @@ -253,33 +266,61 @@ There is no command line variant of this stanza. .. _source-repository-package-fields: -The :ref:`VCS fields` of ``source-repository-package`` are: +The fields of ``source-repository-package`` are: + +.. _source-repository-package-type: + +.. cfg-field:: type: VCS tool -.. - data SourceRepositoryPackage f = SourceRepositoryPackage - { srpType :: !RepoType - , srpLocation :: !String - , srpTag :: !(Maybe String) - , srpBranch :: !(Maybe String) - , srpSubdir :: !(f FilePath) - , srpCommand :: ![String] - } + :required: always -.. cfg-field:: type: VCS kind + The name of the source control system tool used for a repository. + Cabal supports the following common version control systems (VCS): - This field is required. + - ``git`` + - ``darcs`` + - ``svn`` + - ``cvs`` + - ``mercurial`` (or alias ``hg``) + - ``bazaar`` (or alias ``bzr``) + - ``arch`` + - ``monotone`` + - ``pijul`` + + The chosen VCS type determines what other fields are + appropriate to specify for a particular version control system. .. cfg-field:: location: VCS location - This field is required. + :required: always + + The location of the repository, usually a URL but the exact form of this field + depends on the repository type. For example: + + - Git: ``https://github.com/foo/bar.git`` + - Darcs: ``http://code.haskell.org/foo/`` + - CVS: ``anoncvs@cvs.foo.org:/cvs`` .. cfg-field:: branch: VCS branch This field is optional. + 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. .. cfg-field:: tag: VCS tag - This field is optional. + This field is optional but, if given, specifies a single subdirectory. + Otherwise it corresponds to the root directory of the repository and is the same as + specifying ``.`` explicitly. + + Some projects are structured as a "monorepo" and put the sources for multiple + packages inside a single repository. + This field lets you specify the relative path from the root of the + repository to the top directory for the package, i.e. to the directory containing + the package's ``.cabal`` file. .. cfg-field:: subdir: VCS subdirectory list diff --git a/doc/how-to-source-packages.rst b/doc/how-to-source-packages.rst index caecf7e90ac..e9442704b08 100644 --- a/doc/how-to-source-packages.rst +++ b/doc/how-to-source-packages.rst @@ -53,8 +53,9 @@ for a package, both for :ref:`package authors` and maintainers and for :ref:`package consumers`. A relatively structured set of version control system (VCS) fields, that vary -depending on the :ref:`VCS kind`, enables Cabal commands and other -tools to interpret and make effective use of this information. +depending on the :ref:`VCS tool`, +enables Cabal commands and other tools to interpret and make effective use of +this information. ``source-repository`` Says where to find the source for a package and is a metadata field of a @@ -199,8 +200,8 @@ Setting up a *source code* dependency ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ It is easy to copy the fields of ``source-repository`` to set up a -``source-repository-package`` as they share many of the same :ref:`VCS -fields`. Looking at vector's `package description +``source-repository-package`` as they share many of the same +fields. Looking at vector's `package description `_ on Hackage we see the ``source-repository`` stanza: .. code-block:: cabal diff --git a/doc/index.rst b/doc/index.rst index 0b5407e8580..0791253d8e9 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -27,7 +27,6 @@ Welcome to the Cabal User Guide cabal-package-description-file cabal-project-description-file - version-control-fields cabal-config-and-commands external-commands setup-commands diff --git a/doc/version-control-fields.rst b/doc/version-control-fields.rst deleted file mode 100644 index 739905d4b8a..00000000000 --- a/doc/version-control-fields.rst +++ /dev/null @@ -1,95 +0,0 @@ -Version Control System Fields -============================= - -.. _vcs-fields: - -Most of the version control system (VCS) fields types are common to both -``source-repository`` and ``source-repository-package`` stanzas. - -.. list-table:: - :header-rows: 1 - :widths: 30 30 40 - - * - Field Name - - source-repository (head|this) - - source-repository-package - * - type - - [x] - - [x] - * - location - - [x] - - [x] - * - branch - - [x] - - [x] - * - tag - - [x] - - [x] - * - subdir - - [x] (0 or 1) - - [x] (0 or 1 for each dependency) - * - module (CVS only) - - [x] - - [_] - * - post-checkout-command - - [_] - - [x] - -.. _vcs-kind: - -VCS kind -^^^^^^^^ - -Cabal supports specifying different information for various common source -control systems. This is the name of the source control system used for a -repository. The currently recognised types are: - -- ``darcs`` -- ``git`` -- ``svn`` -- ``cvs`` -- ``mercurial`` (or alias ``hg``) -- ``bazaar`` (or alias ``bzr``) -- ``arch`` -- ``monotone`` -- ``pijul`` - -The VCS kind will determine what other fields are appropriate to specify for a -particular version control system. - -VCS location -^^^^^^^^^^^^ - -The location of the repository, usually a URL but the exact form of this field -depends on the repository type. For example: - -- for Darcs: ``http://code.haskell.org/foo/`` -- for Git: ``https://github.com/foo/bar.git`` -- for CVS: ``anoncvs@cvs.foo.org:/cvs`` - -VCS branch -^^^^^^^^^^ - -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. - -VCS tag -^^^^^^^ - -A tag identifies a particular state of a source repository. The exact form of -the tag depends on the repository type. - -VCS subdirectory -^^^^^^^^^^^^^^^^ - -A field of this type is always optional because it defaults to empty, which -corresponds to the root directory of the repository and is the same as -specifying ``.`` explicitly. - -Some projects put the sources for multiple packages inside a single VCS -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.