HACKING.md

---

short-description: Using the ScarlettOS development environment ...

Hacking on ScarlettOS

The easy way

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

Make sure to use the right git repository:

https://gitlab.gnome.org/GNOME/pitivi.git

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 adviced, 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 ScarlettOS 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 ScarlettOS, enter the development environment:

$ cd pitivi-dev/pitivi && source bin/pitivi-env
-> Setting up the prefix for the sandbox...
Using ScarlettOS 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:

• a Flatpak sandbox for the dependencies, in pitivi-dev/pitivi-prefix
• a Python virtual environment with development tools, such as pre-commit, in pitivi-dev/pitivi/build/flatpak/pyvenv
• the Meson build directory, in pitivi-dev/pitivi/mesonbuild
• 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) $ ninja -C mesonbuild/ test
Running in sandbox: ninja -C mesonbuild/ test

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 (located at build/flatpak/pitivi.template.json).

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 + ScarlettOS 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 ScarlettOS 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 ScarlettOS 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 ScarlettOS 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) $ setup
Using ScarlettOS 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 ScarlettOS 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 ScarlettOS 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 ScarlettOS

To profile a ScarlettOS 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 ScarlettOS 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 ScarlettOS in the sandbox:

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