Redesign 'cabal path' command to account for projects #9583

fendor · 2024-01-02T15:39:02Z

Previously, cabal path was only able to query from the global configuration file, e.g., ~/.cabal/config or the XDG equivalent. This was deemed not useful enough to warrant a new cabal command, which is a user facing change.

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. Specifying the output format is currently mandatory. This allows us to postpone the decision of the default output format and encourages users to explicitly specify the output format in the future, too.

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

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

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.

QA Notes

The name of the command is cabal path. It should give the user the option to query certain paths cabal will be using.

The following things might be of interest to validate

Check, that the output of cabal path --help informs the user of its purpose and stability promises.
Any combination of flags to cabal path should succeed. Order should not matter and the output does not honour the order of flags.
- Exception, what is the expected behaviour when the given ghc executable cannot be found? Currently, no output is produced and cabal exits with a non-zero exit status.
As the command is intentionally requiring the flag output-format, did the error message when you forget to supply this flag help you figure out how to solve the issue?
Does the command work in both XDG and legacy cabal dir layouts?
Are cabal.project files honoured?
Are the paths you can query of interest to you?
Can you ignore the project context via -z?
Can you supply custom --cabal-config locations?
The command cabal path must never produce any caching artefacts, i.e. no folder in dist-newstyle is ever modified or created. Neither is dist-newstyle.
Are all output-formats adequately explained or self-explanatory?

Template Α: This PR modifies cabal behaviour

Include the following checklist in your PR:

Patches conform to the coding conventions.
Any changes that could be relevant to users have been recorded in the changelog.
The documentation has been updated, if necessary.
Manual QA notes have been included.
Tests have been added. (Ask for help if you don’t know how to write them! Ask for an exemption if tests are too complex for too little coverage!)

fendor · 2024-01-02T15:43:31Z

As a bit of background context, this PR is the result of the discussions in https://hackmd.io/mQjghm2zRgWgcyD4XKhBqA.
It unifies the cabal status command with cabal path, hopefully producing something that is useful to everyone.

~~The flag compiler-info still causes solving for dependencies, but I couldn't figure out yet how to avoid that elegantly.~~ Fixed 🎊 However, we also need to write out the hcPkgPath.

More tests are yet to come (also a POC that it actually helps hie-bios and HLS's startup time), but since I expect a solid amount of bikeshedding, I open the PR now.

fendor · 2024-03-09T18:56:57Z

This is ready for review now! I want to add a couple of tests. Is there any chance this could land in 3.12 or is that going to be released soon?

fendor · 2024-03-10T15:36:12Z

cabal-install/src/Distribution/Client/CmdPath.hs

+  compilerPathOutputs <-
+    if not $ fromFlagOrDefault False (pathCompiler pathFlags)
+      then pure Nothing
+      else do
+        (compiler, _, progDb) <- runRebuild (distProjectRootDirectory . distDirLayout $ baseCtx) $ configureCompiler verbosity (distDirLayout baseCtx) (projectConfig baseCtx)
+        compilerProg <- requireCompilerProg verbosity compiler
+        (configuredCompilerProg, _) <- requireProgram verbosity compilerProg progDb
+        pure $ Just $ mkCompilerInfo configuredCompilerProg compiler


Honestly, I hate this, I much rather would have some kind of rule system like shake, so we could depend on certain targets, in this case project base context.

cabal-install/src/Distribution/Client/CmdPath.hs

cabal-testsuite/PackageTests/Path/All/cabal.test.hs

chreekat · 2024-04-08T08:53:42Z

Specifying the output format is currently mandatory. This allows us to postpone the decision of the default output format and encourages users to explicitly specify the output format in the future, too.

cabal is UI first and foremost. Forcing users to pick an output format is an antifeature. Scripters can specify the json format once in their script and move on with their lives.

fendor · 2024-04-11T18:00:26Z

@chreekat By default, now cabal path will use the key-value output format.

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

Mikolaj · 2024-04-16T09:11:02Z

@mergify backport

mergify · 2024-04-16T09:11:28Z

backport

❌ No backport have been created

No destination branches found

Mikolaj · 2024-04-16T09:14:45Z

@mergify backport 3.12

mergify · 2024-04-16T09:15:19Z

backport 3.12

✅ Backports have been created

#9893 Redesign 'cabal path' command to account for projects (backport #9583) has been created for branch 3.12 but encountered conflicts

* 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> (cherry picked from commit 4a8a7c5) # Conflicts: # cabal-install/src/Distribution/Client/Setup.hs

* 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> (cherry picked from commit 4a8a7c5)

Redesign 'cabal path' command to account for projects (backport #9583)

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

- Command help text ends with full stop Co-Authored-By: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

Regen cabal help after #9583

fendor force-pushed the enhance/cabal-paths branch 4 times, most recently from 821ad8f to 8a23c6e Compare January 2, 2024 17:54

athas mentioned this pull request Feb 29, 2024

cabal path foo errors with 'man' doesn't take any extra arguments: foo #9755

Closed

fendor force-pushed the enhance/cabal-paths branch 4 times, most recently from 656bb6a to 075ba0e Compare March 4, 2024 09:10

andreasabel linked an issue Mar 4, 2024 that may be closed by this pull request

cabal path foo errors with 'man' doesn't take any extra arguments: foo #9755

Closed

fendor force-pushed the enhance/cabal-paths branch 3 times, most recently from db5ab38 to 6f637a8 Compare March 9, 2024 15:33

fendor added the attention: needs-review label Mar 9, 2024

geekosaur approved these changes Mar 9, 2024

View reviewed changes

fendor commented Mar 10, 2024

View reviewed changes

cabal-install/src/Distribution/Client/CmdPath.hs Outdated Show resolved Hide resolved

fendor force-pushed the enhance/cabal-paths branch from 786f132 to 50ba442 Compare March 10, 2024 16:55

fendor commented Mar 10, 2024

View reviewed changes

cabal-testsuite/PackageTests/Path/All/cabal.test.hs Outdated Show resolved Hide resolved

fendor force-pushed the enhance/cabal-paths branch 5 times, most recently from 90bf19d to db03267 Compare March 11, 2024 17:42

Mikolaj added the attention: needs-backport 3.12 label Mar 14, 2024

fendor force-pushed the enhance/cabal-paths branch 2 times, most recently from cc5169f to 48df524 Compare March 22, 2024 13:00

fendor force-pushed the enhance/cabal-paths branch from 18dbb02 to 62a44b6 Compare April 12, 2024 14:41

andreasabel approved these changes Apr 12, 2024

View reviewed changes

fendor and others added 3 commits April 12, 2024 22:55

Update 'cabal path' documentation

bca688d

Add changelog.d entry

58fcbb7

fendor force-pushed the enhance/cabal-paths branch from 62a44b6 to 58fcbb7 Compare April 12, 2024 20:56

fendor added squash+merge me Tell Mergify Bot to squash-merge and removed attention: needs-review labels Apr 12, 2024

mergify bot added the merge delay passed Applied (usually by Mergify) when PR approved and received no updates for 2 days label Apr 14, 2024

Merge branch 'master' into enhance/cabal-paths

6b7ce07

mergify bot merged commit 4a8a7c5 into haskell:master Apr 14, 2024
44 checks passed

mergify bot mentioned this pull request Apr 16, 2024

Redesign 'cabal path' command to account for projects (backport #9583) #9893

Merged

5 tasks

mergify bot added a commit that referenced this pull request Apr 16, 2024

Merge pull request #9893 from haskell/mergify/bp/3.12/pr-9583

b6c1ed6

Redesign 'cabal path' command to account for projects (backport #9583)

Mikolaj removed the attention: needs-backport 3.12 label Apr 23, 2024

philderbeast mentioned this pull request Apr 24, 2024

Use alice as username in cabal path examples #9931

Merged

ulysses4ever mentioned this pull request May 13, 2024

Fix typo (backport #9770) #10001

Closed

3 tasks

philderbeast added a commit to cabalism/cabal that referenced this pull request Nov 11, 2024

Regen cabal help after haskell#9583

018893b

philderbeast added a commit to cabalism/cabal that referenced this pull request Nov 11, 2024

Regen cabal help after haskell#9583

842b403

philderbeast added a commit to cabalism/cabal that referenced this pull request Nov 11, 2024

Regen cabal help after haskell#9583

73b8493

- Command help text ends with full stop Co-Authored-By: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

philderbeast added a commit to cabalism/cabal that referenced this pull request Nov 15, 2024

Regen cabal help after haskell#9583

19c9f88

- Command help text ends with full stop Co-Authored-By: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

mergify bot added a commit that referenced this pull request Nov 15, 2024

Merge pull request #10545 from cabalism/doc/9583-help

f276006

Regen cabal help after #9583

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Redesign 'cabal path' command to account for projects #9583

Redesign 'cabal path' command to account for projects #9583

fendor commented Jan 2, 2024 •

edited

Loading

fendor commented Jan 2, 2024 •

edited

Loading

fendor commented Mar 9, 2024

fendor Mar 10, 2024

chreekat commented Apr 8, 2024

fendor commented Apr 11, 2024

Mikolaj commented Apr 16, 2024

mergify bot commented Apr 16, 2024

Mikolaj commented Apr 16, 2024

mergify bot commented Apr 16, 2024 •

edited

Loading

Redesign 'cabal path' command to account for projects #9583

Redesign 'cabal path' command to account for projects #9583

Conversation

fendor commented Jan 2, 2024 • edited Loading

QA Notes

fendor commented Jan 2, 2024 • edited Loading

fendor commented Mar 9, 2024

fendor Mar 10, 2024

Choose a reason for hiding this comment

chreekat commented Apr 8, 2024

fendor commented Apr 11, 2024

Mikolaj commented Apr 16, 2024

mergify bot commented Apr 16, 2024

❌ No backport have been created

Mikolaj commented Apr 16, 2024

mergify bot commented Apr 16, 2024 • edited Loading

✅ Backports have been created

fendor commented Jan 2, 2024 •

edited

Loading

fendor commented Jan 2, 2024 •

edited

Loading

mergify bot commented Apr 16, 2024 •

edited

Loading