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.
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
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:
By entering the development environment, you get:
- a Flatpak sandbox
for the dependencies, in
- a Python virtual environment
with development tools, such as
- the Meson build directory,
- some aliases for the build tools, such as
ninja, so they are executed in the sandbox.
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
.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
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.
pitivi/configure.py.inalso need to be built with
build, to regenerate the corresponding
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
(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
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
(ptv-flatpak) development environment
aliases which run meson and ninja in the flatpak sandbox.
NOTE: When updating the environment with
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
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
To profile a Pitivi run, simply set the
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
$ 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
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
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 [...]
The results of the search are