Building for Flatpak
Similar to Snap, there exists a Flatpak version of Jami which is distributed on Flathub.
What is Flatpak and how does it work?
It is recommended that you read the Introduction to Flatpak and Basic Concepts to get a basic understanding.
Important
Before proceeding, install the flatpak package!
Source code
The source code for the Flatpak version is the exact same as that of desktop client. However, the manifest, dependencies, and Flatpak-specific patches are hosted on the official GitHub repository (as required by Flathub) which can be found here.
Prerequesites
Install flatpak-builder
flatpak install flathub org.flatpak.Builder
Then, add the Flathub repo user-wide:
flatpak remote-add --if-not-exists --user flathub https://dl.flathub.org/repo/flathub.flatpakrepo
Building the Flatpak locally
Clone the GitHub repository
git clone git@github.com:flathub/net.jami.Jami.git
Build Jami
flatpak-builder --force-clean --user --install-deps-from=flathub --repo=DIR builddir net.jami.Jami.yml
DIR
- the name you wish to give to your repository. By default you should name it repo
. Should you name it anything else, you must keep it in mind when installing Jami, debugging the Flatpak, and submitting updates to Flathub.
Install Jami
flatpak install DIR -y net.jami.Jami
Run Jami
flatpak run net.jami.Jami
Note
If you have multiple Flatpak installations of Jami, you should specify a --branch=BRANCH
after run
to ensure that you are running the Flatpak you just built!
You can check your Flatpak installations and their corresponding branches using flatpak list
. To run the Flatpak you just built and installed, set BRANCH
to the branch that corresponds to Origin
being repo
.
Debugging
Debugging Flatpaks within the sandbox on your own machine is possible.
Warning
Due to the way Jami is built for Flatpak, debugging can be time-consuming since jami-core is built as a shared library. This means that each time you restart the debugger, you will need to wait for symbols to load. Unless you are certain that the issue you are debugging for is specific to the Flatpak version of Jami, it is usually faster to build and debug the desktop client locally. For instructions, see here.
Dowloading the debug version
The instructions to build the Jami Flatpak as described in the previous section must be complete prior to proceeding. Once done, install the debug version:
flatpak install --include-sdk --include-debug repo -y net.jami.Jami
Starting the debugging environment
The following command will run a shell within the sandbox:
flatpak run --command=sh --devel --filesystem=$(pwd) net.jami.Jami
Once run, the shell should appear similar to the following:
[📦 net.jami.Jami net.jami.Jami]$
There are now two methods for debugging. Regardless of which is chosen, commands described in either section should be run within the sandbox shell.
Debug with the GNU Project Debugger (GDB)
gdb --args /app/bin/jami --debug
Debugging can now be done as usual.
Debug with Visual Studio Code (VS Code)
Start gdbserver
gdbserver :1234 /app/bin/jami --debug
Note
The port number can be changed if required. Make sure the port number for miDebuggerServerAddress in
.vscode/launch.json
reflects the new port number.Launch VS Code at the root of the project
Enter the Run and Debug section (Ctrl+Shift+D)
Select
Attach to Remote GDB
Run Jami (F5)
Setting breakpoints
Source files are located in builddir/files/lib/debug/source
at the root of the project and is where breakpoints should be set.
Submitting updates to Flathub
If not done already, install flatpak-builder and add the Flathub repo user-wide as described in the Prerequesites section.
Build the manifest
flatpak run --command=flathub-build org.flatpak.Builder --install net.jami.Jami.yml
Run and test Jami
flatpak run net.jami.Jami
Run the linter
You must run the commands below if you have made any changes to any of the YAML files. If there are errors, they must be resolved before opening a pull request. Othwerise, the Flathub test build will fail as well.
flatpak run --command=flatpak-builder-lint org.flatpak.Builder manifest net.jami.Jami.yml
flatpak run --command=flatpak-builder-lint org.flatpak.Builder repo repo
The list of linter errors can be found here.
Push changes and open a pull request
If the build was successful and passed the linter checks, changes can be pushed to the GitHub repo and a pull request can be done. Once the the pull request is opened, Flathub’s automatic build system will create a test build for both x86_64
and aarch64
. If the build was successful, you will be able merge to master which will trigger the official build.
Note
Any changes to finish-args
in net.jami.Jami.yml
as well as changes to net.jami.Jami.metainfo.xml
will require approval by the Flathub maintainers. Depending on the changes, your build may be rejected or require explanation/justification. For the latter, an issue will be opened on the GitHub repository where you may justify/explain your changes.
To see the status of approval, sign in to Flathub and navigate to Developer Portal -> Jami.