Debugging

This page provides insight into debugging of yaramod.

Debugging Python bindings

Sometimes, there might be something wrong with your Python code and you want to debug it. Approaching debugging Python bindings of Yaramod is not that straightforward but not difficult nor impossible. Follow this guide in order to debug C++ yaramod code in your Python code.

1. Install gdb if you haven't already.
2. Build yaramod in either RelWithDebInfo or Debug mode. RelWithDebInfo will run as fast as Release but on top of that, it'll provide you general information about symbols. Sometimes it might not show you some specific values (you'll only see <optimized out>) or stepping through the debugger might skip some lines. Debug will be much more slow but it'll provide you complete information about all values in your debugging session. Pick which one suits your needs the most at the moment. We'll also build it with YARAMOD_PYTHON option set to ensure that our Python bindings will get built in the process.

   mkdir build
   cd build
   cmake -DCMAKE_BUILD_TYPE=<RelWithDebInfo|Debug> -DYARAMOD_PYTHON=1 ..
   cmake --build . -- -j
   

3. Create virtual environment (for example using venv) in which you'll run your script. Activate this environment.

   python3 -m venv <PATH_TO_ENV_DIR>
   source <PATH_TO_ENV_DIR>/bin/activate
   

4. Go to build/src/python/ directory. There, you'll find yaramod.cpython-<PYTHON_VERSION>-x86_64-linux-gnu.so. Copy this file over to <PATH_TO_ENV_DIR>/lib64/python<VERSION>/site-packages/.
5. If you run python now and do import yaramod, it shouldn't fail.
6. If your debugging will depend on Python symbols too, I would suggest now also installing debug symbols for your Python. It can vary from distro to distro on how to do it, for example on DEB-based distros it usually involves installing python3-dbg package, on RPM-based distros it's usually done by dnf debuginfo-install python3. Look up on the Internet how it's done on your distro.
7. Run gdb python <YOUR_SCRIPT>.py. If you try to put breakpoint into yaramod source code, you'll be prompted whether to defer applying of this breakpoint because the source code was not found. Just choose yes. This happens because Python does not preload modules but rather loads them only when they are requested via import. So your yaramod.cpython-<PYTHON_VERSION>-x86_64-linux-gnu.so will get loaded only after import yaramod is encountered.