From c133b7a540c6c99760f177c67dff386edfba1804 Mon Sep 17 00:00:00 2001
From: Tom Byers <tombaromba@gmail.com>
Date: Fri, 30 Jul 2021 14:34:11 +0100
Subject: [PATCH] Add note on ffi issue to README

Users of apps consuming this gem and running on OSX Mohave (10.14) can experience an issue with the ffi gem.

This adds a note to the README listing fixes for the issue.

See https://github.com/alphagov/tech-docs-gem/issues/254 for related discussion.
---
 README.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/README.md b/README.md
index cd198a77..274dc35d 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,8 @@ gem 'govuk_tech_docs', path: '../tech-docs-gem'
 
 To preview your documentation changes locally, see the [Tech Docs Template documentation on previewing your documentation](https://tdt-documentation.london.cloudapps.digital/create_project/preview/#preview-your-documentation).
 
+If you experience [this issue](https://github.com/alphagov/tech-docs-gem/issues/254), possible fixes can be found [here](#issue-with-ffi-on-osx-mohave).
+
 ### Use the example in this repo
 
 To start the example in this repo, run:
@@ -46,6 +48,8 @@ bundle exec middleman server
 
 See your website on `http://localhost:4567` in your browser.
 
+If you experience [this issue](https://github.com/alphagov/tech-docs-gem/issues/254), possible fixes can be found [here](#issue-with-ffi-on-osx-mohave).
+
 For more information on previewing your documentation locally, see the [Tech Docs template documentation on previewing your documentation](https://tdt-documentation.london.cloudapps.digital/create_project/preview/#preview-your-documentation).
 
 ## Tests
@@ -63,6 +67,16 @@ To run the tests and see the results in your terminal, run:
 bundle exec rake jasmine:ci
 ```
 
+## Issue with FFI on OSX Mohave
+
+Users on OSX Mohave (10.14) may get this error when running `bundle exec middleman serve` on apps that use this gem.
+
+There are 3 different ways to solve this, depending on what is possible for you. Listed here as best to worst:
+
+1. upgrade to macOS 10.15 (Catalina) or higher
+2. tell rubygems not to use the system ffi (gem inst ffi -- --disable-system-libffi)
+3. pin the ffi version back to 1.12.2 in the Gemfile of your app
+
 ## Releasing new versions
 
 To release a new version, create a new pull request (PR) that updates [version.rb](lib/govuk_tech_docs/version.rb) and [CHANGELOG.md](CHANGELOG.md).