From e031ebd9c18be1a4fc7f37ab193b4b158b92dd9a Mon Sep 17 00:00:00 2001
From: Flash Sheridan <flash@pobox.com>
Date: Sun, 29 Oct 2023 06:52:22 -0400
Subject: [PATCH] Friendlier CMake output and ReadMe tips (#949)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Report CMAKE_PREFIX_PATH, since the error message
with BUILD_TV set can be puzzling if you forget to set this.

* ReadMe:  CMake may look in /opt/

CMake’s find_package() “searches well-known locations” for configuration information, which can be a nightmare for those of us who have ever had to run an ill-behaved build script, even if we renamed the result, it is not in $PATH, and thought we were safe: https://cmake.org/cmake/help/latest/guide/using-dependencies/index.html#using-pre-built-packages-with-find-package

* Less output for long Lit test

`llvm-lit -s` rather than `-vv` for thousands of tests.

* Detecting unsound transformations in a local run

* README.md CMake advice

Check the “LLVMConfig.cmake” and “CMAKE_PREFIX_PATH” output.

* Painful lessons trying to build for our 15.0.4 fork

* Tightly coupled to LLVM top of tree source:  E.g., the source ca. 15.0.7 was broken for our 15.0.4 fork, due to LLVM f09cf34d00 moving Triple.h ⇒ Alive2 805cf71032e00.
* Experiment with Clang versions and vendors: I couldn’t compile alive2/ir/memory.h:90 with Homebrew Clang 16.0.5, but (surprisingly) could with Apple clang-1400.0.29.202, which is normally worse on open source projects.  This may have been LLVM bug 32386.

* Troubleshooting tip about `BUILD_SHARED_LIBS`

Troubleshooting tip about `BUILD_SHARED_LIBS` with `USEDLIBS` and `LLVMLIBS` and perhaps `dd_llvm_target`.  The first two are from https://llvm.org/docs/Projects.html#variables-for-building-programs. I got further, but not far enough, in linking when I supplemented `dd_llvm_target` with conditional `link_libraries`.
---
 CMakeLists.txt |  1 +
 README.md      | 28 +++++++++++++++++++++++-----
 2 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 72412150e..9cd1fc955 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -166,6 +166,7 @@ if (BUILD_LLVM_UTILS OR BUILD_TV)
   find_package(LLVM REQUIRED CONFIG)
 
   message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
+  message(STATUS "CMAKE_PREFIX_PATH: ${CMAKE_PREFIX_PATH}")
   message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")
 
   if (NOT LLVM_ENABLE_RTTI)
diff --git a/README.md b/README.md
index ddd28f75a..6e825bede 100644
--- a/README.md
+++ b/README.md
@@ -119,11 +119,15 @@ To run translation validation on all the LLVM unit tests for IR-level
 transformations:
 
 ```
-$LLVM2_BUILD/bin/llvm-lit -vv -Dopt=$ALIVE2_HOME/alive2/build/opt-alive.sh $LLVM2_HOME/llvm/test/Transforms
+$LLVM2_BUILD/bin/llvm-lit -s -Dopt=$ALIVE2_HOME/alive2/build/opt-alive.sh $LLVM2_HOME/llvm/test/Transforms
 ```
 
 We run this command on the main LLVM branch each day, and keep track of the results
-[here](https://web.ist.utl.pt/nuno.lopes/alive2/).
+[here](https://web.ist.utl.pt/nuno.lopes/alive2/).  To detect unsound transformations in a local run:
+
+```
+fgrep -r "(unsound)" $ALIVE2_HOME/alive2/build/logs/
+```
 
 
 Running Alive2 as a Clang Plugin
@@ -307,11 +311,25 @@ should be the only user of this server.
 
 Troubleshooting
 --------
-Some combinations of Clang and MacOS versions may give link warnings 
+* Check the “LLVMConfig.cmake” and “CMAKE_PREFIX_PATH” output from CMake in
+case of build problems. CMake may look for configuration information in old
+installations of LLVM, e.g., under `/opt/`, if these are not set properly.
+* Some combinations of Clang and MacOS versions may give link warnings 
 “-undefined dynamic_lookup may not work with chained fixups,” and
 runtime errors with “symbol not found in flat namespace.”  Setting
-[CMAKE_OSX_DEPLOYMENT_TARGET](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_DEPLOYMENT_TARGET.html) as a cache entry to 11.0
-or less at the beginning of CMakeLists.txt may work around this. 
+[CMAKE_OSX_DEPLOYMENT_TARGET](https://cmake.org/cmake/help/latest/variable/
+CMAKE_OSX_DEPLOYMENT_TARGET.html) as a cache entry to 11.0
+or less at the beginning of CMakeLists.txt may work around this.
+* Building for Translation Validation requires enabling `BUILD_SHARED_LIBS`. 
+For LLVM forks not normally built with the option, this may interfere with
+CMake files’ use of `USEDLIBS` and `LLVMLIBS` and perhaps `dd_llvm_target`. 
+* Building for Translation Validation is tightly coupled to LLVM top of tree
+source.  Building a fork with older source may require reverting to the
+corresponding Alive2 commit.  This in turn may require experimentation with
+Clang versions and vendors.
+* Building older source on an up-to-date machine may require adjustments.  For
+example, the now-deleted file `scripts/rewritepass.py` depended on the
+deprecated Python 2; update the shebang line to `python3`.
 
 LLVM Bugs Found by Alive2
 --------