Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Bases:
* https://downloads.haskell.org/~ghc/6.10.1/docs/html/users_guide/release-6-10-1.html
* https://hackage.haskell.org/package/Cabal-2.0.0.2/changelog
* https://github.com/haskell/cabal/commit/e1c39fc9ff4bf4eb8e956e2ee77da95d6cc73bbe

`--use-unicode` is added to `cabal haddock` and `cabal haddock-project`.
One cannot simply use `--haddock-option="--use-unicode"` because it
makes haddock to fail when building indexes.

New options for cabal.project and ./Setup interface:

* `profiling-shared`: Enable building profiling dynamic way
* Passing `--enable-profiling` and `--enable-executable-dynamic` builds
  profiled dynamic executables.

Support for using `profiling-shared` is guarded behind a constraint
which ensures you are using `Cabal >= 3.13`.

In the cabal file:

* `ghc-prof-shared-options`, for passing options when building in
  profiling dynamic way

Other miscellenious fixes and improvements

* Some refactoring around ways so that which
  ways we should build for a library, foreign library and executable is
  computed by the `buildWays` function (rather than ad-hoc in three
  different places).

* Improved logic for detecting whether a compiler supports compiling
  a specific way. See functions `profilingVanillaSupported`,
  `dynamicSupported`, `profilingDynamicSupported` etc
  These functions report accurate infomation after ghc-9.10.1.

* Fixed logic for determining whether to build shared libraries. (see
  #10050)
  Now, if you explicitly enable `--*-shared`, then that will always take
  effect. If it's not specified then `--enable-executable-dynamic` will
  turn on shared libraries IF `--enable-profiling` is not enabled.

* Remove assumption that dynamically linked compilers can build dynamic
  libraries (they might be cross compilers.

* Query the build compiler to determine which library way is necessary
  to be built for TH support to work.
  (rather than assume all compilers are dynamically linked)

* An extensive test which checks how options for `./Setup` and
  `cabal-install` are translated into build ways.

Fixes #4816, #10049, #10050

Issue #10063 points out that cabal exits before the external command
has finished executing. This was a simple oversight to not
waitForProcess on the result of calling createProcess.

This also points out the flaw that there isn't a way for external
commands to signal failure, so we now also propagate the exit code from
the external process.

Fixes #10063

We no longer define the `__HADDOCK_VERSION__` macro when invoking GHC
through Haddock, since doing so essentially guarantees recompilation
during documentation generation.

We audited all uses of `__HADDOCK_VERSION__` in hackage, ensuring there
was a reasonable path forward to migrate away from using
`__HADDOCK_VERSION__` for each, while generating the same documentation
as it did before.

If you are a user of `__HADDOCK_VERSION__`, please take a look at the
discussion in https://github.com/haskell/cabal/pull/9177 and reach out
to us if your use case is not covered.

Reverts the version-cpp flag introduced in the previous commit to avoid
a workaround. Instead, we get rid of the problem (`__HADDOCK_VERSION__`) at its root.

See the discussion in #9177

Haddock no longer writes compilation files by default, so we do not need to pass
tmp dirs for `-hidir`, `-stubdir`, and `-odir` via `--optghc`. Indeed, we do not
*want* to do so, since it results in recompilation for every invocation of
Haddock via Cabal. This commit stops this from happening for haddock versions >=
2.28 (when Hi Haddock was introduced).

This commit also stops the default definition of the `__HADDOCK_VERSION__` macro
when invoking GHC through haddock. Since a very limited set of users may still
depend on this macro, we introduce the `--haddock-version-cpp` flag and
`haddock-version-cpp:` cabal.project field, which enable the definition of
the `__HADDOCK_VERSION__` macro when invoking GHC through Haddock. This will
almost guarantee recompilation during documentation generation due to the macro
definition.

This commit also renames the `--haddock-lib` flag to `--haddock-resources-dir`
(and `haddock-lib:` cabal.project field to `haddock-resources-dir:`), and adds
this flag to the users guide since it was missing an entry. This also allows us
to add this field to `cabal-install:test:integration-tests2`, since it is no
longer ambiguous with the `--lib` flag.

This commit also causes `documentation: true` or `--enable-documentation` to
imply `-haddock` for GHC.

Also, since Haddock >= 2.29 is renaming `--lib` to `--resources-dir`, this
commit switches the flag provided to Haddock using a backwards compatible
condition based on the Haddock version.

Adds a changelog entry.

closes #7986

* generate doc/requirements.txt

As suggested in https://github.com/haskell/cabal/pull/10030#pullrequestreview-2064505535

* generate doc/requirements.txt

As suggested in https://github.com/haskell/cabal/pull/10030#pullrequestreview-2064505535

The proposal has been accepted, but its final location is in the 'rfc'
subdirectory instead of the 'proposals' subdirectory. This simply
updates the link in the Cabal documentation.

- Adds pijul as type
- explicit dot is the same as root
- Update doc/cabal-package-description-file.rst
- Grammar, comma required for non-restrictive clause
- Move warning down the section
- Move repository stuff to its own page
- Add author and consumer subsections
- Keep consistent ordering
- Put source-repository before source-repository-package
- Reword intro and add hackage linking
- A field of this type is always optional
- Fix typo
- Put the table into the field types section
- Link to VCS kind, consistent casing
- Introduce the VCS acronym early
- Link to cabal get for this|head
- Update doc/cabal-package-description-file.rst
- Comma after as an example
- Update doc/cabal-package-description-file.rst
- There are two kinds comma
- Split sentences.
- Move to how to section
- Add version control fields
- Rewrite package consumer section
- Bump source packages up a level
- Rename as "how to source packages"
- Rename section, "package source"
- Fix whitespace
- Mention manual download before cabal download
- Use a description list for source-repository fields
- Add a warning about the confusing field names
- Clarify *source code* ``.tar.gz`` archive
- Use Git uppercase
- Source Marker section, marks out
- Change to "inside a single VCS repository"
- Taking a Dependency from a Source Code Repository
- Lead with uppercase first letter for Darcs, Git
- Fix whitespace
- Use lowercase for titles
- Change the guide title to "How to get package *source code*".
- Hackage is for published, exact versus range of versions
- Mention cabal get
- Lead with uppercase for Cabal and Hackage
- Move VCS fields up in the tree
- Mention *source code* in all the section titles
- Explain how linking helps contributors and maintainers
- Add an example of conversion
- Add a dependency vendoring section
- Show cloning with cabal build --dry-run
- Keep VCS fields small
- Add diagrams
- Warn about hash in clone folder name
- Use code style for .cabal
- Use lower caps in title to match other sections
- Add missing _ for external link reference
- Move package authoring section to last
- Use subsections for vendoring
- Add a section about publishing
- Fix up anchors and references
- Typo, "extracts it to a directory"
- It is a "``cabal get`` unpacking step"
- Use a comma in "Fork, don't vendor"
- Add a tag to the src-repo-pkg example
- The warning about commits is only for Git repositories
- Move note to setting up section
- Fix whitespace
- Missing source-repository ead in the diff
- Use with/without a "-package" suffix ... belongs
- Add a reference to cabal get
- How to locate and get
- Add back the ref to the package consumer section
- Replace arrowheads with ASCII
- Replace ticked checkboxes with ASCII
- Warn about project and the set of pkgs separately
- Multiple dependency packages not multiple dependencies
- Shorter explanation of vendoring
- Lower caps for bold terms
- Add references to VCS fields
- A marker that points to
- Use the shorter "shepherd"
- Use grab (not obtain) before obtaining
- Clarify terms in source code note
- Hackage is only for published package dependencies
- Add a link to hackage upload
- Add a footnote about packages of a cabal.project
- Revert section title to "Specifying the local packages"
- Change shepherd to "deal with"
- Put source after package, ordering how to guides
- Comma after as

Co-Authored-By: Artem Pelenitsyn <a.pelenitsyn@gmail.com>
Co-Authored-By: brandon s allbery kf8nh <allbery.b@gmail.com>

Co-authored-by: brandon s allbery kf8nh <allbery.b@gmail.com>

Co-authored-by: brandon s allbery kf8nh <allbery.b@gmail.com>

This commit introduces a new build-type, Hooks. A package using this
build type should provide a SetupHooks.hs module which exports
a value `setupHooks :: SetupHooks`. This is intended to replace the
Custom setup type. This allows Cabal to have finer-grained information
about the build, instead of having an opaque Setup executable to invoke.

Tests include:

  - error when returning an invalid component diff in a
    per-component pre-configure hook
  - error when declaring pre-build rules whose dependency
    graph contains cycles
  - error when we cannot find a dependency of a pre-build rule
  - warning when there are pre-build rules that are declared but
    never demanded
  - correctness tests for SetupHooks, e.g. that
    pre-build rules are run in dependency order (see the
    `SetupHooksRuleOrdering` test)

Also uses 'stanza' consistently in that context.

* Redesign 'cabal path' command to account for projects

Previously, `cabal path` was only able to query from the global
configuration file, e.g., `~/.cabal/config` or the XDG equivalent.
Adding support for cabal project is a huge boost to usability.

We take the foundations and turn them into `cabal v2-path` which takes
project configuration, such as `cabal.project` into account.
Note, the command is still named `cabal path`, but for the sake of
disambiguation, we refer to this new iteration of the command as `cabal
v2-path`.

In addition, we add support for multiple output formats, such as
key-value pairs and json.

The key-value pair output prints a line for each queried key and its
respective value:

    key1: value2
    key2: value2

If only a single key is queried, we print only the
value, for example:

    value1

The json output format is versioned by the cabal-install version which
is part of the json object.
Thus, all result objects contain at least the key "cabal-install-version".

We expand the `cabal v2-path` to also produce information of the
compiler that is going to be used in a `cabal build` or `cabal repl` invocation.
To do that, we rebuild the install plan and query for the configured
compiler program.
This is helpful for downstream tools, such as HLS, to figure out the GHC
version required to compile a project with.

We also add an exhaustive test suite for 'cabal path' cmd

We test that each query honours cabal.project files, cli parameters, and
is composable with the other query flags.

We extend the test output normalisers for ghc compiler location and
cabal-install version, as the 'cabal path' command outputs the exact ghc
and ghc-pkg location. In addition, the json output format is versioned
on the cabal-install version.

Currently, we query the cabal-install version on each test normalisation
run. This might be unnecessary expensive, and could be avoided by
introducing a 'cabalProgram' that specifies how the program version can
be found. This way, we can cache the version query.

Add '--cache-home' flag thats shows the cabal's cache root

Rename '--cache-dir' to the more correct '--remote-repo-dir'.

* Update 'cabal path' documentation

* Add changelog.d entry

---------

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Per https://github.com/haskell/cabal/wiki/Updating-the-license-list
to version 3.23 (2024-02-08) of SPDX License List.

As a warning (“Hackage would reject this package”), to prepare users
to GHC language editions.

Co-authored-by: brandon s allbery kf8nh <allbery.b@gmail.com>

In this PR we make the `--package-db` flag apply only to the default
immutable initial package stack rather than also applying to the store
package database.

There are two special package databases which cabal install knows about
and treats specially.

* The store directory, a global cache of installed packages where cabal
  builds and installs packages into.
* The inplace directory, a local build folder for packages, where cabal
  builds local packages in.

It is very important that cabal registers packages it builds into one of
these two locations as there are many assumptions that packages will end
up here.

With the current design of the `--package-db` flag, you are apparently
allowed to override the store location which should have the effect of
making the last package database in the package stack the "store"
directory. Perhaps this works out in theory but practically this
behaviour was broken and things were always registered into the store
directory that cabal knew about. (The assertion in
`ProjectBuilding.UnpackedPackage` was failing (see added test)).

With `--package-db` not being able to modify the location of the store
directory then the interaction of `--package-db`, `--store-dir` and
`--dist-dir` flags become easy to understand.

* `--package-db` modify the initial package database stack, these
  package database will not be mutated by cabal and provide the initial
  package environment which is used by cabal.
* `--store-dir` modify the location of the store directory
* `--dist-dir` modify the location of the dist directory (and hence
  inplace package database)

Treating the flags in this way also fix an assertion failure when
building packages.

Fixes #9678