Introduction to the recipes code base

This page is meant to provide a high-level overview of the recipes code in git, for the benefit of interns and other newcomers. It does not go into technical details or provide a step-by-step guide to build from git, but it should help you find your way around the repo and the various sources.

1. Build system

After 1.0, Recipes has switch to use meson exclusively for building.

The relevant files for this are the various meson.build files. There are a few auxiliary files as well, such as meson_options.txt, and tools/meson_post_install.py.

To build with meson, you do:

  rm -rf ./build
  meson --prefix=<your prefix> build 
  ninja -C build
  ninja -C build install

(on Fedora, ninja is called ninja-build for some reason).

2. flatpak

The flatpak build builds not just recipes itself, but also the dependencies that we need to bundle because they are not in the GNOME runtime.

To build a flatpak, you can use the flatpak/org.gnome.Recipes.json manifest that is in git. The most convenient way to use this file is to check out the recipes-releases module from github and use the Makefile in there, but you can also use flatpak-builder manually:

  flatpak-builder --verbose --force-clean --repo=repo --ccache \
                  recipes flatpak/org.gnome.Recipes.json

3. Dependencies

Recipes uses GTK+ >= 3.22, libcanberra, gnome-autoar and gspell. The last 3 are optional and can be disabled at configure time. Look at meson_options.txt to find the right option.

One of the easier ways to deal with the need to build some of these dependencies (e.g. because the GTK+ in your distro is too old) is to use jhbuild.

I've tried this on Ubuntu 16.04, and it mostly works. One complication is that you need apt-file for jhbuild sysdeps --install to work.

Another complication is that libarchive is too old for gnome-autoar. To get around that problem, download and unpack libarchive-3.2.2.tar.gz:

  cd jhbuild/checkout
  wget http://www.libarchive.org/downloads/libarchive-3.2.2.tar.gz
  tar xf libarchive-3.2.2.tar.gz

Install it:

  cd libarchive-3.2.2
  ./configure --prefix=$HOME/jhbuild/install
  make
  make install

After this, gnome-autoar should be buildable, and you can just build recipes like this:

  jhbuild build --nodeps recipes

To get a fully functional installation, you may have to build a few more things:

  jhbuild buildone libcroco librsvg dconf

and you may have to force the Adwaita theme for the best experience:

  GTK_THEME=Adwaita jhbuild run gnome-recipes

4. Directory structure

src: Contains the source code and ui files. Also things that we embed into the executable as resources.

data: Contains recipe data that we ship with the application, as well as data files that we need to install for proper integration, such as desktop file, D-Bus service file, gnome-shell search provider definition, etc.

tools: We build a recipe-extract tool that is used to extract translatable strings from the contributed recipes and chefs, so we can show users recipes that are translated in their native language. The tool is used in data/ to generate recipes.db.h and chefs.db.h, which in turn are listed in po/POTFILES.in.

po: Translations are handled here. Normally, this is the territory of the GNOME translation teams, they push updates to the .po files here, and add new languages.

po-data: Translations for the recipe data.

tests: Yes, we have a few tests! These test some of the parsing for numbers, units and ingredients.

subprojects/libgd: A git submodule we use.

5. Sources

Recipes uses the GtkApplication class for its main object, so the main entry point in main.c essentially just creates an object of our GrApp subclass of it, and then calls g_application_run().

gr-app.[hc] is where you'll find code for handling the life-cycle of a GtkApplication (startup, activate, open), as well as definitions for the various !GActions that export and connect to the app menu. The ui for the app menu is defined in menus.ui.

gr-window.[hc] is our GtkApplicationWindow subclass. It has a ui template in gr-window.ui. In that template, you'll find the main window structure, with the headerbar, and all the main pages (each is their own class). GrWindow has all the logic for switching pages, so you'll find methods to show a recipe, edit a recipe, show cuisines, etc. It is the 'central hub' for switching between views.

gr-recipe-store.[hc] is the storage layer of the app. It currently just writes out very simple key files, and keeps the data objects in hash tables at runtime. Search is also partially implemented here.

gr-recipe.[hc], gr-chef.[hc]: The data objects for our data.

The remaining files are mainly widgets, large and small. Almost every one of them comes with a ui template. For example, gr-edit-page.[hc] and its ui template in gr-edit-page.ui define the edit page, so main entry points here are gr_edit_page_edit() (to start editing a recipe) and gr_edit_page_save() (to save changed and stop editing).

recipes.css, cuisine.css: We use GTK+'s CSS machinery quite a bit to style our tiles and other widgets, and the CSS for that can be found in here. Note that we also generate CSS at runtime to use the recipe and chef images as background in tiles.

6. Data

One of the goals for this project is to ship contributed recipes with the application. This data lives in data/recipes.db and data/chefs.db, with the images in the data/images directory. We install this data into $PREFIX/share/gnome-recipes. At start time, we load the data from there first, and then from ~/.local/share/gnome-recipes (or ~/.var/app/org.gnome.Recipes/data in the flatpak case), so you can have local changes override the contributed recipe (although we only allow that if you are the author). When saving data, we always write to the location in the home directory.

More documentation about file formats can be found in gr-recipe-store.c.