diff --git a/guides/advanced/customizing-systems.md b/guides/advanced/customizing-systems.md
index a5c963e0..a941af2d 100644
--- a/guides/advanced/customizing-systems.md
+++ b/guides/advanced/customizing-systems.md
@@ -420,3 +420,14 @@ You can also use the GitHub interface to do this:
 ```text
 https://github.com/YourGitHubUserName/custom_rpi3/compare/main...nerves-project:main?expand=1
 ```
+
+## Building Systems on macOS
+
+The primary Apple File System (APFS) volume on Macs is case-insensitive, but the Nerves filesystem is case-sensitive. This can cause filename conflicts when including some packages.
+
+To get around this limitation, use Disk Utility to create a new volume with the format "APFS (Case-sensitive)". Then set the following [environment variables](environment-variables.md) so that Nerves will use the new volume (named "Nerves" in this example):
+
+```sh
+export XDG_DATA_HOME='/Volumes/Nerves'
+export TMPDIR='/Volumes/Nerves/tmp'
+```
diff --git a/guides/advanced/environment-variables.md b/guides/advanced/environment-variables.md
index b622f091..ffa54bb2 100644
--- a/guides/advanced/environment-variables.md
+++ b/guides/advanced/environment-variables.md
@@ -17,6 +17,7 @@ device-specific code.
 | `NERVES_DEBUG`                    | Set to `1` to print out debug info during compilation |
 | `NERVES_LOG_DISABLE_PROGRESS_BAR` | Set to `1` to disable progress bar output when fetching artifacts (typically for CI) |
 | `SOURCE_DATE_EPOCH`               | Used for [reproducable builds](https://reproducible-builds.org). Can also be set via `config :nerves, source_date_epoch: val` |
+| `TMPDIR`                          | Root directory for temporary files. Usually already set by the shell.  |
 
 ## Nerves-provided environment variables