Commit 26d21d24 authored by Alexandru Băluț's avatar Alexandru Băluț

docs: Update gdb instructions

Fixes #2158
parent 56b28b98
......@@ -5,5 +5,6 @@ configure_file(input: 'pitivi.in',
pitivi_bin = '@0@/pitivi'.format(meson.current_build_dir())
install_data(pitivi_bin, install_dir: get_option('bindir'))
# FIXME Work around to be able to run uninstalled
# Create `pitivi` in the current dir at build time to be able to
# run uninstalled in the dev env.
run_command('cp', pitivi_bin, meson.current_source_dir())
......@@ -62,10 +62,38 @@ process:**
integrate it into our test suite so that it does not happen again in
the future!
## Stack traces for crashes
When reporting a **crash** or when the application freezed **deadlock**,
it would be good to provide a **stack trace**.
## Stack traces for crashes and deadlocks
When reporting a **crash** or a **deadlock** (application is frozen),
we can't do much without a **stack trace** (also known as back trace).
The back trace can be obtained with `gdb`. Below are instructions on
how to properly start Pitivi in gdb.
Once Pitivi is started in gdb and you reproduce the crash or deadlock:
- When Pitivi crashes, run `bt full` to get the backtrace.
- When Pitivi freezes, press Ctrl+Z and run `thread apply all bt` to
get the backtraces for all the threads.
> To avoid the need to press Enter to “scroll” in gdb, run `set pagination 0`.
### When running in the development environment
1. Make sure you have the GNOME Sdk and Debug symbols installed,
see below.
2. Enter the sandbox:
```
ptvenv
```
3. Start Pitivi inside gdb:
```
gdb python3 -ex "run $PITIVI_REPO_DIR/bin/pitivi"
```
### When running with Flatpak
......@@ -81,33 +109,24 @@ for i in $(flatpak list | grep org.pitivi.Pitivi | awk '{ print $1 }'); do
done
```
2. Start a shell in the Pitivi bundle environment.
2. Start a shell in the Pitivi flatpak sandbox:
```
flatpak run -d --command=bash org.pitivi.Pitivi
```
In the development environment, you do this by running `ptvenv` instead.
3. Start Pitivi inside gdb
3. Start Pitivi inside gdb:
```
gdb python3 -ex 'run /app/bin/pitivi'
```
When Pitivi crashes, run `bt full` to get the backtrace. When Pitivi
freezes, press Ctrl+Z and run `thread apply all bt` to get the
backtraces for all the threads.
### When running from the packages of your Linux distro
See GNOME's [Getting
Traces](https://wiki.gnome.org/Community/GettingInTouch/Bugzilla/GettingTraces)
instructions for some comprehensive documentation and tips on the
subject.
For those of you who already know how to install the relevant debug
packages etc, we provide you with some simple reminders below of
commands that can be particularly useful in Pitivi's context.
GNOME's [Getting Stack Traces] has excellent documentation and tips
on the subject, including how to install the relevant debug
packages. Below is a quick reminder for those already familiar with
the process.
When you want to “attach” to an existing Python process (useful for
deadlocks, where the application will be hung instead of crashed):
......@@ -119,14 +138,9 @@ gdb python3 THE_PITIVI_PROCESS_NUMBER
When you want to run Pitivi entirely in gdb from the start:
```
gdb python3 $(which pitivi)
set pagination 0 # avoids the need to press Enter to “scroll”
run
gdb python3 -ex "run $(which pitivi)"
```
When Pitivi crashes, run `bt full` to get the backtrace. When Pitivi
freezes, press Ctrl+Z and run `thread apply all bt` to get the
backtraces for all the threads.
## Debug logs
......@@ -182,12 +196,11 @@ info from [GES](GES.md) in addition to Pitivi's:
PITIVI_DEBUG=5 GST_DEBUG=ges:5 bin/pitivi > debug.log 2>&1;
```
Some additional tips:
- When using GST\_DEBUG, the resulting logs will most likely be too
big to be attached to a bug report directly. Instead, compress them
(in gzip, bzip2 or lzma format) before attaching them to a bug
report.
> When using GST\_DEBUG, the resulting logs will most likely be too
> big to be attached to a bug report directly. Instead, compress them
> (in gzip, bzip2 or lzma format) before attaching them to a bug report.
# Python performance profiling
......@@ -205,3 +218,5 @@ The resulting `pitivi_performance.profile` file can then be processed
to create a visual representation of where the most time was spent and
which functions were called the most often in the code. See also [Jeff's
blog posts on profiling](http://jeff.ecchi.ca/blog/tag/profiling/).
[Getting Stack Traces]: https://wiki.gnome.org/Community/GettingInTouch/Bugzilla/GettingTraces
......@@ -4,13 +4,17 @@ short-description: Using the Pitivi development environment
# Hacking on Pitivi
*The easy way to setup the development environment is to follow the*
*[GNOME Newcomers guide](https://wiki.gnome.org/Newcomers/).*
*Make sure to use the right git repository:*
## The easy way
The easy way to setup the development environment is to follow the
[GNOME Newcomers guide](https://wiki.gnome.org/Newcomers/).
Make sure to use the right git repository:
> **https://gitlab.gnome.org/GNOME/pitivi.git**
## Setting up advanced development environment
## Setting up the advanced development environment
> NOTE: This way of setting the development environment is sensibly more complex
> but also more flexible than the one for newcomers. If you are a beginner
......@@ -66,7 +70,7 @@ Now that you are in the development environment, try running the
Running in sandbox: ninja -C mesonbuild/ test
```
Hack away, and check the effect of you changes by simply running:
Hack away, and check the effect of your changes by simply running:
```
(ptv-flatpak) $ pitivi
```
......@@ -85,14 +89,29 @@ dependencies from their git repos and tarballs as defined in the
manifest](https://git.gnome.org/browse/pitivi/tree/build/flatpak/pitivi.template.json) (located at `build/flatpak/pitivi.template.json`).
### Building the Pitivi C parts
### How we use the sandbox
Select parts of Pitivi are written in C and need to be built when changed,
such as the audio envelope renderer for the audio clips. Build them with:
```
(ptv-flatpak) $ ninja -C mesonbuild/
Running in sandbox: ninja -C mesonbuild/
```
The sandbox we set up has access to the host file system. This allows
running the Python modules in `pitivi-dev/pitivi/pitivi/...` on top of
the GNOME + Pitivi dependencies system installed in the sandbox.
Without this trick, you'd have to build and install every time when you
change a `.py` file, to be able to test how it works, which would be
annoying because it takes a non-negligible amount of time.
We don't actually run Pitivi 100% uninstalled. Besides the `.py` files
there are other parts which need to be built when changed or even
installed before using them:
- Select parts of Pitivi are written in C, such as the audio envelope
renderer for the audio clips. Build them with `ninja -C mesonbuild/` or
with our very own alias `build`, which is the same thing. No need to
install them.
- Similarly, `bin/pitivi.py.in` and `pitivi/configure.py.in` also need
to be built with `build`, to regenerate the corresponding `.py` files.
- The translations need to be built and installed, which can be done
with `binstall`. See "Switching locales" below.
### Hacking on Pitivi dependencies (Meson)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment