Add relevant info for MacOS building process (#1176)

INSTALL.md

@@ -30,7 +30,7 @@ python3 -m pip install pybind11 lit
 ```
 
 ## macOS / Homebrew
-
+In order to install the dependencies on macOS, you must have Homebrew installed and on your `PATH`.
 ```shell
 brew update
 brew install  \
@@ -40,19 +40,70 @@ brew install  \
   fmt         \
   git         \
   gmp         \
+  grep        \
   jemalloc    \
+  libffi
   libyaml     \
   llvm@15     \
   maven       \
   mpfr        \
   pkg-config  \
   python3     \
   z3
+```
+
+To ensure that the backend can use pybind11 correctly, we must create an virtual
+environment and install the `pybind11` package:
+```shell
+python3 -m venv venv
+source venv/bin/activate
 python3 -m pip install pybind11 lit
 ```
 
+Guarantee that you have the JDK installed and on your `PATH`:
+```shell
+export PATH="/opt/homebrew/opt/openjdk/bin:$PATH"
+```
+
+Some tests rely on GNU Grep options, which are not available on macOS by
+default. To ensure that the tests run correctly, you add the path of
+GNU Grep to your `PATH` in your shell profile:
+```shell
+export PATH=/opt/homebrew/Cellar/grep/3.11/libexec/gnubin/:$PATH
+```
+
 # Building
 
+## Environment Variables
+
+If you're building on macOS, type the following command or epermanently
+add it your `env` (`.zshrc`, `.bashrc`, etc.), so that the Homebrew
+installation of LLVM gets picked up correctly. We recommend adding it to
+your shell profile.
+```shell
+export LLVM_DIR=$($(brew --prefix llvm@15)/bin/llvm-config --cmakedir)
+```
+
+If you don't usually use the `clang` from your Homebrew installation as
+your default compiler, you can set the following CMake flg to use these
+`clang` and `clang++`:
+```shell
+-DCMAKE_C_COMPILER="$(brew --prefix llvm@15)/bin/clang" \
+-DCMAKE_CXX_COMPILER="$(brew --prefix llvm@15)/bin/clang++"
+```
+Once again, we recommend adding them and other llvm binaries to your
+`PATH` in your shell profile:
+```shell
+export PATH="$(brew --prefix llvm@15)/bin:$PATH"
+```
+
+Some tests rely on GNU Grep options, which are not available on macOS by
+default. To ensure that the tests run correctly, you can create an alias
+for GNU Grep:
+```shell
+alias grep=ggrep
+```
+
 Once the system dependencies have been installed, the backend can be built
 locally with:
 ```shell
@@ -66,12 +117,6 @@ cmake .. \
 make -j$(nproc) install
 ```
 
-If you're building on macOS, add the following option to your CMake invocation
-so that the Homebrew installation of LLVM gets picked up correctly.
-```shell
--DLLVM_DIR=$($(brew --prefix llvm@15)/bin/llvm-config --cmakedir)
-```
-
 Additionally, to build the pattern-matching compiler, run:
 ```shell
 cd matching
@@ -91,7 +136,8 @@ To run the integration tests, run:
 ```shell
 lit test
 ```
-from the root source directory.
+from the root source directory. You can use `-v` to see which test is being executed
+and the output of failling tests.
 
 There is also a unit test suite for backend internals;
 Add the following option to your CMake invocation to enable it:
@@ -113,7 +159,7 @@ and conform to best practices.
 
 ```shell
 # Ubuntu
-apt install shellcheck clang-format-12 iwyu
+apt install shellcheck clang-format-15 iwyu
 
 # macOS
 brew install shellcheck clang-format iwyu

cmake/FixHomebrew.cmake

@@ -20,5 +20,15 @@ if(APPLE)
     include_directories(AFTER SYSTEM "${BREW_PREFIX}/include")
     link_directories(AFTER "${BREW_PREFIX}/lib")
     set(ENV{PKG_CONFIG_PATH} "${BREW_PREFIX}/opt/libffi/lib/pkgconfig")
+
+    # Use LLD as the linker
+    # This is necessary as the default linker used by CMake on macOS is
+    # ld64, which currently has some incompatibilities with Homebrew and XCode15.
+    # See: https://github.com/orgs/Homebrew/discussions/4794#discussioncomment-7044468
+    # Adding this flag avoid the following errors:
+    # ld: warning: duplicate -rpath ... ignored
+    # ld: warning: ignoring duplicate libraries ...
+    add_link_options("-fuse-ld=lld")
+
   endif() # USE_NIX
 endif() # APPLE