Merge pull request #5832 from commercialhaskell/stable

Stable

Author: mpilgrem

doc/install_and_upgrade.md

@@ -114,6 +114,34 @@ see the linked FAQ entries:
 If you are on macOS 10.12 (Sierra) and encounter GHC panic while building, see
 this [issue](https://github.com/commercialhaskell/stack/issues/2577)
 
+
+On Apple silicon chip (AArch64/ARM64) architectures, the installation of Stack
+or some packages (e.g. `network`) requiring C source compilation might fail with
+`configure: error: C compiler cannot build executables`. In that case you should
+pass `-arch arm64` as part of the `CFLAGS` environment variable. This setting
+will be picked up by the C compiler of your choice.
+
+```bash
+# Assuming BASH below
+
+# passing CFLAGS in-line with the command giving rise to the error
+CFLAGS="-arch arm64 ${CFLAGS:-}" some_command_to_install_stack
+CFLAGS="-arch arm64 ${CFLAGS:-}" stack [build|install]
+
+# -- OR --
+
+# ~/.bash_profile
+# NOTE: only do this if you do not have to cross-compile, or remember to unset
+# CFLAGS when needed
+export CFLAGS="-arch arm64 ${CFLAGS:-}"
+```
+
+The setting instructs the C compiler to compile objects for ARM64. These can
+then be linked with libraries built for ARM64. Without the instruction, the C
+compiler, invoked by Cabal running in x86-64, would compile x86-64 objects and
+attempt to link them with existing ARM64 libraries, resulting in the error
+above.
+
 ## Ubuntu
 
 Use the [generic Linux option](#linux).