Merge branch 'stable'

Author: mpilgrem

doc/GUIDE.md

@@ -1091,6 +1091,103 @@ modified version of a dependency that hasn't yet been released upstream.
     See [stack.yaml documentation](yaml_configuration.md#packages) for more
     details.
 
+## Haskell packages with C code
+
+A Haskell package can include C source code. For example, consider a simple
+one-package project named `c-example`, created by `stack new c-example` but with
+these changes:
+
+A C header file `my-library.h` added in new directory `include`:
+~~~c
+#ifndef MY_LIBRARY_HEADER
+#define MY_LIBRARY_HEADER
+int max(int, int);
+#endif
+~~~
+
+A C source code file `my-library.c` added in new directory `c-source`:
+~~~c
+#include "my-library.h"
+
+/* Function returning the larger of two integers */
+int max(int x1, int x2) {
+  if (x1 > x2)
+    return x1;
+  else
+    return x2;
+}
+~~~
+
+A different `src/Lib.hs` Haskell module, including a Haskell foreign import
+declaration making use of the C `max` function:
+~~~haskell
+module Lib
+  ( someFunc
+  , c_max
+  ) where
+
+someFunc :: IO ()
+someFunc = putStrLn "someFunc"
+
+foreign import ccall "max" c_max :: Int -> Int -> Int
+~~~
+
+A different `app/Main.hs` Haskell module, making use of the Haskell `c_max`
+function now exported from module `Lib`:
+~~~haskell
+module Main ( main ) where
+
+import Lib ( c_max, someFunc )
+
+main :: IO ()
+main = do
+  someFunc
+  print $ c_max 10 100
+~~~
+
+The package's `package.yaml` file (simplied), used to create the package's
+Cabal file, might look like this:
+~~~yaml
+spec-version: 0.36.0
+
+name: c-example
+version: 0.1.0.0
+
+# Hpack 0.36.1 and earlier does not support Cabal's 'includes' field
+extra-source-files:
+- include/my-library.h
+
+dependencies:
+- base >= 4.7 && < 5
+
+library:
+  source-dirs: src
+  include-dirs: # Where to look for C header files?
+  - include
+  c-sources: # What C source code files to be compiled and linked?
+  - c-source/my-library.c
+
+executables:
+  c-example-exe:
+    main: Main.hs
+    source-dirs: app
+    ghc-options:
+    - -threaded
+    - -rtsopts
+    - -with-rtsopts=-N
+    dependencies:
+    - c-example
+~~~
+
+The project's `stack.yaml` file only needs to identify a snapshot:
+~~~yaml
+snapshot: lts-22.26 # GHC 9.6.5
+~~~
+
+This example project can be built with Stack in the normal way (`stack build`),
+and the built executable can then be executed in the Stack environment in the
+normal way (`stack exec c-example-exe`).
+
 ## Flags and GHC options
 
 There are two common ways to alter how a package will install: with Cabal flags