Workstation/FlatpakModuleCreation

This is a narrative about creating a modulemd file for an application given the current state of the prototype tooling. See Workstation/FlatpakDevelopmentSetup for setting up an environment and basics.

Initial attempt at creating a modulemd

We first try to create a modulemd information using the existing runtime and the dependency information from the Fedora 26 package set. (This command assumes that flatpak-runtime is built locally - once there are official builds you can omit the -l flatpak-runtime:f26)

   flatpak-module create-modulemd -l flatpak-runtime:f26 --from-package gedit -o gedit.yaml --dependency-tree gedit-dependencies.txt

Once this completes, if you look at gedit.yaml, you will see lots and lots of packages being built, including things like the ceph distributed filesystem client libraries. If you look at gedit-dependencies.txt, you can see that the problem is that gedit pulls in gvfs, when it should only be pulling in gvfs-client.

Excluding Requires

To get the modulemd to act as if gedit has been fixed to require gvfs-client, create a gedit-packages.yaml file with the following contents:

   runtime-roots:
       - gedit
   ignore-requires:
       gedit: [ gvfs ]
   extra-requires:
       gedit: [ gvfs-client ]

and rerun the command as:

   flatpak-module create-modulemd -l flatpak-runtime:f26 --from-package gedit -o gedit.yaml --dependency-tree gedit-dependencies.txt

Which results in a much smaller gedit.yaml.

Updating the runtime

If we comparing the set of packages to be built in gedit.yaml with gnome-sdk-images and freedesktop-sdk-images we can find some packages being built that probably should be in the runtime:

   gvfs enchant hunspell hunspell-en zenity

(these are source package names.) We go to the flatpak-runtime module and add the binary packages we want to runtime-roots in flatpak-runtime-packages.yaml:

    # This is a set of binary packages that we should depsolve to get the
    # set of packages that are installed into the runtime.
    runtime-roots:
    +    - enchant
    +    - hunspell-en-US
    +    - hunspell-en-GB
         - gtk3
         - gnome-desktop3
    +    - gvfs-client
         - librsvg2
         - libappstream-glib
         - python3-gobject
    +    - zenity

We then update the modulemd (flatpak-runtime.yaml):

    make update-modulemd

Then check in the changes to both flatpak-runtime.packages and flatpak-runtime.yaml with an appropriate commit message:

   Add additional packages, as needed for gedit
   
   Add dependencies of gedit that are in the org.gnome.Platform runtime:
   
       enchant, hunspell, gvfs-client, zenity

The changes to flatpak-runtime.yaml are likely to be fairly small - just adding the specified libraries and maybe a few dependencies. But if the depth of the overall build chain changes, all the buildolder: values could change.

Now fire off a local build and wait:

    mbs-build local

Creating the final modulemd file

Go back to the directory where you were creating gedit.yaml and rerun the command:

   flatpak-module create-modulemd -l flatpak-runtime:f26 --from-package gedit -o gedit.yaml --dependency-tree gedit-dependencies.txt

Verify that the package list looks good. You now can proceed to fixing the gedit package to require gfvs-client instead of gvfs and building the gedit module and the flatpak.

Appendix: Dealing with make create-modulemd failures

create-modulemd can fail:

   Can't make progress in sorting by build order. Remaining packages to order:
   [lots of output]
   Giving up

This basically means that there's a build dependency loop in the packages for the module. The format of the dumped information is:

   <package>: <is builddepended on, directly or indirectly>

To fix this, you need to figure out what the loop is, and cut it, by adding an appropriate build-order-ignore. For example, if the wayland package uses graphviz to build its docs and some applications in graphviz depends on cairo which depends on wayland, then you can add in <module>-packages.yaml:

   build-order-ignore:
       - graphviz

because when building the docs for wayland, we don't care if we have the version of wayland we built in the buildroot or not. The point of the build ordering is so that when we build, for example, gtk3, a library that links against libwayland, we have the newly built wayland-devel packages.