Add status command to cabal

[fendor]

Lightweight command that can query for very basic information
in a cabal project.
In particular, information about the compiler for the project and the
unit-id a given target belongs to.
Other flags are bound to follow.

A document that lays out the plan in more detail: https://gist.github.com/fendor/796b373aba26e12dbdecf7e40af78b32

This is the second part to #7489. It allows IDEs and hie-bios to quickly query for certain project meta information, in this case compiler information and what unit a target string belongs to.

Example:

> cabal status --output-format=json --compiler | jq
{
  "cabal-version": "3.7",
  "compiler": {
    "flavour": "ghc",
    "compiler-id": "ghc-8.10.7",
    "path": "/home/hugin/.ghcup/bin/ghc"
  }
}

> cabal status --output-format=json --compiler --target="lib:cabal" | jq
{
  "cabal-version": "3.7",
  "compiler": {
    "flavour": "ghc",
    "compiler-id": "ghc-8.10.7",
    "path": "/home/hugin/.ghcup/bin/ghc"
  },
  "targets": [
    {
      "target": "lib:cabal",
      "unit-id": "Cabal-3.7.0.0-inplace"
    }
  ]
}

Target strings that resolve to the same component are listed both times.

> cabal status --output-format=json --compiler --target="lib:cabal" --target="./Cabal/src/Distribution/Make.hs" | jq
{
  "cabal-version": "3.7",
  "compiler": {
    "flavour": "ghc",
    "compiler-id": "ghc-8.10.7",
    "path": "/home/hugin/.ghcup/bin/ghc"
  },
  "targets": [
    {
      "target": "lib:cabal",
      "unit-id": "Cabal-3.7.0.0-inplace"
    },
    {
      "target": "./Cabal/src/Distribution/Make.hs",
      "unit-id": "Cabal-3.7.0.0-inplace"
    }
  ]
}

Main advantage:

• Very quick (only perform work you actually need)
• Extensible
• Composable

Disadvantage:

• Maintain cabal command
• Do we really need it?
• Are we sure we are not just blindly adding commands without considering a bigger picture?

Alternatives:

• Use cabal build --dry-run to generate plan.json and then parse that one.
  • How to find the location of plan.json given a target string?
• Merge this with another command
  • E.g. Add option cabal build --dry-run --targets or something like that, but it feels like terrible UX.

Missing:

• Write tests in cabal-testsuite
  • No build-plan
  • Some third-party dependency doesn't build
  • Some local dependency doesn't build
  • Ignores invalid target selectors
  • Disabled units
  • Unit fails to build
  • GHCJS, what's the output?
  • Check plan.json is generated
  • Bench unit
  • Exe unit
  • Flib unit
  • Lib unit
  • Test unit
  • Custom Setup
• Documentation
  • Write Command docs
  • Define json schema
  • Explicitly mark as experimental
  • Show some use-cases
  • Future features
    • Cabal-plan why-depends

Old PR description, here for completeness

Lightweight command that can query for very basic information
in a cabal project.
In particular, you can list all targets in your project or print
information about the compiler. Other flags are bound to follow.

This is the second part to #7489. It allows IDEs and hie-bios to quickly query for certain project meta information, in this case compiler information and available targets.

Example:

> cabal ide --project-compiler
Resolving dependencies...
Compiler: ghc
Version: 8.10.2
Path: /home/hugin/.ghcup/bin/ghc-8.10.2

> cabal ide --targets
lib:Cabal
lib:cabal-testsuite
exe:setup
exe:cabal-tests
lib:cabal-install
exe:cabal
test:long-tests
test:integration-tests2
test:memory-usage-tests
test:unit-tests
lib:cabal-install-solver
test:unit-tests
lib:solver-benchmarks
exe:hackage-benchmark
test:unit-tests
lib:Cabal-QuickCheck
lib:Cabal-tree-diff
lib:Cabal-described
test:no-thunks-test
test:rpmvercmp
test:hackage-tests
test:custom-setup-tests
test:check-tests
test:parser-tests
test:unit-tests
test:cabal-benchmarks
lib:cabal-doctest

Main advantage:

• Very quick (only perform work you actually need)
• Extensible

Disadvantage:

• Maintain cabal command
• Do we really need it?
• Are we sure we are not just blindly adding commands without considering a bigger picture?

Alternatives:

• Use cabal build --dry-run to generate plan.json and then parse that one.
  • How to find the location of plan.json?
• Merge this with another command
  • E.g. Add option cabal build --dry-run --targets or something like that, but it feels like terrible UX.

Missing:

• [ ] Documentation
• [ ] Test-cases

[michaelpj]

If the intent is for these to be machine-readable, would it make sense to dump them out in JSON or similar by default?

[phadej]

If the intent is for these to be machine-readable, would it make sense to dump them out in JSON or similar by default?

What's wrong with reading plan.json then. cabal-plan library has SearchPlanJson and findPlanJson find the plan.json files.

[fendor]

What's wrong with reading plan.json then.

Personally, I think it is a bit troublesome to find plan.json reliably without user input. If we can mitigate that somehow, the ide command could also be just a frontend to query plan.json efficiently in a backwards compatible way.

Additionally, what is the simplest/efficient way to generate plan.json? cabal build all --dry-run? That takes on the cabal code-base 2.5s, while the ide command needs a couple of milliseconds.

However, I can see how appealing it would be to not have to introduce a new command...

[jneira]

This is the second part to #7489. It allows IDEs and hie-bios to quickly query for certain project meta information, in this case compiler information and available targets.

So it the replacement od cabal show-build-info? Afaiu it is complementary to cabal build --ddump-build-info=file, no? I mean all the info this command can offer will be in the show-build-info json, right? (and then the json requested by @michaelpj would be already covered)
In any case i like the design, the discoverability and it could be used for other tooling than ide's, like shell scripts

[fendor]

I mean all the info this command can offer will be in the show-build-info json, right?

Not only from build-info.json, e.g. available target information is from plan.json. Conceputally, all information we can query via cabal ide is available in plan.json and the component respective build-info.json.

So it the replacement od cabal show-build-info?

Basically yes, but intended to be a bit more general.

Afaiu it is complementary to cabal build --ddump-build-info=file, no?

Yep, ideally a quick way to query for project metadata, in this case project compiler and targets.

[emilypi]

@Mergifyio update

[mergify]

Command update: success

Branch has been successfully updated

[gbaz]

Some slight bikeshedding since we closed the old status pr in favor of this. I'd prefer the name be something like "status" (now available!) or "build-info" or the like, since I imagine end users and not just ides might want this.

Also I'd encourage taking a look at this status output from the old draft PR to see if all the information it provides is covered by this -- maybe the old work covers something missed/forgotten here? :-)

#2882 (comment)

[emilypi]

@fendor what do you think about @gbaz's comment?

[fendor]

I did not have time yet to revisit this PR.

[jneira]

@fendor ping, would be great to see this in 3.8 if possible

[fendor]

I think to get this over the finish line, we need the following resolved:

• What is the scope?
  • Pure query interface or is it allowed to perform side effects (such as writing a build-plan to plan.json)
• Who is the intended consumer of this command?
  • Should the output be human-readable or machine-readable?
    • hie-bios needs a quick way to query for the GHC version (in the current hie-bios interface, it actually needs the GHC path)
    • Humans might be interested in ide/info output too
• What should be generally be queried via this interface?
  • I proposed information available in plan.json and build-info.json if these files exist.

[jneira]

Thanks for the update

I think to get this over the finish line, we need the following resolved:

* What is the scope?
  
  * Pure query interface or is it allowed to perform side effects (such as writing a build-plan to `plan.json`)

I would say that it should generate the info if it is needed instead throw an error or show staled info.

* Who is the intended consumer of this command?
  
  * Should the output be human-readable or machine-readable?
    
    * hie-bios needs a quick way to query for the GHC version (in the current hie-bios interface, it actually needs the GHC path)
    * Humans might be interested in `ide`/`info` output too

I would say that human readable, as tools could access the undelying info (build-info and plan.json). that said it could have some flag to make it seudo machine readable.

* What should be generally be queried via this interface?
  
  * I proposed information available in `plan.json` and `build-info.json` if these files exist.

Sounds good

[andreasabel]

I agree with @gbaz that ide isn't the best name for a command that dumps some computed information. ide promises to crank up an IDE for package development or something grand like that.
Alt: values, show-info etc.

[mergify]

update

❌ Base branch update has failed

refusing to allow a GitHub App to create or update workflow .github/workflows/bootstrap.yml without workflows permission
err-code: 8016A

[fendor]

Closing as discussed in https://hackmd.io/mQjghm2zRgWgcyD4XKhBqA

A new PR will follow soonish, depending on the holidays.