haskell / haskell/cabal

improve documentation for c-related fields

Open
#4,553 0 comments 1 reaction 0 assignees View on GitHub
documentation
Dominant language
Haskell
Stars
1.7k
Forks
750
Avg merge
4d 3h
Merged PRs (30d)
28

Description

The documentation for `c-sources` should state that the sources need to be listed [in dependency order](https://ghc.haskell.org/trac/ghc/ticket/13786#comment:3).

Also, it would be nice to have a bit more clarity on the various include-file-related options. Given that `include-files` is [ignored by GHC](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/ffi-chap.html#using-header-files), that should probably be noted in the Cabal documentation, too. And I'm unclear when `install-includes` would be needed, if ever. My solution has been to just put include files in `extra-source-files`, but it would be nice if the documentation offered more guidance on this.

Thanks!

Contributor guide

Open the contributing guide

Research direction

Start with the Cabal documentation for c-sources, include-files, and install-includes, then compare the linked GHC FFI documentation. Document dependency ordering for c-sources, note that GHC ignores include-files, and clarify when install-includes is needed versus extra-source-files.

Written by the indexing model from the issue text.

Assessment

Tech stack
haskell
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.