Metadata-Version: 2.1
Name: davext
Version: 0.6.1
Summary: UNKNOWN
Home-page: https://github.com/maxmarsc/dave
Author: maxmarsc
Author-email: maxime.coutant@protonmail.com
License: GPLV3
Platform: UNKNOWN
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: customtkinter==5.2.2
Requires-Dist: matplotlib==3.9.2


<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](.pictures/dave_logo_long_v6.png  )

DAVE is a GDB & LLDB extension which provide commands to visualize audio data
directly from your buffers/classes. 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=".pictures/phase.png">
</p>

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`

__2D (multichannel) containers__:
- Any nesting of 1D containers
- `juce::AudioBuffer`
- `juce::dsp::AudioBlock`

Currently supported OS are Linux and supposedly MacOS. Both GNU and LLVM stdlib
implementation are supported.

---

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 working `venv` and `tkinter` modules

### 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.

*MacOS* : On MacOS distribution you might need to install tkinter using homebrew/macports.
*Python* : Python support is limited 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


---


## Milestones
- [x] Freeze
- [x] Concatenate 
- [x] Save to disc
- [x] Add tooltip hover for action buttons
- [x] out-of-scope detection
- [x] react to step over/up/down
- [x] Mid/Side
- [x] Interleaved 
- [x] Easy installation
- [x] improve logging system
- [x] document commands
- [x] add license
- [x] llvm libc/libstd (need to be tested)
- [x] JUCE 
- [x] GSL
- [x] Add samplerate support
- [ ] Add a way for the user to add custom container support
- [ ] Add command to help diagnostic type for custom container support
- [ ] Add argument parsing to `show` (view, layout, settings...)
- [ ] Add versionning selection to dave_install
- [ ] Add FISH shell support
- [ ] command aliases
- [ ] minimize call to render functions
- [ ] CHOC
- [ ] Eigen
- [ ] Document the code
- [ ] find testing strategy
- [x] Restart dave process 
- [x] Improve GUI proportions
- [x] container deletion (GUI + delete command)
- [x] LLDB





## 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 22.04
When starting lldb on ubuntu 22.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.10/
sudo ln -s /usr/lib/llvm-${VERSION}/lib/python3.10/dist-packages /usr/lib/local/lib/python3.10/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
touch venv/lib64/python3.10/site-packages/lldb.pth
echo "/usr/lib/llvm-${VERSION}/lib/python3.10/dist-packages/" > venv/lib64/python3.10/site-packages/lldb.pth
```

### GDB 14 on Ubuntu 22.04
```bash
sudo apt-get install -y libmpfr-dev libgmp-dev
wget https://ftp.gnu.org/gnu/gdb/gdb-14.2.tar.xz
tar -xzvf gdb-14.2.tar.xz 
cd gdb-1402
./configure
make all -j"$(ncpus)
sudo make install
```

