From 82b22e480142b0324f03f118e8e83f755baa92f3 Mon Sep 17 00:00:00 2001 From: Owen W. Taylor Date: Jan 31 2018 10:21:01 +0000 Subject: README.md: Update to correspond to the current status --- diff --git a/README.md b/README.md index d3a6037..2f415d4 100644 --- a/README.md +++ b/README.md @@ -1,71 +1,9 @@ -This git repository holds documentation, data and scripts related to -maintaining Fedora modules for the desktop and for Flatpak runtimes -for Fedora. +This git repository holds the modulemd file and associated container files +for the Fedora Flatpak runtimes. It also holds scripts and data files used +to maintain and update the Fedora Flatpak runtimes. -Fedora Desktop Modules Plan -=========================== - -The plan is to have the following modules, in addition to a large number -of application modules: - -**X11-base** - (already exists, name is perhaps not ideal). Holds the -core graphics stack - X, wayland libraries, mesa. - -**desktop-runtime** - this module corresponds roughly to -org.gnome.Platform/org.gnome.SDK, but possibly with the addition of -Qt and other libraries frequently used by Linux workstation users. - -**desktop** - this module contains the core GNOME desktop, but not desktop -applications. - -**flatpak-runtime** - this is a small module that depends on -desktop-runtime, and adds Flatpak-specific stuff, and in particular -has a `buildroot` profile that install macros for relocation to `/app`. If you -build-requires this module, your package will be relocated to `/app`. Build -time modules like `autotools` are also *required* by this module so that they -can be included into the SDK flatpaks, while they are only *buildrequired* -by the `desktop-runtime` module. - -The dependency graph looks something like: - -``` -flatpak-runtime ┐ -desktop ────────┤ - └ desktop-runtime ┐ - ├ X11-base - └ fonts ───────┐ - └ Platform -``` - -The`flatpak-runtime module will have profiles corresponding to different -generated runtimes: - -**runtime-base**: `org.fedoraproject.BasePlatform`. This is a smaller -runtime corresponding to `org.freedesktop.Platform`, and should -contain packages that we think could be supported over multiple -years. (Possibly the name should be something like runtime-stable -instead, but stable is a loaded word.) - -**sdk-base**: `org.fedoraproject.BaseSdk` - SDK corresponding to -`org.fedoraproject.BasePlatform`. The goal is that most -flatpak-builder manifests that build against `org.freedesktop.Sdk` can -be built against this instead, though can't be a formal promise, -because org.freedesktop.Platform contains some amount of stray -binaries and libraries that we need to eliminate. (It contains, for -example, a binary of the Python `idle` IDE that doesn't work. Pulling -`idle` into our runtime via `python2-tools` would pull in -`python2-tkinter` and `tk`.) - -**runtime**: org.fedoraproject.Platform - the runtime that Fedora -Flatpaks uses, roughly corresponding to `org.gnome.Platform`. It may -contain less stable libraries than `org.fedoraproject.BasePlatform`. - -**sdk**: the SDK corresponding to the ``org.fedoraproject.Platform`. -The goal is that most flatpak-builder manifests that build against -`org.gnome.Sdk` can be built against this instead. - -Usage of this module -==================== +Updating +======== *Prequisites*: you need to have the following "upstream" runtimes installed: @@ -74,15 +12,41 @@ Usage of this module * `org.gnome.platform/x86_64/3.26` * `org.gnome.Sdk/x86_64/3.26` -These will be used as sources to resolve hypthetical package sets that we -can compare to the package sets of the desktop modules. - -You also need `python3-jinja2 python3-dnf` and possibly a few other Python +You also need `python3-jinja2` and possibly a few other Python packages installed. And finally, you'll need to have [fedmod](https://pagure.io/modularity/fedmod) installed. - -*Report generation*: run `make`. The first run will download f27 data -into the user-specific DNF cache and also generate a big index of all files -in Fedora. Subsequent runs are faster. Then open `report.html` in your -browser. +You should run `fedmod fetch-metadata` initially and whenever you want to download +a fresh set of metadata from Fedora. `fedmod` never updates metadata on its own. + +*How it works*: The files in the upstream runtimes are the primary source for the contents +of the corresponding Fedora runtimes. When you type `make update`, the +steps are as follows: + + * List the contents of selected directories of the upstream runtime + (`tools/list-files.py`) + * Exclude and rename files, and otherwise tweak the contents of the + resulting lists, and find the Fedora packages that contain the + corresponding packages. (`tools/resolve-files.py`) + * Find all dependencies of the resolved packages using `fedmod resolve-deps`, + correlate it all together, figure out the install profiles for each runtime, + and create `report.html`. (`tools/generate-report.py`) + * Create a `flatpak-runtime.new.yaml` using the profiles. (`tools/generate-modulemd.py`) + * Copy `flatpak-runtime.new.yaml` to `flatpak-runtime.yaml` + +*Report generation*: if you type `make report` instead then all the above happens +except the last step. + +Tweaking the result +=================== +The main way to tweak the result is to edit and extend the data embedded in +`tools/resolve-files.py`. Make sure you add comments explaining why you are +excluding files, and feed back exclusions to the upstream runtime maintainers +as appropriate. + +Package notes +============= +To aid in keeping track of the status of all the packages in +`report.html`, notes and "flags" are read from package-notes.txt. The +notes are added to `report.html` and the flags affect formatting. The +top of that file has a comment describing the simple format.