Merge pull request #359 from lamech/master

Provide simple MacOS build instructions.

readme-macos.txt

@@ -0,0 +1,52 @@
+To install on MacOS (tested on an M2 Macbook Pro in 2023 under MacOS Monerey):
+
+1. Popeye's build system requires an up-to-date `clang`, `ld` etc. which are not provided by Apple by default.
+
+```
+$ brew install llvm
+```
+
+2. Either copy the following lines into your .zshrc to point at the newly installed tools, or execute the following commands in a shell where you will be building Popeye:
+
+```
+export PATH="/opt/homebrew/opt/llvm/bin:$PATH"
+export LDFLAGS="-L/opt/homebrew/opt/llvm/lib"
+export CPPFLAGS="-I/opt/homebrew/opt/llvm/include" 
+```
+
+3. At the top level of the Popeye source code distribution, edit `makefile.defaults`. Find the line that says `TOOLCHAIN` and ensure it is pointing at `clang`:
+
+```
+TOOLCHAIN=clang
+```
+
+4. Now simply run `make -f makefile.unx`, which, after compiling and linking 500-odd source files, should result in a working Popeye binary called `py` in the current directory.
+
+5. (Optional: basic testing) Launch `py` with no arguments. It should display the following header (or some variation, depending on your MacOS version):
+
+`Popeye Darwin-21.6.0-arm-64Bit v4.87 (1024 MB)`
+
+Now paste the following into the terminal:
+
+```
+BeginProblem
+Stipulation #2
+Option Variation NoBoard
+Pieces
+    White Rb8 Kb3
+    Black Kb1
+EndProblem
+```
+
+Popeye should respond by solving the problem, then exiting with no errors:
+
+```
+   1.Rb8-c8 ! zugzwang.
+      1...Kb1-a1
+          2.Rc8-c1 #
+
+
+solution finished. Time = 0.018 s
+```
+
+6. (Optional: comprehensive testing) Run any of the self-test scripts (`solveExamples.sh` is quite comprehensive, for instance) to confirm all functionality works.