Implement extra-files

[mpilgrem]

cabal-version: 3.14 of the Cabal package description format specification has introduced new field extra-files - like extra-source-files but without the semantics that the files listed are tracked by build tools.

[sol]

Hey, thanks for looking into this.

Personally I am not convinced that extra-files offers enough value over extra-source-files and extra-doc-files to be worthwhile.

That said, this is a minimal change, so in this specific case I am willing to accept this patch for parity with Cabal.

Note that parity with Cabal is not a stated design principle of Hpack, so this will always be a case by case decision.

[sol]

As this is a very non-invasive change, do you think we should release as 0.38.1?

NB: Adding a new field to Hpack.Config.Package I don't consider a "breaking" change:

• Hpack.Config is semi-internal
• A user should use Hpack.Config.package to construct a Package anyway, and if they did that, their code will continue to work just fine.
• In general, for records with a large number of fields, I as a user should always be prepared that new fields are added.

[sol]

Please also bump the package version accordingly, so that a release to Hackage is triggered

[sol]

@mpilgrem I updated the issue description, can you please update the commit message accordingly?

[mpilgrem]

This is 'early', in that only GHC >= 9.12 requires Cabal >= 3.14 and we are unlikely to understand user use of extra-files until library authors start dropping support for GHC 9.10. However, Cabal-based build tools will treat extra-files differently (changes not tracked, not copied to html directory) from extra-source-files and extra-doc-files.

[sol]

Cabal-based build tools will treat extra-files differently (changes not tracked, ...) from extra-source-files

My question is more along the lines of "When does this actually matter?".

I think in the worst case you just rebuild too often. Now if there is some extra file that changes all the time, then I would see a potential issue that extra-files could address. It's just that I can't imagine a use case where this would matter.

[sol]

• apply my two diff suggestions
• bump version to 0.38.1
• add change log entry

Then this is ready to go 👍

[sol]

Suggested change

	it "accepts a list of files" $ do
	it "accepts extra-files" $ do

[mpilgrem]

We currently have:

extra-doc-files
  accepts a list of files

and

extra-files
  accepts extra-files

seemed a little 'circular' as an output - but if you are sure that is what you want, I'll put it through.

[sol]

The priorities are:

1. It needs to be clear what the purpose of a specific test case is ("What are we testing here?").
2. Consistency
3. Anything else

As (1) is the main priority, I would shy away from sacrificing it for stylistic reasons.

In this specific case, we are testing that it "accepts extra-files". We are not concerned with whether it can be a list, whether it accept globs, etc. (those aspects are covered by other test cases).

seemed a little 'circular' as an output

Yes, definitely agree!

However, if you would want to address this, then I think the right approach would be to get rid of the describe "extra-files".

But then again we already have things like:

describe "spec-version" $ do
  it "accepts spec-version" $ do

So keeping the describe is at least consistent with what we already have (in line with our second priority).

[sol]

@mpilgrem did you read this?

[mpilgrem]

Sorry, my mistake. I'll fix it now.

[sol]

Suggested change

	| `extra-files` | · | | Accepts [glob patterns](#file-globbing) | | `0.39.0` |
	| `extra-files` | · | | Accepts [glob patterns](#file-globbing) | | `0.38.1` |

[mpilgrem]

The reason I've held off on the Hpack version is that there may be other changes soon that could be released together (and extra-files on its own is not a burning platform) - I'm currently (off repository) looking at moving #518 forward.

[sol]

I say "release early, release often" and "minimize dependencies between tasks".

[mpilgrem]

Noted, but in this case #518 is on the heals of this one - and maybe #605 too, if I can convince you of its utility.

[mpilgrem]

Rebuilding unnecessarily was given as the motivation for extra-files:

• Populating extra-source-files in Agda.cabal broke workflow "deploy pages" agda/agda#6502
• Document that extra-source-files trigger a rebuild haskell/cabal#8756
• Neutral field (like extra-files or extra-sdist-files) to add files to sdist haskell/cabal#8817

but the fact it was not implemented for the first 20 years of Cabal suggests its need was not pressing!