[Initiatives.wiki] Update DevOps with Flatpak

From: Jordan Petridis <jpetridis src gnome org>
To: commits-list gnome org
Cc:
Subject: [Initiatives.wiki] Update DevOps with Flatpak
Date: Thu, 21 Jul 2022 10:52:20 +0000 (UTC)
commit 696d10a91b33d7bd9649e892c688fcb1e8d17d2f
Author: Jordan Petridis <jpetridis gnome org>
Date:   Thu Jul 21 10:52:19 2022 +0000

    Update DevOps with Flatpak

 DevOps-with-Flatpak.md | 63 +++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 49 insertions(+), 14 deletions(-)
---
diff --git a/DevOps-with-Flatpak.md b/DevOps-with-Flatpak.md
index af82343..d95d471 100644
--- a/DevOps-with-Flatpak.md
+++ b/DevOps-with-Flatpak.md
@@ -1,6 +1,7 @@
 # Flatpak CI
 
 ### Requirements
+
 - Meson. Feel free to adapt to Autotools or other build system, however we rely on Meson for the templates.
 - GtkApplication/GApplication based. So it's possible to have different app-ids.
 
@@ -9,6 +10,7 @@
 The main goal here is to make sure our CI runs for every commit and MR and the project is buildable using 
the same base across GNOME, the Flatpak env.
 
 For that, use the following template and replace the variables with the appropriate variables for your 
project.
+
 ```yaml
 include: 'https://gitlab.gnome.org/GNOME/citemplates/raw/master/flatpak/flatpak_ci_initiative.yml'
 
@@ -20,13 +22,14 @@ flatpak:
         APP_ID: "org.gnome.NautilusDevel"
         RUNTIME_REPO: "https://nightly.gnome.org/gnome-nightly.flatpakrepo";
         BUNDLE: "nautilus-dev.flatpak"
-    extends: '.flatpak'
+    extends: '.flatpak@x86_64'
 ```
 
 The template will do the following:
-1. Build with `meson build` inside a [nightly 
Flatpak](registry.gitlab.gnome.org/gnome/gnome-runtime-images/gnome:master) environment. 
-1. Install with `ninja install` in /app prefix.
-1. Run tests with `ninja test` with a 
[xvfb-run](http://manpages.ubuntu.com/manpages/xenial/man1/xvfb-run.1.html) mocked display inside a Flatpak 
environment. The mocked display has a resolution of 1024x768.
+
+1. Build with `meson build` inside a [nightly 
Flatpak](registry.gitlab.gnome.org/gnome/gnome-runtime-images/gnome:master) environment.
+2. Install with `ninja install` in /app prefix.
+3. Run tests with `ninja test` with a 
[xvfb-run](http://manpages.ubuntu.com/manpages/xenial/man1/xvfb-run.1.html) mocked display inside a Flatpak 
environment. The mocked display has a resolution of 1024x768.
 
 If you need to change the configure args that will be passed into meson, you can do so by defining a 
`CONFIG_OPTS` variable.
 
@@ -38,10 +41,11 @@ If you need to change the configure args that will be passed into meson, you can
 ```
 
 ### Flatpak bundle for every MR and commit
+
 The main goal is to create Flatpak bundles so people can install and run them.
 
 1. Create a Flatpak package/bundle and export it
-1. Create a GitLab artifact to save the generated bundle for 14 days
+2. Create a GitLab artifact to save the generated bundle for 14 days
 
 The template will create a Flatpak bundle with `flatpak build-bundle` and the runtime pointing to the value 
of RUNTIME_REPO variable. Once the build is done you will see a widget that exposes the artifacts of the job 
in the MR and that can download the generated Flatpak bundle.
 
@@ -49,20 +53,20 @@ The template will create a Flatpak bundle with `flatpak build-bundle` and the ru
 
 ### Flatpak builds on every commit to your main branch
 
-The nightly builds can be published to GNOME [Nightly Flatpak 
Repository](https://nightly.gnome.org/gnome-nightly.flatpakrepo), by adding the following job. It will 
publish the build on the `master, main or mailine` branch, but only if it the branch is marked as *protected* 
in gitlab.
+The nightly builds can be published to GNOME [Nightly Flatpak 
Repository](https://nightly.gnome.org/gnome-nightly.flatpakrepo), by adding the following job. It will 
publish the build on the `master, main or mailine` branch, but only if it the branch is marked as _protected_ 
in gitlab.
 
 ```yaml
 nightly:
   extends: '.publish_nightly'
-  # assuming your job in named 'flatpak'
-  dependencies: ['flatpak']
   needs: ['flatpak']
 ```
 
 ### Saving build and test logs & cache builds
+
 If the CI fails, we need a way to retrieve the logs. For this we use the artifacts tool of GitLab too. The 
provided template exports the meson-logs.txt and the testlog.txt files as part of the artifacts.
 
 ### Final gitlab-yaml file template
+
 Here is the resulting template, but it is recommended to try doing it step-by-step.
 
 ```yaml
@@ -76,7 +80,7 @@ flatpak:
         APP_ID: "org.gnome.NautilusDevel"
         RUNTIME_REPO: "https://nightly.gnome.org/gnome-nightly.flatpakrepo";
         BUNDLE: "nautilus-dev.flatpak"
-    extends: '.flatpak'
+    extends: '.flatpak@x86_64'
 
 nightly:
     extends: '.publish_nightly'
@@ -86,6 +90,7 @@ nightly:
 ```
 
 # Parallel installation
+
 For GLib & Gtk+ based apps we need to generate a different dbus id, so different versions can be installed 
and ran alongside. For that, we created the concept of "profiles" in the building phase. This is a bit tricky 
and also needs to be done all at once for the major part.
 
 The stable profile will be used for distributions and stable versions, and the development profile will use 
a different id for the application itself, the icons, the installation path, services, etc.
@@ -93,6 +98,7 @@ The stable profile will be used for distributions and stable versions, and the d
 First, let's add basic support for profiles in the root meson.build file.
 
 ### Root meson.build
+
 ```python
 if get_option('profile') == 'Devel'
   name_suffix = ' (Development Snapshot)'
@@ -124,7 +130,9 @@ config_h = declare_dependency(
   )
 )
 ```
+
 And make sure to add the config_h dependency to your project dependencies. Usually in the executable command:
+
 ```python
 executable(
 ...
@@ -137,6 +145,7 @@ dependencies: [
 ```
 
 Lastly, add a meson option in the meson_options.txt file for the profile:
+
 ```python
 option(
   'profile',
@@ -150,7 +159,9 @@ option(
 ```
 
 ### Icons handling
+
 To install icons with the proper name change to the following on your data/meson.build:
+
 ```python
 icondir = join_paths('icons', 'hicolor', 'scalable', 'apps')
 install_data(
@@ -166,12 +177,15 @@ install_data(
   rename: '@0 -symbolic svg'.format(application_id)
 )
 ```
+
 If you are providing a Nightly variant of your application icon, make sure to name it 
"org.gnome.AppNameDevel.svg" (replace "AppName" by your application name). This way the code above will 
assign the desired icon to each profile.
 
 ### Desktop file handling
+
 The desktop file name has to match the dbus id, so we need to recreate it based on the profile selected.
 
 For that, in the data/meson.build create the desktop file with:
+
 ```python
 desktop_conf = configuration_data()
 desktop_conf.set('icon', application_id)
@@ -189,15 +203,19 @@ desktop = i18n.merge_file(
   type: 'desktop'
 )
 ```
+
 Replace "AppName" by your application name.
 
 And in the desktop.in.in file change to the following:
+
 ```
 Icon=@icon@
 ```
 
 ### AppData handling
+
 Similar to the desktop file, need to take application_id into account. Create the appdata file with:
+
 ```python
 appdata_conf = configuration_data()
 appdata_conf.set('appid', application_id)
@@ -214,14 +232,17 @@ appdata = i18n.merge_file(
   po_dir: po_dir
 )
 ```
+
 Replace "AppName" by your application name.
 
 In the xml.in.in file change to the following:
+
 ```
 <id>@appid@.desktop</id>
 ```
 
 ### Service handling
+
 Every GLib app registers as a service too. So similar to desktop file and appdata, let's take into account 
the application id:
 
 ```python
@@ -235,14 +256,17 @@ configure_file(
   install_dir: servicedir
 )
 ```
+
 Replace "AppName" by your application name.
 
 In the service.in file change the following line:
+
 ```
 Name=@appid@
 ```
 
 ### Shell search provider handling
+
 Most of core apps have a shell search provider, we need to take into account the application id too for this.
 
 ```python
@@ -258,37 +282,45 @@ configure_file(
 ```
 
 And in the search provider .ini.in file change the values to the following:
+
 ```
 DesktopId=@appid@.desktop
 BusName=@appid@
 ObjectPath=/org/gnome/AppName@profile@/SearchProvider
 ```
+
 Replace "AppName" by your application name.
 
 ### Flatpak manifest handling
+
 Simply change the app id to the matching app id of the selected profile, for example:
+
 ```json
 "app-id": "org.gnome.AppNameDevel",
 ```
+
 And in config-options of your module section add:
+
 ```python
 "config-opts": [
     "-Dprofile=Devel"
 ],
-
 ```
 
 For the stable flatpak branch, change the id to the regular one and the profile to the stable one.
 
 ### Application handling
+
 Now we need to handle inside the code itself the proper id. Now you can include the config.h generated with 
the selected ID from the build. In your GtkApplication implementation:
 
 In the startup vfunc, make sure to apply the correct application id:
+
 ```c
 gtk_window_set_default_icon_name (APPLICATION_ID);
 ```
 
 In the creation of the GtkApplication, make sure to pass the correct id too:
+
 ```c
 g_object_new (APP_NAME_TYPE_APPLICATION,
               "application-id", APPLICATION_ID,
@@ -297,11 +329,13 @@ g_object_new (APP_NAME_TYPE_APPLICATION,
 ```
 
 For your preferences dialog, make sure to set the proper icon name:
+
 ```c
 gtk_window_set_icon_name (GTK_WINDOW (preferences_window), APPLICATION_ID);
 ```
 
 Same for the about dialog:
+
 ```c
 program_name = g_strconcat (_("App Name"), NAME_SUFFIX, NULL);
 gtk_show_about_dialog (window ? GTK_WINDOW (window) : NULL,
@@ -309,10 +343,10 @@ gtk_show_about_dialog (window ? GTK_WINDOW (window) : NULL,
                        "logo-icon-name", APPLICATION_ID,
                        ...,
                        NULL);
-
 ```
 
 And lastly, if you have a Shell search provider, pass the correct id too:
+
 ```c
 g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (self->skeleton),
                                   connection,
@@ -320,9 +354,11 @@ g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (self->skeleton),
 ```
 
 # Adding a visual hint for development
+
 The goal is that the person installing a profile knows that it's a development version right away, including 
in case errors are reported with an screenshot. For that we will add an style to the app when running in 
devel mode.
 
 In your application window code:
+
 ```c
     if (g_strcmp0 (PROFILE, "") != 0)
     {
@@ -344,9 +380,8 @@ Which assumes that if there is a profile set, it's going to be for development.
 
 This almost does what we would want, but not quite. If you build this way it will always try to fetch your 
modules from the source specified in the manifest, but we want to use our local checkout instead. This is 
fine if you only build the `master` branch but MRs need to be able to change the source to their checkout.
 
-To achieve this we use the `--stop-at=module` argument which will build all of the dependencies up to your 
module from the manifest. Then we take over and need to install the application ourselves. This is why your 
config
-s `CONFIGURE_ARGS` variable needs to be kept in sync with your module's config options in the manifest.
+To achieve this we use the `--stop-at=module` argument which will build all of the dependencies up to your 
module from the manifest. Then we take over and need to install the application ourselves. This is why your 
config s `CONFIGURE_ARGS` variable needs to be kept in sync with your module's config options in the manifest.
 
 **A previous version of the template had some extra `review` and `stop_review` jobs, what happened to 
those?**
 
-They have been deprecated and replaced by a simpler feature that provides the same function. It should 
simplifies both the template setup, and the backend setup needed to run the previous jobs. For more you can 
refer to this 
[commit](https://gitlab.gnome.org/GNOME/citemplates/commit/544836ee58f91a735616ecb04ea857a66d2bb699)
\ No newline at end of file
+They have been deprecated and replaced by a simpler feature that provides the same function. It should 
simplifies both the template setup, and the backend setup needed to run the previous jobs. For more you can 
refer to this 
[commit](https://gitlab.gnome.org/GNOME/citemplates/commit/544836ee58f91a735616ecb04ea857a66d2bb699 "Replace 
review apps with artifacts:expose_as")
\ No newline at end of file
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]