From 7a2617b3334ae1583114a94801d64e4a93450129 Mon Sep 17 00:00:00 2001 From: Mohamad Badiezadegan Date: Mon, 28 Sep 2026 21:41:46 -0700 Subject: [PATCH] docs: add DragonFlyBSD compilation guide --- docs/dragonflybsd.md | 303 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 303 insertions(+) create mode 100644 docs/dragonflybsd.md diff --git a/docs/dragonflybsd.md b/docs/dragonflybsd.md new file mode 100644 index 000000000..0d461e767 --- /dev/null +++ b/docs/dragonflybsd.md @@ -0,0 +1,303 @@ +# Compiling and Running QuEST on DragonFlyBSD + +## Step-by-step tutorial for QuEST 4.x, GCC 13, and OpenMP + +This tutorial documents the installation path successfully tested with +**QuEST 4.3.0 on DragonFlyBSD**. It includes the DragonFlyBSD-specific +fixes needed for the C example linker and the GCC 13 C++ runtime. + +## 1. Install the required build tools + +Update the package database and install Git, CMake, GNU Make, GCC 13, +and `pkgconf`: + +``` csh +sudo pkg update +sudo pkg install git cmake gmake gcc13 pkgconf +rehash +``` + +Verify the tools: + +``` csh +git --version +cmake --version +gmake --version +gcc13 --version +g++13 --version +``` + +## 2. Download QuEST + +Clone the official QuEST repository: + +``` csh +cd ~ +git clone https://github.com/QuEST-Kit/QuEST.git +cd QuEST +``` + +For reproducibility, record the exact revision: + +``` csh +git rev-parse HEAD +git describe --tags --always +``` + +## 3. Create a clean build directory + +``` csh +cd ~/QuEST +rm -rf build +mkdir build +cd build +``` + +## 4. Configure QuEST for GCC 13 and OpenMP + +Use QuEST's current CMake option names: + +``` csh +cmake .. \ + -DCMAKE_C_COMPILER=/usr/local/bin/gcc13 \ + -DCMAKE_CXX_COMPILER=/usr/local/bin/g++13 \ + -DQUEST_ENABLE_OMP=ON \ + -DQUEST_ENABLE_MPI=OFF \ + -DQUEST_ENABLE_CUDA=OFF \ + -DQUEST_BUILD_EXAMPLES=ON \ + -DCMAKE_BUILD_TYPE=Release +``` + +A successful configuration should report multithreading as ON and +MPI/distribution and CUDA as OFF. + +You may see: + +``` text +libnuma not found, QuEST will not be aware of numa locality +``` + +This was only a warning in the tested DragonFlyBSD configuration and did +not prevent QuEST from compiling or running. + +## 5. Determine the CPU count + +DragonFlyBSD commonly uses `csh`/`tcsh`. Check the number of visible +CPUs: + +``` csh +sysctl -n hw.ncpu +``` + +If it reports `2`: + +``` csh +gmake -j2 +``` + +If it reports `8`: + +``` csh +gmake -j8 +``` + +A csh-compatible automatic form is: + +``` csh +gmake -j`sysctl -n hw.ncpu` +``` + +Avoid Bash-style `$(...)` command substitution in `csh`/`tcsh`. + +## 6. Compile QuEST + +For the tested 2-vCPU system: + +``` csh +gmake -j2 +``` + +The QuEST library successfully reached: + +``` text +[94%] Linking CXX shared library libQuEST.so +[94%] Built target QuEST +``` + +## 7. Handle the DragonFlyBSD C-example linker issue + +On the tested system, CMake attempted to link `min_example.c` with +`gcc13`, but `libQuEST.so` contains C++ code and requires the C++ +runtime. + +The build failed with a GLIBCXX-related unresolved symbol even though +the QuEST library itself had already compiled. + +From `~/QuEST/build`, manually link the generated C object with `g++13`: + +``` csh +/usr/local/bin/g++13 \ + CMakeFiles/min_example.dir/examples/tutorials/min_example.c.o \ + -o min_example \ + ./libQuEST.so.4.3.0 +``` + +Confirm that the executable exists: + +``` csh +ls -l min_example +``` + +## 8. Verify the GCC 13 C++ runtime + +Find GCC 13's `libstdc++`: + +``` csh +/usr/local/bin/g++13 -print-file-name=libstdc++.so.6 +``` + +Verify that the tested library contains the required symbol version: + +``` csh +strings /usr/local/lib/gcc13/libstdc++.so.6 | grep GLIBCXX_3.4.32 +``` + +The successful test returned: + +``` text +GLIBCXX_3.4.32 +``` + +## 9. Set the runtime library path + +The tested DragonFlyBSD environment initially loaded GCC 11's +`libstdc++`, even though QuEST had been compiled with GCC 13. + +Set the runtime path to GCC 13 and the QuEST build directory: + +``` csh +setenv LD_LIBRARY_PATH /usr/local/lib/gcc13:/home/user/QuEST/build +``` + +Replace `/home/user` if your home directory is different. + +## 10. Verify dynamic library resolution + +Run: + +``` csh +ldd ./min_example +``` + +The important entries should resolve similarly to: + +``` text +libQuEST.so.4 => /home/user/QuEST/build/libQuEST.so.4 +libstdc++.so.6 => /usr/local/lib/gcc13/libstdc++.so.6 +libgomp.so.1 => /usr/local/lib/gcc13/libgomp.so.1 +``` + +`libgomp` is the GNU OpenMP runtime used for CPU multithreading. + +## 11. Run QuEST + +``` csh +./min_example +``` + +In the successful DragonFlyBSD test, QuEST created a 20-qubit +state-vector simulation with 1,048,576 amplitudes using 16 MiB. + +The output ended with: + +``` text +Total probability: 1 +``` + +This confirms successful execution and a normalized quantum state. + +## 12. Test OpenMP multithreading + +One thread: + +``` csh +setenv OMP_NUM_THREADS 1 +./min_example +``` + +Two threads: + +``` csh +setenv OMP_NUM_THREADS 2 +./min_example +``` + +Check the CPU count before choosing larger thread counts: + +``` csh +sysctl -n hw.ncpu +``` + +## Troubleshooting summary + + ----------------------------------------------------------------------- + Symptom Action + ----------------------------------- ----------------------------------- + `Illegal variable name` with Use an explicit `-jN` or csh + `gmake -j$(...)` backticks. + + `libnuma not found` Warning only in the tested CPU + build. + + Undefined C++ / GLIBCXX symbol Link the generated object with + while linking `min_example` `g++13`. + + `GLIBCXX_3.4.32 not found` at Ensure `/usr/local/lib/gcc13` is + runtime first in `LD_LIBRARY_PATH`. + + `libQuEST.so` cannot be found Add `~/QuEST/build` to + `LD_LIBRARY_PATH` and verify with + `ldd`. + ----------------------------------------------------------------------- + +## Quick command reference + +``` csh +sudo pkg update +sudo pkg install git cmake gmake gcc13 pkgconf +rehash + +cd ~ +git clone https://github.com/QuEST-Kit/QuEST.git +cd QuEST + +rm -rf build +mkdir build +cd build + +cmake .. \ + -DCMAKE_C_COMPILER=/usr/local/bin/gcc13 \ + -DCMAKE_CXX_COMPILER=/usr/local/bin/g++13 \ + -DQUEST_ENABLE_OMP=ON \ + -DQUEST_ENABLE_MPI=OFF \ + -DQUEST_ENABLE_CUDA=OFF \ + -DQUEST_BUILD_EXAMPLES=ON \ + -DCMAKE_BUILD_TYPE=Release + +sysctl -n hw.ncpu +gmake -j2 + +/usr/local/bin/g++13 \ + CMakeFiles/min_example.dir/examples/tutorials/min_example.c.o \ + -o min_example \ + ./libQuEST.so.4.3.0 + +setenv LD_LIBRARY_PATH /usr/local/lib/gcc13:/home/user/QuEST/build +ldd ./min_example +./min_example +``` + +## Result + +**Successfully tested configuration:** DragonFlyBSD + GCC/G++ 13.3 + +QuEST 4.3.0 + OpenMP/libgomp + CPU state-vector simulation.