[RFC] Introduce name-agnostic package filename

[chshersh]

If I have a package called foo the .cabal file for this package must be called foo.cabal. For the package bar it must be named bar.cabal. So the name of the file that describes package metadata should be the same as the package name. This is a minor inconvenience that makes it harder to write tooling and interact with packages:

1. If I want to change the project name, I also need to change the filename.
2. Tools that work with Haskell source code and want to read fields like default-extension can't just read a single file, and they need to filter files with the .cabal extension and do extra work.
3. GitHub analysing tools like issue-wanted can't just construct the path to the predefined file because the name of the repository and name of the package inside repository can be different.

So It feels that introducing a single name for all packages can make the ecosystem healthier. I'm not sure what are the benefits of forcing the .cabal file to have the same name as a package. But I see the benefits of having a single file name without apparent drawbacks.

Proposed change

1. Introduce a single uniform file name (like package.cabal or just .cabal).
2. cabal-install should first look at the package.cabal file to read metadata and if this file is not present, fall back to the current scheme.

Pros

1. Simpler integration with tooling.
2. More beginner-friendly build tooling.

Cons

1. Slightly complicates the logic of the cabal-install permanently or temporary (if this change is going to be accepted and all packages will migrate to this scheme after 10 years).

Alternatives

1. Do nothing.

[DanielG]

No one's forcing you to name your cabal files by their pacakge-name, it's just a convention. In fact naming every cabal file packge.cabal would work today, as far as cabal is concerned anyways. Stack is another matter, it enforces the naming convention and errors out when it is not satisfied.

[DanielG]

Evaluating your points above one by one: 1) Nope, you can keep the name the same, it'll still work. 2) IMO tools should use the Cabal library to read cabal files anyways or they're just going to be prone to break. 3) Come on, finding .cabal files is like five lines of code, that's not a fair trade for literally thousands of independent projects having to change to comply with this!

[DanielG]

Ah, cabal check will actually complain about the package-name naming convention:

Warning: The filename ./package.cabal does not match package name (expected: package-name.cabal)

So this wouldn't be distributable on Hackage actually!

[phadej]

No one's forcing you to name your cabal files by their pacakge-name, it's just a convention. In fact naming every cabal file packge.cabal would work today, as far as cabal is concerned anyways. Stack is another matter, it enforces the naming convention and errors out when it is not satisfied.

Not true,

Warning: The following errors will cause portability problems on other
environments:
Warning: The filename ./fol.cabal does not match package name (expected:
foldable1.cabal)
Warning: Hackage would reject this package.

[chshersh]

2. IMO tools should use the Cabal library to read cabal files anyways or they're just going to be prone to break

Partially agree. Sometimes you just want to get a value of the cabal-version field, this can be done without depending on Cabal. Also, Cabal is a boot library and supporting builds of your package under multiple GHC version can be a bit painful if you want to do something simple. Also, I don't see a function of type getCabal :: IO GenericPackageDescription. AFAIU, you still need to provide a full path to the .cabal file:

• https://hackage.haskell.org/package/Cabal-3.0.0.0/docs/Distribution-PackageDescription-Parsec.html#v:readGenericPackageDescription

3. Come on, finding .cabal files is like five lines of code, that's not a fair trade for literally thousands of independent projects having to change to comply with this!

This is not exactly true if I want to scrawl GitHub. Knowing owner and package name, I can't just construct the URL to the cabal file like this if I want to fetch information:

https://raw.githubusercontent.com/kowainik/relude/master/relude.cabal

This requires to perform an extra call to the GitHub API to get the content information making the code less performant and hitting GitHub API rate limit even sooner.

[phadej]

Sometimes you just want to get a value of the cabal-version field, this can be done without depending on Cabal.

I'd say, no you cannot. You can do some smart regex, but that's a hack.

---

This is not exactly true if I want to scrawl GitHub. Knowing owner and package name, I can't just construct the URL to the cabal file like this if I want to fetch information:

But you can now, what's the problem then?

How about multi package repositories, this change won't help those, will it?

---

That said I'm not against this idea in general. But a bit more elaborate proposal would be nice, the migration story have to explicitly written out.

• I assume this would be valid only for cabal-version: X.Y packages. This is the least, to prevent old cabal-installs try to build the package.
• 01-index.tar format cannot be changed, so there they will still be stored as package-name.cabal, but that's fine?

[DanielG]

On Thu, Oct 17, 2019 at 09:13:31AM -0700, Dmitrii Kovanikov wrote: Also, `Cabal` is a boot library and supporting builds of your package under multiple GHC version can be a bit painful if you want to do something simple.

Just because it's a boot library does not mean you have to support all versions of it. That is only true if you also happen to depend on the `ghc` library so not in general.

Also, I don't see a function of type `getCabal :: IO GenericPackageDescription`. AFAIU, you still need to provide a full path to the `.cabal` file:

getCabal verbosity = readGenericPackageDescription verbosity =<< defaultPackageDesc verbosity

> 3) Come on, finding .cabal files is like five lines of code, that's not a fair trade for literally thousands of independent projects having to change to comply with this! This is not exactly true if I want to scrawl GitHub. Knowing owner and package name, I can't just construct the URL to the `cabal` file like this if I want to fetch information: ``` https://raw.githubusercontent.com/kowainik/relude/master/relude.cabal ``` This requires to perform an extra call to the GitHub API to get the content information making the code less performant and hitting GitHub API rate limit even sooner.

Ah that makes more sense. I honestly still don't think the whole ecosystem should pay the price just because of this arbitrary limitation though. Have you tried asking Github for a better API even? ;)

[chshersh]

But you can now, what's the problem then?

What I can now is to get the list of all Haskell repositories with their names in a single GitHub search query (well, almost, but that's implementation detail). However, as I mentioned, the GitHub repository can have a different name from the Haskell package inside. And for now, my application can't handle such repositories without extra work.

How about multi package repositories, this change won't help those, will it?

It actually will, because the file for describing multiple packages is already always called cabal.project so I can construct URL in a uniform way, download cabal.project, parse it and construct URLs to the nested package.cabal files in subdirectories without the need to look into directory contents.

I assume this would be valid only for cabal-version: X.Y packages. This is the least, to prevent old cabal-installs try to build the package.

I agree with this, sounds reasonable.

01-index.tar format cannot be changed, so there they will still be stored as package-name.cabal, but that's fine?

I'm not aware of such implementation details, but I guess that's fine.

[chshersh]

@DanielG

Ah that makes more sense. I honestly still don't think the whole
ecosystem should pay the price just because of this arbitrary
limitation though. Have you tried asking Github for a better API even? ;)

Yes, I tried, and they are not going to change the way their API is implemented. My primary motivation is not to adapt to the specifics of the GitHub API, though, this would solve a real practical problem for me. I think that this is a general overall improvement. And this feature is opt-in. However, I have a feeling that a lot of people will appreciate this change 🙂

[DanielG]

I suppose if we make this conditional on the cabal-version it wouldn't be as bad as I thought actually. At that point it really is just an aestetics thing but doesn't (really) break anything.

Though I'm not sure you can call it opt-in if we start enforcing the package.cabal name starting with the next cabal-version.

[phadej]

• Support window where both <package-name>.cabal and package.cabal are found:
  • doesn't improve the situation, hardly anyone would change, especially existing packages
• Hard change at some concrete cabal-version: X.Y
  • internet

I'm scared of the internet nowadays...

---

Also I'm quite sure something in hackage-server would need an update.

---

I can only say that this is non-trivial change, and one will learn more when implementing it

[Mikolaj]

HI! Could we re-open this discussion? We are currently in-between the two worlds --- cabal build accepts arbitrary .cabal file names, cabal sdist warns, cabal install breaks, Hackage sicks the dogs. Users get confused and errors/warnings are too late and inconsistent. See #7322.

I think we should either error out early if package foo doesn't have foo.cabal file neme, or permit both foo.cabal and package.cabal for the forseable future, advertise it, let the market decide and don't worry about forbidding foo.cabal just now. Two generations of maintainer will burn out before social awareness is at a level permitting to ban foo.cabal, so no need to worry about it yet, but at least we open up the future and let fringe worflows flow, at a relatively low cost IMHO (certainly compared to the inconsistent status quo).