Import content from the manual, add build instructions

PiperOrigin-RevId: 385492515
Change-Id: Ida57a7d243227b589ffb7b20126f88a8f92e6f88

.gitignore

@@ -0,0 +1,15 @@
+# Editor backup files/IDE files
+*~
+.*.swp
+.*.swo
+
+# IDEs
+.cache/
+.clangd/
+.idea/
+.vscode/
+compile_commands.json
+
+# Build artifacts
+build/
+java/ui/build/

README.md

@@ -10,13 +10,14 @@ in disassembled code.
 
 ## Table of Contents
 
-- [About BinDiff](#about)
+- [About BinDiff](#about-bindiff)
 - [Quickstart](#quickstart)
+- [Documentation](#documentation)
 - [Codemap](#codemap)
+- [Building from Source](#building-from-source)
 - [License](#license)
-- [Getting Involved](#contributing)
+- [Getting Involved](#getting-involved)
 
-<a name="about"></a>
 ## About BinDiff
 
 BinDiff is an open-source comparison tool for binary files, that assists
@@ -32,17 +33,25 @@ results and enables knowledge transfer among binary analysts.
 ### Use Cases
 
 * Compare binary files for x86, MIPS, ARM, PowerPC, and other architectures
-  supported by the IDA Pro, Binary Ninja or Ghidra disassemblers
+  supported by popular [disassemblers](docs/disassemblers.md).
 * Identify identical and similar functions in different binaries
 * Port function names, comments and local names from one disassembly to the
   other
 * Detect and highlight changes between two variants of the same function
 
 ## Quickstart
 
-If you want to just get started using BinDiff, you download prebuilt
-installation packages from the
-[release page](https://github.com/google/binexport/releases).
+If you want to just get started using BinDiff, download prebuilt installation
+packages from the
+[releases page](https://github.com/google/bindiff/releases).
+
+Note: BinDiff relies on a separate disassembler. Out of the box, it ships with
+support for IDA Pro, Binary Ninja and Ghidra. The [disassemblers page](docs/disassemblers.md) lists the supported configurations.
+
+## Documentation
+
+A subset of the existing [manual](https://www.zynamics.com/bindiff/manual) is
+available in the [`docs/` directory](docs/README.md).
 
 ## Codemap
 
@@ -58,6 +67,102 @@ BinDiff contains the following components:
 * [`packaging`](packaging) - Package sources for the installation packages
 * [`tools`](tools) - Helper executables that are shipped with the product
 
+## Building from Source
+
+The instruction below should be enough to build both the native code and the
+Java based components.
+
+More detailed build instructions will be added at a later date. This includes
+ready-made `Dockerfile`s and scripts for building the installation packages.
+
+### Native code
+
+BinDiff uses CMake to generate its build files for those components that consist
+of native C++ code.
+
+The following build dependencies are required:
+
+*   [BinExport](https://github.com/google/binexport) 12, the companion plugin
+    to BinDiff that also contains a lot of shared code
+*   Boost 1.71.0 or higher (a partial copy of 1.71.0 ships with BinExport and
+    will be used automatically)
+*   [CMake](https://cmake.org/download/) 3.14 or higher
+*   [Ninja](https://ninja-build.org/) for speedy builds
+*   GCC 9 or a recent version of Clang on Linux/macOS. On Windows, use the
+    Visual Studio 2019 compiler and the Windows SDK for Windows 10.
+*   Git 1.8 or higher
+*   IDA Pro only: IDA SDK 7.6 (unpack into `deps/idasdk`)
+*   Dependencies that will be downloaded:
+    *   Abseil, GoogleTest, Protocol Buffers (3.14), and SQLite3
+    *   Binary Ninja SDK
+
+The general build steps are the same on Windows, Linux and macOS. The following
+shows the commands for Linux.
+
+Download dependencies that won't be downloaded automatically:
+
+```bash
+mkdir -p build/out
+git clone https://github.com/google/binexport build/binexport
+unzip -q <path/to/idasdk76.zip> -d -d build/
+```
+
+Next, configure the build directory and generate build files:
+
+```bash
+cmake -S . -B build/out -G Ninja \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DCMAKE_INSTALL_PREFIX=build/out \
+  -DBINDIFF_BINEXPORT_DIR=build/binexport \
+  "-DIdaSdk_ROOT_DIR=${PWD}build/idasdk76"
+```
+
+Finally, invoke the actual build. Binaries will be placed in
+`build/out/bindiff-prefix`:
+
+```bash
+cmake --build build/out --config Release
+(cd build/out; ctest --build-config Release --output-on-failure)
+cmake --install build/out --config Release
+```
+
+### Java GUI and yFiles
+
+Building the Java based GUI requires the commercial third-party graph
+visualisation library [yFiles](https://www.yworks.com/products/yfiles) for graph
+display and layout. This library is immensely powerful, and not easily
+replaceable.
+
+To build, BinDiff uses Gradle 6.x and Java 11 LTS. Refer to its
+[installation guide](https://docs.gradle.org/6.8.3/userguide/installation.html)
+for instructions on how to install.
+
+Assuming you are a yFiles license holder, set the `YFILES_DIR` environment
+variable to a directory containing the yFiles `y.jar` and `ysvg.jar`.
+
+Note: BinDiff still uses the older 2.x branch of yFiles.
+
+Then invoke Gradle to download external dependencies and build:
+
+Windows:
+```
+set YFILES_DIR=<path\to\yfiles_2.15>
+cd java
+gradle shadowJar
+```
+
+Linux or macOS:
+
+```
+export YFILES_DIR=<path/to/yfiles_2.15>
+cd java
+gradle shadowJar
+```
+
+Afterwards the directory `ui/build/libs` in the `java` sub-directory should
+contain the self-contained `bindiff-ui-all.jar` artifact, which can be run
+using the standard `java -jar` command.
+
 ## Further reading / Similar tools
 
 The original papers outlining the general ideas behind BinDiff:
@@ -74,13 +179,13 @@ Other tools in the same problem domain:
 
 * [Diaphora](https://github.com/joxeankoret/diaphora), an advanced program
   diffing tool implementing many of the same ideas.
+* [TurboDiff](https://www.coresecurity.com/core-labs/open-source-tools/turbodiff-cs), a now-defunct program diffing plugin for IDA Pro.
 
 ## License
 
 BinDiff is licensed under the terms of the Apache license. See
 [LICENSE](LICENSE) for more information.
 
-<a name="contributing"></a>
 ## Getting Involved
 
 If you want to contribute, please read [CONTRIBUTING.md](CONTRIBUTING.md)

docs/README.md

@@ -0,0 +1,35 @@
+![BinDiff Logo](images/bindiff-lockup-vertical.png)
+
+Copyright 2011-2021 Google LLC.
+
+# BinDiff Documentation
+
+BinDiff is a leading executable-comparison tool for reverse engineers that need
+to analyze patches, malware variants, or are generally interested in the
+differences between two executables.
+
+In order to make best use of BinDiff, it is very helpful to spend a bit of time
+familiarizing yourself with the concepts and algorithms behind it. For this, we
+recommend reading [Understanding BinDiff](concepts.md), which explains the
+behind-the-scenes and
+[Core Functionality](https://www.zynamics.com/bindiff/manual/#chapCoreFunc),
+which explains the basic elements of the user interface.
+
+Ideally, we would like you to also read
+[Analyzing a Microsoft Patch](https://www.zynamics.com/bindiff/manual/#chapWalkthrough)
+(a walk-through demonstrating how to analyze a simple security update) and
+[Advanced Usage](https://www.zynamics.com/bindiff/manual/#N20AB6)
+(porting your symbols and comments from one disassembly to the next).
+
+*This documentation is a work in progress and not everything from the original
+manual has been ported over.*
+
+## Table of Contents
+
+- [Understanding BinDiff](concepts.md)
+- [Installation](https://www.zynamics.com/bindiff/manual/#N201AE)
+- [Disassemblers](disassemblers.md)
+- [Core Functionality](https://www.zynamics.com/bindiff/manual/#chapCoreFunc)
+- [Analyzing a Microsoft Patch](https://www.zynamics.com/bindiff/manual/#chapWalkthrough)
+- [Advanced Usage](https://www.zynamics.com/bindiff/manual/#N20AB6)
+- [Version History](version-history.md)