VirtualBow

VirtualBow is a software tool for designing and simulating bows. Visit http://www.virtualbow.org for more information about the project.

Building

Solver

The solver is the part that does the numerical computations and is written in Rust. Building the solver therefore requires a Rust compiler and the Cargo build tool. Building the solver executable is as easy as running cargo build --release, which automatically downloads and compiles the required dependencies as well. To run the tests, use cargo test --release (the release flag helps with performance since the simulation is very slow in debug mode).

GUI

The VirtualBow GUI application built around the solver is written in C++. Building it requires, in addition to the solver requirements, CMake, a C++17 compiler and the following external dependencies:

• Qt 5.9.5
• Boost 1.79.0
• Eigen 3.4.0
• Json 3.10.5

Also used are QCustomPlot and Calculate, but those are already included with this repository. The version numbers are just the minimum needed, newer versions might work too.

Optional pre-built dependencies for the supported platforms and compilers are available at virtualbow-dependencies. They each contain a file named paths.cmake that will set up the CMAKE_PREFIX_PATH so that the libraries are found by CMake. The easiest way to use it is by setting CMAKE_TOOLCHAIN_FILE to paths.cmake in your build,

-DCMAKE_TOOLCHAIN_FILE=[dependencies]/paths.cmake

If you're using Qt Creator you can set this property under Projects - Build Settings - CMake. (If the configuration step keeps failing, try Build - Clear CMake Configuration and then run CMake again via Build - Run CMake.)

Below are some brief instructions for building on the supported platforms. When in doubt, see the CI build definitions of virtualbow and virtualbow-dependencies for how they are actually compiled for releases.

Windows

Automated portable build (recommended)

A PowerShell script handles every step automatically and produces a self-contained portable ZIP that runs on any Windows machine without installation:

Prerequisites:

• Rust + Cargo — installed and on PATH
• MSYS2 — install location auto-detected (or pass -Msys2Root, or set $env:MSYS2_ROOT)

Then run from the repository root:

powershell -ExecutionPolicy Bypass -File .\build-portable.ps1

The script will:

1. Install all required MSYS2 mingw64 packages (Qt6, GCC, Ninja, Catch2, nlohmann-json, ffmpeg)
2. Add the x86_64-pc-windows-gnu Rust target and compile the FFI bridge library
3. Configure and build the C++ GUI with CMake + Ninja
4. Run windeployqt6 to bundle Qt6 plugins
5. Copy all required MinGW and Qt runtime DLLs
6. Copy ffmpeg.exe (required for video export)
7. Produce virtualbow-portable-<version>-windows-x64.zip

The ZIP unpacks to a virtualbow/ folder with this layout:

virtualbow/
├── VirtualBow.cmd     ← double-click to launch
└── lib/               ← exe, DLLs, Qt plugins, user manual

The launcher starts the GUI from inside lib/ so Windows finds DLLs and Qt plugins next to the executable — no installer, no PATH edits, no admin rights.

Optional flags:

Flag	Effect
-SkipRustBuild	Skip rebuilding the Rust FFI library
-SkipCppBuild	Skip reconfiguring and rebuilding the C++ GUI
-OutputDir <path>	Directory for the output ZIP (default: repository root)
-Msys2Root <path>	Override MSYS2 install location

Developer (incremental) build

For day-to-day development:

.\build-dev.ps1                          # build virtualbow-gui (default)
.\build-dev.ps1 -Target virtualbow-test  # build the test target
.\build-dev.ps1 -Reconfigure             # re-run cmake before building
.\build-dev.ps1 -Clean                   # wipe build/ and start fresh
.\build-dev.ps1 -NoInstall               # skip prereq verification

The script auto-detects MSYS2, installs any missing mingw64 packages, ensures the x86_64-pc-windows-gnu Rust target is present, then runs CMake + Ninja. See BUILDING-WINDOWS.md for details and troubleshooting.

Manual build (advanced)

Using GCC from MSYS2 (mingw64 environment) and Qt6. Replace <msys2> below with your MSYS2 install root (default: C:/msys64):

# Install dependencies (once)
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja `
          mingw-w64-x86_64-qt6-base mingw-w64-x86_64-qt6-tools `
          mingw-w64-x86_64-nlohmann-json mingw-w64-x86_64-catch

# Add the GNU Rust target (once)
rustup target add x86_64-pc-windows-gnu

# Build the Rust FFI library for GCC
cargo build --release --target x86_64-pc-windows-gnu -p virtualbow_ffi

# Build the GUI
mkdir build; cd build
cmake ../gui -G Ninja -DCMAKE_BUILD_TYPE=Release `
    -DCMAKE_PREFIX_PATH=<msys2>/mingw64 `
    -DCMAKE_C_COMPILER=<msys2>/mingw64/bin/gcc.exe `
    -DCMAKE_CXX_COMPILER=<msys2>/mingw64/bin/g++.exe
cmake --build . --target virtualbow-gui

Note: The CMakeLists.txt automatically selects the correct Rust library path: when building with MinGW it uses rust/target/x86_64-pc-windows-gnu/release/, otherwise rust/target/release/.

Building with Microsoft Visual C++ (MSVC) is supported by the CI but requires downloading the pre-built MSVC dependencies and using -DCMAKE_TOOLCHAIN_FILE=[dependencies]/paths.cmake.

Linux and MacOS

On Linux, the Qt libraries packaged with the system are used. On Ubuntu they can be installed with

sudo apt install qt6-base-dev

The rest of the build process is the same on Linux and MacOS

mkdir build && cd build
cmake ../virtualbow/gui -DCMAKE_TOOLCHAIN_FILE=[...]/paths.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build .

Contributing

Contributions of any kind are very welcome!

The development of VirtualBow is discussed and planned publicly on our issue tracker and the discussions. Feel free to participate by either commenting on existing topics or opening your own ones for feedback, new ideas, feature requests or bug reports. If you plan a larger contribution, consider discussing it with us first to make sure that it fits the scope and vision of the project.

For actually contributing to this repository please follow these steps:

1. Fork the repository and create a new branch for your changes from the latest develop branch. The branching strategy used in this repository is called Git Flow in case you want to learn more about it.

2. Implement and test your changes and add unit tests and/or documentation for your new code if applicable. The code style used in VirtualBow is not explicitly specified anywhere and not 100% consistent either. Just try to match the style of the existing/surrounding code reasonably well.

3. Create a pull request against the develop branch of this repository. Write a short summary of your changes and include any other relevant information like e.g. links to related issues or discussions.

4. Wait and see if the build pipeline passes. This automatic process ensures that the project still compiles successfully and all tests work as expected. Don't worry if this step fails initially, you can keep updating your branch with new commits until all checks have passed.

5. Sign the Contributor License Agreement. If this is your first contribution to VirtualBow, you will be asked to sign our Contributor License Agreement (CLA). This document clarifies the rights to your contribution and ensures that we can use your contribution(s) for our purposes. Our CLA is adapted from the Apache Individual Contributor License Agreement with only minor changes, so it is a fairly standard license agreement.

6. You are almost done! Your changes will now be reviewed for merging as soon as possible.

License

VirtualBow is released under the PolyForm Noncommercial License 1.0.0 and is therefore free to use for non-commercial (e.g. personal or academic) purposes.