Skip to content

build.md

Latest commit

 

History

History
99 lines (71 loc) · 4.48 KB

build.md

File metadata and controls

99 lines (71 loc) · 4.48 KB
Raw

Building

  • Update to the latest development build of Binary Ninja

    • Follow this guide to do so

  • Clone binaryninja-api and checkout to the corresponding commit used to build the version of Binary Ninja you are running

    • If you updated to the latest dev build of Binary Ninja, then you can checkout the api repo to the latest dev as well
    • A more robust approach is to find the file api_REVISION.txt in BN_INSTALLATION_FOLDER/Resources
git clone --recurse-submodules https://github.com/Vector35/binaryninja-api.git
cd binaryninja-api
git checkout dev
# or git checkout commit_hash

  • Download LLDB development build for your OS at https://github.com/Vector35/lldb-artifacts/releases/latest - make sure that the correct LLDB version is downloaded (grep 'LLVM_VERSION ' core/CMakeLists.txt can help)

    • Extract the zip archive to ~/libclang

  • Download Qt development build for your OS at https://github.com/Vector35/qt-artifacts/releases/latest.

    • Extract the zip archive to ~/Qt

  • Build the debugger

    FlatBuffers (needed for X2WinRpcAdapter's wire protocol) is vendored as a git submodule under vendor/ and built as part of this project's own CMake configure/build -- no separate install step needed, just make sure submodules are cloned (--recurse-submodules below, or git submodule update --init --recursive after the fact).

# Get the source
git clone --recurse-submodules https://github.com/Vector35/debugger.git

# Do an out-of-source build
mkdir -p build
cd build

# Build it
cmake -DBN_API_PATH=../binaryninja-api -DBN_INSTALL_DIR=/path/to/binaryninja/installation ..

make

While the code is compiling, it's a good time to check the Binary Ninja slack for any updates!

The build artifacts will be in the folder out. You should find two files libdebuggercore and libdebuggerui, and two folders debugger (that contains the Python code) and lldb.

  • Run the debugger
    • Open Binary Ninja, disable the setting corePlugins.debugger so the debugger that comes with Binary Ninja is not loaded
    • Close Binary Ninja
    • Copy everything in the out folder to the user plugin folder - cp -r out/plugins/* ~/.binaryninja/plugins/
    • Set the environment variable BN_STANDALONE_DEBUGGER=1
    • Launch BinaryNinja

Standalone CI builds

The debugger's Jenkinsfile-dev and Jenkinsfile-test use mise to install the Python, uv, CMake, and Ninja versions pinned in mise.toml and mise.lock. Each worker trusts the checked-out configuration and installs the locked tools under the shared mise-install-<node> lock before building.

After CI stages the Binary Ninja, Qt, and LLDB archives in artifacts-extern, it runs:

mise run build

The build task installs the locked Python dependencies into the debugger's .venv, then runs scripts/build.py with Python 3.12.13 to build, package, and test the standalone debugger. Visual Studio and the platform SDKs are still supplied by the worker.

Developer builds can use the CMake workflow above or mise run build with the same staged artifacts as CI.

Windows Remote Debug Server

Windows builds include windows-debug-server.exe for Windows user-mode remote debugging from Linux, macOS, or Windows. It is built and packaged with the debugger; it is not built on Linux or macOS. To build just the server from an already configured Windows build directory, run:

cmake --build build --config RelWithDebInfo --target x2winstub

The internal CMake target remains x2winstub, but the executable is named windows-debug-server.exe. In a standalone Ninja build it is under build/out/plugins; multi-configuration generators such as Visual Studio place it under build/out/plugins/RelWithDebInfo. Internal Binary Ninja builds place it in BN_CORE_PLUGIN_DIR. The Windows package includes the executable in its plugins directory. Copy it to the Windows host to run it; running the server does not require installing Binary Ninja there.

See the Windows Remote guide for connection and launch steps, and integration test instructions for testing it locally on Windows.

Notes:

  • On Windows, building the debugger in Debug mode may cause obscure bugs since the debug ABI of MSVC can be different from that of the release build. It is recommended to build with RelWithDebInfo on Windows.