Hacking on Pitivi

There are two ways to set up a flatpak sandbox with all the dependencies required to run and develop Pitivi. We recommend the advanced way, but if you want something quick, go ahead with the easy way.

The easy way

The easy way to setup the development environment is to follow the GNOME Newcomers guide.

This implies using GNOME Builder to manage the dependencies sandbox.

Clone the https://gitlab.gnome.org/GNOME/pitivi.git git repository in GNOME Builder.

To run the unittests, click in Builder: Unittests > pitivi > Pitivi unit tests. Make sure they all pass, or tell us about any failures.

To be able to use our pre-commit git hook, run:

$ cd ~/Projects/pitivi
$ ln -s ../../pre-commit.hook .git/hooks/pre-commit

When creating commits, for the pre-commit git hook to work properly it has to run in the sandbox. This is possible only by running git in a Build Terminal in GNOME Builder. You might want to export EDITOR=nano if you get "error: unable to start editor 'vi'" when you have to enter a commit message.

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 or if you usually use GNOME Builder as your main IDE, follow, as previously advised, the GNOME Newcomers guide

The official way of getting your environment up and running is by using flatpak. For this you need to install flatpak on your system, along with flatpak-builder. Note flatpak-builder might be provided by an additional package on some distributions (such as Archlinux).

Create a development environment folder and get the Pitivi source code into it:

$ mkdir pitivi-dev
$ cd pitivi-dev
$ git clone https://gitlab.gnome.org/GNOME/pitivi.git

Whenever you want to hack on Pitivi, enter the development environment:

$ cd pitivi-dev/pitivi && source bin/pitivi-env
-> Setting up the prefix for the sandbox...
Using Pitivi prefix in /.../pitivi-dev/pitivi-prefix
[prefix being built, if not already...]
Running in sandbox: echo Prefix ready
Prefix ready

This can take a while when creating the sandbox from scratch. Note the prompt changes:

(ptv-flatpak) $

By entering the development environment, you get:

Now that you are in the development environment, try running the unittests:

(ptv-flatpak) $ ptvtests
Running in sandbox: gst-validate-launcher .../pitivi/tests/ptv_testsuite.py

Hack away, and check the effect of your changes by simply running:

(ptv-flatpak) $ pitivi

Updating the development environment

To update the dependencies installed in the sandbox, run:

(ptv-flatpak) $ ptvenv --update

That will actually recreate the sandbox prefix, updating all dependencies from their git repos and tarballs as defined in the flatpak manifest.

How we use the sandbox

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)

If you have to work on say, GStreamer Editing Services which is built using the Meson build system, first clone it into your pitivi-dev folder:

(ptv-flatpak) $ git clone git://anongit.freedesktop.org/gstreamer/gst-editing-services

Prepare its build directory (Once it has been set up, you won't have to run meson again for this build directory):

(ptv-flatpak) $ cd gst-editing-services && setup
Using Pitivi prefix in /.../pitivi-dev/pitivi-prefix
Running in sandbox: meson mesonbuild/ --prefix=/app --libdir=lib -Ddisable_gtkdoc=true -Ddisable_doc=true

Build and install it in the sandbox:

(ptv-flatpak) $ ninja -C mesonbuild/ install
Using Pitivi prefix in /.../pitivi-dev/pitivi-prefix
Running in sandbox: ninja -C mesonbuild/ install

In the (ptv-flatpak) development environment meson and ninja are aliases which run meson and ninja in the flatpak sandbox.

NOTE: When updating the environment with ptvenv --update, it will use your local dependencies repositories it finds in the pitivi-dev folder, instead of the default remote repositories. This means you have to update them yourself. Also beware that it will not take into account not committed changes.

Hacking on Pitivi dependencies (Autotools, Make, etc)

If the project you are working on is built with other tools, make sure they are run in the sandbox by using ptvenv. For example:

(ptv-flatpak) $ cd pitivi-dev/frei0r-plugins-1.4
(ptv-flatpak) $ ptvenv ./autogen.sh
Running in sandbox: ./autogen.sh
(ptv-flatpak) $ ptvenv ./configure
Running in sandbox: ./configure
(ptv-flatpak) $ ptvenv make
Running in sandbox: make

Profiling Pitivi

To profile a Pitivi run, simply set the PITIVI_PROFILING environment variable to 1, like so:

(ptv-flatpak) $ PITIVI_PROFILING=1 pitivi

A file named pitivi-runstats will be created in the current directory, a handy tool to examine it is gprof2dot.py, install it with:

$ pip install gprof2dot

Then run:

$ gprof2dot -f pstats pitivi-runstats | dot -Tsvg -o profile.svg

You can then inspect the call tree profile with your preferred image viewer:

$ xdg-open profile.svg

Switching locales

To see how Pitivi looks in a different locale, use:

(ptv-flatpak) $ LANG=fr_FR.UTF-8 pitivi

Pay attention the translations in the sandbox are not automatically updated when you git pull. You can update them by updating your sandbox (ptvenv --update) or by reinstalling Pitivi in the sandbox:

(ptv-flatpak) $ binstall
Installing /.../pitivi-dev/pitivi/mesonbuild/po/de.gmo to /app/share/locale/de/LC_MESSAGES/pitivi.mo


Development Workflow – How we do it

Using Git in Pitivi – Specifics of using Git in Pitivi

Coding Style Guide – Writing code that looks consistent

Command line tools – A list of tools useful when developing Pitivi

The results of the search are