Metadata-Version: 2.4
Name: davext
Version: 0.13.1
Summary: base module for the DAVE debugger extension
Home-page: https://github.com/maxmarsc/dave
Author: maxmarsc
Author-email: maxime.coutant@protonmail.com
License: GPLV3
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >3.10.1
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6==6.9.0
Requires-Dist: scipy==1.15.2
Requires-Dist: pyqtgraph==0.13.7
Requires-Dist: darkdetect==0.8.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


<p align="center"><b>Base python module for the DAVE project</b></p>

**Important:** It is not recommended to install DAVE directly from pypi, you
should rather use the install script as show in the "Project Setup" section.

# Debugger Audio Visualization Extension
![logo](https://media.githubusercontent.com/media/maxmarsc/dave/v0.13.1/.pictures/dave_logo_long_v6.png  )

DAVE is a GDB & LLDB extension which provide commands to visualize audio related data
directly from your process's memory. No need to recompile your code and/or instrument
it with nasty macros or fancy libs, just start your debugger !

<p align="center">
    <b> The DAVE GUI </b>
</p>
<p align="center">
    <img src="https://media.githubusercontent.com/media/maxmarsc/dave/v0.13.1/.pictures/gui_demo.png">
</p>

<p align="center">
    <b> The DAVE ascii formatters </b>
</p>

```
2 channels 256 samples, min -9.9998E-01, max 1.0000E+00 {
  dSparkline[0] = "[0⎻⎺‾⎺⎻x⎼_⎽⎼x⎺‾⎺⎻x⎽_⎽—x⎺‾⎺⎻x⎽_⎽⎼x⎺‾⎺⎻x⎽_⎽—x⎺‾⎺⎻x⎽_⎼x⎺‾⎺—x_⎽—x⎺‾⎺⎻x⎽_⎽⎼x⎺‾⎺⎻x⎽_⎽—x⎺‾⎺—x_⎼x⎺‾⎺⎻x⎽_⎽⎼x⎺‾⎺x⎽_⎽⎼x⎺‾⎺—x_⎽⎼x⎺‾⎻x⎽_⎽—x‾⎺⎻x⎽_⎼x⎺‾⎺—x_⎽—x‾⎺⎻x_⎽⎼x‾⎺⎻x_⎽⎼x‾⎺⎻x_⎽—x‾⎺—x_]"
  dSparkline[1] = "[0⎻⎺‾⎺⎻x⎼_⎽⎼x⎺‾⎺⎻x⎽_⎽—x⎺‾⎺⎻x⎽_⎽⎼x⎺‾⎺⎻x⎽_⎽—x⎺‾⎺⎻x⎽_⎼x⎺‾⎺—x_⎽—x⎺‾⎺⎻x⎽_⎽⎼x⎺‾⎺⎻x⎽_⎽—x⎺‾⎺—x_⎼x⎺‾⎺⎻x⎽_⎽⎼x⎺‾⎺x⎽_⎽⎼x⎺‾⎺—x_⎽⎼x⎺‾⎻x⎽_⎽—x‾⎺⎻x⎽_⎼x⎺‾⎺—x_⎽—x‾⎺⎻x_⎽⎼x‾⎺⎻x_⎽⎼x‾⎺⎻x_⎽—x‾⎺—x_]"
  [...]
}
```

DAVE supports plotting for different types of audio "entities" that might live in
your program's memory :
- audio sample containers (amplitude or spectral)
- IIR filters

Currently supported audio containers (both in `float` and `double`) are :

__1D (mono) containers__:
- `std::array`
- `std::vector`
- `std::span`
- [Microsoft's `gsl::span`](https://github.com/microsoft/GSL/blob/main/include/gsl/span) 
- `C array`
- `pointer`
- `choc::buffer::MonoView`
- `choc::buffer::MonoVBuffer`

__2D (multichannel) containers__:
- Any nesting of C/C++ standards 1D containers
- `juce::AudioBuffer`
- `juce::dsp::AudioBlock`
- `choc::buffer::InterleavedView`
- `choc::buffer::InterleavedBuffer`
- `choc::buffer::ChannelArrayView`
- `choc::buffer::ChannelArrayBuffer`
- `hart::AudioBuffer`

Currently supported IIR filter/coefficients are :
- `juce::dsp::IIR::Filter`
- `juce::dsp::IIR:Coefficients`
- `juce::dsp::StateVariableTPTFilter`
- `juce::dsp::StateVariableFilter::Filter`
- `juce::dsp::StateVariableFilter::Parameters`

**You can also add supports for your own entity classes**

### Current support
| Operating System  | Status       |
|-------------------|--------------|
| Linux             | ✅           |
| MacOS             | ✅           |
| Windows           | ❌           |

| Debugger platform | GDB          | LLDB         |
|-------------------|--------------|--------------|
| CLI               | ✅           | ✅           |
| VSCode            | ✅ (*)       | ❓ need testing  |
| CLion             | ✅ (*)       | ✅ (*) |
| XCode             | N/A          | ✅ (*)|
| Visual Studio     | ❌           | ❌           |

(*) -  DAVE is not able to react when you go up/down in
the stack using the IDE ui.

---

To get started first follow the `Project Setup` guide below, then you can read 
the [User Guide](USER_GUIDE.md) to get familiar with DAVE.

If you want to develop/experiment with dave, follow the [Development Guide](DEV_GUIDE.md)

## Project setup
### Requirements
DAVE requires a python >= 3.10 installation with a working `venv` module

### Installation
The simplest way to install dave and its bindings is to use the install script :
```bash
# via the install script
## using curl
bash -c "$(curl -fsSL https://raw.githubusercontent.com/maxmarsc/dave/refs/heads/main/dave/assets/dave_install.sh)"

## using wget
bash -c "$(wget https://raw.githubusercontent.com/maxmarsc/dave/refs/heads/main/dave/assets/dave_install.sh -O -)"
```

It will install the python dave modules, the debuggers bindings, and the `dave`
cli tool to help manage your dave installation.

You don't trust the script ? Check the [Manual Installation Guide](./MANUAL_INSTALLATION.md)

*Python* : Python support is limited, deprecated and requires a different installation method, see the section below

---

After binding, starts your debugger, you should see the following message :
```
[dave] Successfully loaded
```

And the dave debugger commands should be available :
 - `dave show`
 - `dave delete`
 - `dave freeze`
 - `dave concat`

See the [User Guide](USER_GUIDE.md) on how to use these.

### Update
If you want/need to update dave, you can use the `dave` cli tool :

```bash
# Update dave
dave update
```

### Uninstallation
If you just want to remove the dave bindings run
```bash
dave unbind
```

If you want to completely remove dave from your system run
```bash
dave uninstall
```

### Python support
Python support is limited because both python debuggers I have investigated
(pdb and debugpy) does not provide an API complete enough to provide full DAVE support.
Most importantly **Python debugger does not provide automatic update on breakpoints**.

To install DAVE for python, install the `davext` pypi package in your environment.

Only 1D and 2D numpy tensors are supported, and you need to manually import dave
from the debugger CLI, like this:
```py
import dave.debuggers.pdb as pydave
```

Then you can use the following commands :
 - `pydave.show` analog to `dave show`
 - `pydave.concat` analog to `dave concat`
 - `pydave.freeze` analog to `dave freeze`
 - `pydave.delete` analog to `dave delete`
 - `pydave.update` which forces the update of the containers data


---


## Licensing
This project is licensed under GPLv3.0. The goal is for you to be able to use it
to debug any project, open or proprietary, but to prevent anyone from making a
proprietary project out of DAVE's code.

If you have any question or request about licensing, don't hesitate to ask !

**Wikipedia:** *Software under the GPL may be run for all purposes, including commercial purposes and even as a tool for creating proprietary software, such as when using GPL-licensed compilers.*





## Troubleshooting

### Set logging level
When running into an issue, please activate the debug log level, by setting
the env variable `DAVE_LOGLEVEL` to `debug` before starting the debugger.

### LLDB on Ubuntu 24.04
When starting lldb on ubuntu 24.04 you might get this error :
```
Traceback (most recent call last):
  File "<string>", line 1, in <module>
ModuleNotFoundError: No module named 'lldb'
```

This is a [known bug](https://bugs.launchpad.net/ubuntu/+source/llvm-defaults/+bug/1972855). In the meantime you can fix these using a symbolic link :
```bash
sudo mkdir -p /usr/lib/local/lib/python3.12/
sudo ln -s /usr/lib/llvm-${VERSION}/lib/python3.12/dist-packages /usr/lib/local/lib/python3.12/dist-packages
```

### LLDB init
To always load the .lldbinit file in the current working directory, add the following command to ~/.lldbinit:
```
settings set target.load-cwd-lldbinit true
```

### LLDB python module linting
for `.venv`
```bash
PYTHON_VERSION="3.12"
LLDB_VERSION="14"
touch .venv/lib64/python${PYTHON_VERSION}/site-packages/lldb.pth
echo "/usr/lib/llvm-${LLDB_VERSION}/lib/python${PYTHON_VERSION}/site-packages/" > .venv/lib64/python${PYTHON_VERSION}/site-packages/lldb.pth
```
