Improve online docs for includes: field

[mpilgrem]

Bases for additions to online docs:

• https://downloads.haskell.org/~ghc/6.10.1/docs/html/users_guide/release-6-10-1.html ("... the includes field in .cabal files ... all have no effect when compiling Haskell source code.")

• EDIT: https://downloads.haskell.org/ghc/latest/docs/users_guide/exts/ffi.html#using-header-files ("... the include-files field in a Cabal package specification is ignored.") (The reference to include-files is as in the original; it can be understood to mean includes.) EDIT2: https://gitlab.haskell.org/ghc/ghc/-/issues/25032

• https://hackage.haskell.org/package/Cabal-2.0.0.2/changelog ("Dropped support for versions of GHC earlier than 6.12 ...")

• e1c39fc (removes use of GHC's -#include option)

• Patches conform to the coding conventions. N/A

• Is this a PR that fixes CI? If so, it will need to be backported to older cabal release branches (ask maintainers for directions). N/A

[hasufell]

I don't understand. Cabal was written to be a specification. Whether GHC supports all the things is kind of irrelevant to the spec.

The question is, does an includes field make sense? Can we debate this properly without just looking at GHC?

[mpilgrem]

@hasufell, I had a similar thought, but in connection with:

• Should includes: field be removed from the specification?  #10147

rather than this change to the online documentation. (With the documentation, I did hesitate over adding 'deprecated' but lots of Haskell packages - including GHC boot packages - no longer use the redundant - from a GHC perspecive - includes: field.)

The following comment may be better at #10147:

I appreciate that the Cabal User Guide still states:

One of the purposes of Cabal is to make it easier to build packages on different platforms (operating systems and CPU architectures), with different compiler versions and indeed even with different Haskell implementations. (Yes, there are Haskell implementations other than GHC!)

but is that true of Cabal (the library) in 2024? In practice, do the Cabal team actively consider the possibility of Haskell implementations other than GHC?

[Kleidukos]

@mpilgrem Yeah we recently merged a PR that recognised the existence of MicroHS (#9878)

[mpilgrem]

I have removed merge-me, given (a) @hasufell's comment and (b) to copper-bottom that GHC did not re-introduce (undocumented) a use for Cabal's includes: with the CApiFFI language extension.

[sol]

to copper-bottom that GHC did not re-introduce (undocumented) a use for Cabal's includes: with the CApiFFI language extension

I would be surprised if that were the case for three reasons:

1. From what I originally tried with cabal -v3 I didn't see anything listed under includes to be passed to ghc (nor gcc). I didn't specifically try with CApiFFI, but given that Cabal can't definitely know whether some source file uses some specific language extension, Cabal isn't in a position to decide to do something different depending on whether CApiFFI is used or not. So from what I understand, the only option would be for Cabal to always pass includes to GHC, and again from what I have tried it does not do that.
2. e1c39fc removed flagFfiIncludes from GhcImplInfo. Doesn't this mean that the underlying mechanism for Cabal to communicate includes to GHC has been removed?
3. -#include has been removed from GHC, and I'm not aware of any other similar flag that Cabal could use to make GHC aware of any includes.

But given haskell/network#582 (comment) I agree that it makes sense to track down what exactly is still done with includes.

[sol]

to copper-bottom that GHC did not re-introduce (undocumented) a use for Cabal's includes:

#10153 demonstrates that there are no (undocumented) uses of includes, it is entirely unused.

The only things that Cabal does with includes are:

• check that they exist and that the paths are well-formed
• check that a dummy C program that includes them can be compiled successfully

[mpilgrem]

I've added to my list of 'bases' above GHC's current documentation.

[mpilgrem]

I am going to restore the merge-me because:

(a) I think it has now been copper-bottomed that GHC has not used Cabal's includes: field from GHC 6.10.1 (released November 2008);
(b) while that could be said to be a GHC-centric perspective, the origins of includes: were, I think, also GHC-centric. My review of the history is here sol/hpack#587 (comment);
(c) I think the 'Cabal project' has, effectively, deprecated includes: since Cabal 2.0 - and deprecated is not the same thing as removed;
(d) @sol's various pull requests could have stimulated the reaction 'No, includes: could be useful', but none have so far;
(e) if somebody were to develop a Haskell compiler other than GHC that wished to make use of includes:, the deprecated tag might help flag that a conversation need to be had with (i) the 'Cabal project' and (ii) the public packages, including GHC boot packages, that have dropped the use of includes: over the years.

[sol]

the origins of includes: were, I think, also GHC-centric.

I think that's the key observation here.

includes: was used by some archaic versions of GHC AND it was ever only used when complied with -fvia-C, which itself is a pretty exotic use case by now AND I think it's not entirely clear whether it's even practical to try to make sense of includes: in a context other than -fvia-C as, due to the nature of CPP, trying to parse C header files is a non-trivial undertaking.

In addition, includes is frequently misunderstood. People would:

• wrongly assume that includes: are passed to the C compiler via -include and/or GHC via -optP-include, which they are not and never have been
• wrongly assume that you have to list every file, that you CPP-#include somewhere, under includes:, which you don't have to (I think this is obvious if you have a proper understanding of the C compilation model, but I think it's also important to acknowledge that not necessarily every Haskell programmer has a proper understanding of the C compilation model)
• list C header files under includes: instead of extra-source-files, which results in broken package tarbals

Given all this, I kind of hope that all of us at least agree that something has to be done here. While I don't have a strong opinion on how exactly to change the documentation, I do think that this PR is an improvement over the status quo.

[hasufell]

wrongly assume that includes: are passed to the C compiler via -include and/or GHC via -optP-include, which they are not and never have been

This is exactly what the cabal documentation suggests:

A list of header files to be included in any compilations via C

What other interpretation here is possible? Whether GHC did something sensible is an entirely different discussion and I find it rather irrelevant. This is a spec.

I think this is obvious if you have a proper understanding of the C compilation model, but I think it's also important to acknowledge that not necessarily every Haskell programmer has a proper understanding of the C compilation model

This is not obvious at all. Again, this is a spec, not a shim over Makefiles. It doesn't have to map 1:1 to how you interact with gcc.

---

Given all this, I kind of hope that all of us at least agree that something has to be done here

Yes, I'd like to understand what was the original motivation as opposed to how it was actually used.

[sol]

wrongly assume that includes: are passed to the C compiler via -include and/or GHC via -optP-include, which they are not and never have been

This is exactly what the cabal documentation suggests:

I think "exactly" is a little bit strong here, but I agree that the Cabal documentation is potentially misleading. This is how I originally interpreted it:

sol/hpack#587 (comment)

The Cabal documentation says that they are used for compilations via C. Traditionally, in the context of GHC, "via-C" means unregistered builds / bootstrapping, which is pretty exotic, so I kind of doubt that this is what the Cabal docs refer to.

So what I kind of assume this is actually doing is pass -include to the C compiler when compiling c-sources. This is still pretty exotic though, as usually you would just use #include-statements instead.

Where include could actually be somewhat useful is, if Cabal would also pass them to ghc via -optP-include. Not sure if that's the case, the docs don't say anything about it and I'm currently away from the computers, so I can't try.

However, it turns out, that compilations via C indeed refers to -fvia-C only.

Unless proven otherwise, I assume -fvia-C is the original and only motivation for adding includes: to the specification. This is (a) consistent with everything @mpilgrem dug up and (b) I don't think dabbling in speculations is an effective tool when trying to understand something in a historic context.

[Mistuke]

I've merged haskell/win32#233 because that seems to be the direction things went, however I wanted to point out that:

The only things that Cabal does with includes are:

• check that they exist and that the paths are well-formed
• check that a dummy C program that includes them can be compiled successfully

This in itself was useful. The reason at least win32 had these was because of it's extensive use of hsc2hs. Cabal checking the existence of the header files provided a better user experience than hsc2hs giving a cryptic compile error. This prevents you from getting too far into your build process with a header that may be incompatible with your native compiler. imho it serves the exact analogous of what configure does, and also the reason why it's part of cabal configure.

So these changes will potentially make it much harder to figure out compile errors later.

Also note that hsc2hs and cpphs and other low level still includes --include=<file> today and it's required for certain scenarios. https://github.com/haskell/hsc2hs

To me the difference between includes and install-includes was clear. includes provided "configure" time validation for headers required during build time and install-includes provided headers required post build time.

I don't understand. Cabal was written to be a specification. Whether GHC supports all the things is kind of irrelevant to the spec.

The question is, does an includes field make sense? Can we debate this properly without just looking at GHC?

I 100% agree with this comment. I hope whatever discussion is had does not focus on what GHC does. This information is there and useful for custom build types as it's available through the Hook structures.

cabal/Cabal/src/Distribution/Simple/UserHooks.hs

Line 53 in 4f01b76

data UserHooks = UserHooks

and I've personally used them before when writing preprocessors.

So please don't focus Cabal solely on what GHC does or uses.