Cabal会在哪些路径下搜索includes字段中列出的文件？

Great question—this part of the Cabal docs is definitely a bit vague! Let’s break down exactly where Cabal looks for system-installed header files when you use the includes field:

Key Search Paths for System Headers #

• System compiler default paths: Cabal relies on your system's C compiler (like GCC or Clang) to resolve system-installed headers. It automatically includes all default paths your compiler uses—common examples are /usr/include, /usr/local/include, or platform-specific paths (e.g., /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include on macOS). To check these defaults manually, run:

  gcc -v -E -x c /dev/null  # For GCC
  # Or for Clang:
  clang -v -E -x c /dev/null
  

  Look for the section labeled "include search starts here" to see all built-in paths.

• extra-include-dirs in your .cabal file: If you need to add non-standard system paths (e.g., headers installed in /opt/my-custom-lib/include), list them in the extra-include-dirs field of your package's .cabal file. Cabal will pass these paths to the compiler via the -I flag, ensuring they’re included in the search for headers specified in includes.

• Environment variables: Cabal respects standard C/C++ environment variables that modify include paths:

  • C_INCLUDE_PATH: For C-specific header paths
  • CPATH: A generic variable that applies to both C and C++ headers
    Any paths set here will be added to the compiler's search list when Cabal invokes it.

• Paths from system dependencies (via pkg-config): If your package depends on a system library that uses pkg-config (like libcurl or GTK), Cabal will automatically run pkg-config --cflags <library-name> to fetch the library's include paths and add them to the compiler's search path. This handles headers from external libraries your package links against.

How to Verify the Exact Paths Used #

To confirm which paths Cabal is actually using for your project, run a build with verbose output:

cabal build --verbose=3

Or if you’re using Stack:

stack build --verbose

Look for lines starting with your compiler command (e.g., gcc -c ...)—you’ll see all -I flags, which list every include path Cabal passes to the compiler.

Relevant Cabal Docs Excerpt #

As you referenced:

includes: list of filenames
This list contains all header files needed for compilation via C, applicable to both system-installed headers and headers included with the package being installed. The former must be looked up in absolute paths, while the latter are looked up relative to the top of the source tree or the directories listed in include-dirs.
These files typically contain prototypes for externally imported functions used by the package.

内容的提问来源于stack exchange，提问作者Chris Martin