From 4660f2178ff8cc69a94f738150c39eabf264eabf Mon Sep 17 00:00:00 2001
From: Artem Dinaburg <artem@trailofbits.com>
Date: Wed, 13 Jan 2021 12:54:12 -0500
Subject: [PATCH] Update README (#470)

* Update README to show how to do full source builds using VCPKG and explain how to solve a frustrating build issue

* Explain how to disable building SPARC32 runtime semantics

Co-authored-by: Eric Kilmer <eric.d.kilmer@gmail.com>
---
 CMakeLists.txt                  |  1 +
 README.md                       | 40 +++++++++++++++++++++++++++++++++
 lib/Arch/SPARC32/CMakeLists.txt |  4 +++-
 3 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 7d122adb5..4a126d2dc 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -167,6 +167,7 @@ endif()
 # Configuration options for semantics
 #
 option(REMILL_BARRIER_AS_NOP "Remove compiler barriers (inline assembly) in semantics" OFF)
+option(REMILL_BUILD_SPARC32_RUNTIME "Build the Runtime for SPARC32. Turn this off if you have include errors with <bits/c++config.h>, or read the README for a fix" ON)
 
 #
 # target settings
diff --git a/README.md b/README.md
index 501b380a4..6aecd5b13 100644
--- a/README.md
+++ b/README.md
@@ -138,3 +138,43 @@ cd ./remill-build
 make test_dependencies
 make test
 ```
+
+### Full Source Builds
+
+Sometimes, you want to build everything from source, including the [cxx-common](https://github.com/trailofbits/cxx-common) libraries remill depends on. To build against a custom cxx-common location, you can use the following `cmake` invocation:
+
+```sh
+mkdir build
+cd build
+cmake  \
+  -DCMAKE_INSTALL_PREFIX="<path where remill will install>" \
+  -DVCPKG_ROOT="<path to cxx-common directory>/vcpkg"  \
+  -G Ninja  \
+  ..
+cmake --build .
+cmake --build . --target install
+```
+
+The output may produce some CMake warnings about policy CMP0003. These warnings are safe to ignore.
+
+### Common Build Issues
+
+If you see errors similar to the following:
+
+```
+fatal error: 'bits/c++config.h' file not found
+```
+
+Then you need to install 32-bit libstdc++ headers and libraries. On a Debian/Ubuntu based distribution, You would want to do something like this:
+
+```sh
+sudo dpkg --add-architecture i386
+sudo apt-get update
+sudo apt-get install libc6-dev:i386 install libstdc++-10-dev:i386 g++-multilib
+```
+
+This error happens because the SPARC32 runtime semantics (the bitcode library which lives in `<install directory>/share/remill/<version>/semantics/sparc32.bc`) are built as 32-bit code, but 32-bit development libraries are not installed by default.
+
+A similar situation occurs when building remill on arm64 Linux. In that case, you want to follow a similar workflow, except the architecture used in `dpkg` and `apt-get` commands  would be `armhf` instead of `i386`.
+
+Another alternative is to disable SPARC32 runtime semantics. To do that, use the `-DREMILL_BUILD_SPARC32_RUNTIME=False` option when invoking `cmake`.
diff --git a/lib/Arch/SPARC32/CMakeLists.txt b/lib/Arch/SPARC32/CMakeLists.txt
index 4929f4577..e6edb48bd 100644
--- a/lib/Arch/SPARC32/CMakeLists.txt
+++ b/lib/Arch/SPARC32/CMakeLists.txt
@@ -29,7 +29,9 @@ add_library(remill_arch_sparc32 STATIC
   Extract.cpp
 )
 
-add_subdirectory(Runtime)
+if(${REMILL_BUILD_SPARC32_RUNTIME})
+  add_subdirectory(Runtime)
+endif()
 
 set_property(TARGET remill_arch_sparc32 PROPERTY POSITION_INDEPENDENT_CODE ON)