Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve online docs for includes: field #10145

Merged
merged 1 commit into from
Jul 1, 2024
Merged

Improve online docs for includes: field #10145

merged 1 commit into from
Jul 1, 2024

Conversation

mpilgrem
Copy link
Collaborator

@mpilgrem mpilgrem commented Jun 24, 2024

Bases for additions to online docs:

@mpilgrem mpilgrem added the merge me Tell Mergify Bot to merge label Jun 24, 2024
RyanGlScott pushed a commit to RyanGlScott/mintty that referenced this pull request Jun 25, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
sol added a commit to sol/win32 that referenced this pull request Jun 25, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
sol added a commit to sol/network that referenced this pull request Jun 25, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
sol added a commit to sol/primitive that referenced this pull request Jun 25, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
sol added a commit to sol/process that referenced this pull request Jun 25, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
sol added a commit to sol/bytestring that referenced this pull request Jun 25, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
sol added a commit to sol/old-time that referenced this pull request Jun 25, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
sol added a commit to sol/ghcup-hs that referenced this pull request Jun 25, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
sol added a commit to sol/bzlib that referenced this pull request Jun 25, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
@hasufell
Copy link
Member

hasufell commented Jun 25, 2024

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
Copy link
Collaborator Author

mpilgrem commented Jun 25, 2024

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

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
Copy link
Member

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

andrewthad pushed a commit to haskell/primitive that referenced this pull request Jun 25, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
@mpilgrem mpilgrem removed the merge me Tell Mergify Bot to merge label Jun 25, 2024
@mpilgrem
Copy link
Collaborator Author

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.

Bodigrim pushed a commit to haskell/zlib that referenced this pull request Jun 25, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
@sol
Copy link
Member

sol commented Jun 26, 2024

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
Copy link
Member

sol commented Jun 26, 2024

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:

@mpilgrem
Copy link
Collaborator Author

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

hasufell pushed a commit to haskell/unix that referenced this pull request Jun 26, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
clyring pushed a commit to haskell/bytestring that referenced this pull request Jun 26, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
@mpilgrem
Copy link
Collaborator Author

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.

@mpilgrem mpilgrem added the merge me Tell Mergify Bot to merge label Jun 29, 2024
@sol
Copy link
Member

sol commented Jun 30, 2024

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
Copy link
Member

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
Copy link
Member

sol commented Jun 30, 2024

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.

tomjaguarpaw pushed a commit to haskell/process that referenced this pull request Jul 1, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
@mergify mergify bot added the merge delay passed Applied (usually by Mergify) when PR approved and received no updates for 2 days label Jul 1, 2024
@mergify mergify bot merged commit 6eaba73 into master Jul 1, 2024
15 checks passed
@mergify mergify bot deleted the includes-docs branch July 1, 2024 17:35
Mistuke pushed a commit to haskell/win32 that referenced this pull request Aug 27, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
@Mistuke
Copy link
Collaborator

Mistuke commented Aug 27, 2024

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:

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.

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.

Bodigrim pushed a commit to haskell/bytestring that referenced this pull request Oct 9, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
Bodigrim pushed a commit to haskell/bytestring that referenced this pull request Oct 15, 2024
This is useless at best, and a common source of confusion.

haskell/cabal#10145
sol/hpack#355
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation merge delay passed Applied (usually by Mergify) when PR approved and received no updates for 2 days merge me Tell Mergify Bot to merge
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants