Initial creation of tutorials for 3rd party desktop applications

deployment/desktop/hosting-metadata.md

@@ -0,0 +1,198 @@
+---
+title: Hosting metadata for software applications 
+subsection: desktop
+description: >
+  How to host your GUI desktop application's metadata for yum/DNF or Flatpak in self- or Github-hosted repositories
+---
+
+# Hosting metadata for yum/DNF or Flatpak
+
+Metadata for distribution tools and GNOME Software must be refreshed
+periodically, such as when new versions of [packaged
+applications](desktop-software.html) are released for consumption by
+users.  In many cases, Linux distributions take care of the metadata
+extraction, generation, and hosting for these purposes.  However, this
+section provides information on how to host your own metadata in case
+you need to do so.
+
+## Install helper utilities
+
+Install the following software to help parse and generate the metadata needed for hosting:
+
+```console
+$ sudo dnf install createrepo_c libappstream-glib-builder flatpak-builder
+```
+
+## Generating yum repository metadata
+
+1. Run these commands to create the initial metadata for source
+   packages and the standard *x86_64* architecture:
+
+	```console
+$ createrepo_c --no-database --simple-md-filenames SRPMS/
+$ createrepo_c --no-database --simple-md-filenames x86_64/
+	```
+
+1. Next, generate the AppStream XML using the *appstream-builder*
+   tool:
+
+   ```console
+$ appstream-builder				\
+	--origin=yourcompanyname		\
+	--basename=appstream			\
+	--cache-dir=/tmp/asb-cache		\
+	--enable-hidpi				\
+	--max-threads=1				\
+	--min-icon-size=32			\
+	--output-dir=/tmp/asb-md		\
+	--packages-dir=x86_64/			\
+	--temp-dir=/tmp/asb-icons
+Scanning packages...
+Processing packages...
+Merging applications...
+Writing /tmp/asb-md/appstream.xml.gz...
+Writing /tmp/asb-md/appstream-icons.tar.gz...
+Writing /tmp/asb-md/appstream-screenshots.tar...
+Done!
+   ```
+
+	The actual build output will depend on your compose server
+    configuration. At this point you can also verify the application
+    is visible in the *yourcompanyname.xml.gz* file.
+
+1. Next, take the generated XML and the tarball of icons and add it to
+   the *repomd.xml* master document, so that GNOME Software
+   automatically downloads the content for searching:
+
+	```console
+$ modifyrepo_c					\
+	--no-compress				\
+	--simple-md-filenames			\
+	/tmp/asb-md/appstream.xml.gz		\
+	x86_64/repodata/
+$ modifyrepo_c					\
+	--no-compress				\
+	--simple-md-filenames			\
+	/tmp/asb-md/appstream-icons.tar.gz	\
+	x86_64/repodata/
+	```
+
+	Deploying this metadata allows GNOME Software to add the
+	application metadata the next time the repository is refreshed.
+
+## Hosting a DNF repository on Github
+
+While Github isn't ideal for hosting DNF repositories, this method currently works:
+
+1. Once you've created a local copy of your repository, create a new
+   project on Github. Then use the follow commands to import your
+   repository into Github.
+
+	```console
+$ cd ~/src/myrepository
+$ git init
+$ git add -A
+$ git commit -a -m "first commit"
+$ git remote add origin [email protected]:yourgitaccount/myrepo.git
+$ git push -u origin master
+	```
+
+1. Next, go to the Github web interface and browse down in the file
+   tree until you find the file called *repomd.xml*, and click on
+   it. You should now see a button in the Github interface called
+   *Raw*. Click that to get the raw version of the XML file.  In the
+   URL bar of your browser you should see a URL like this:
+
+	```console
+https://raw.githubusercontent.com/username/reponame/master/noarch/repodata/repomd.xml
+	```
+
+	Copy that URL, as you'll need it to create the *.repo* file that distributions and users use to reach your new repository.
+
+1. Create a *.repo* file using this example as a template, and edit it to match your data:
+
+	```console
+[frobnicator]
+name=Frobnicator 3D generator
+baseurl=https://raw.githubusercontent.com/username/reponame/master/noarch
+gpgcheck=0
+enabled=1
+enabled_metadata=1
+	```
+
+	For more information on this format, consult the [repository
+    options in the DNF configuration documentation](http://dnf.readthedocs.io/en/latest/conf_ref.html#repo-options).
+
+1. Copy this file to */etc/yum.repos.d* on your computer and load up
+   GNOME Software. Click on the *Updates* button in GNOME Software,
+   and then select the refresh button in the top left corner to ensure
+   your database is up to date.  You should then be able to search in
+   GNOME software and find your new application.
+
+## Generating Flatpak metadata
+
+The [Flatpak](https://flatpak.org) application packaging standard is another way to provide metadata for consumers. This guide assumes you are familiar with this standard, along with the [manifest and basic build operations required](http://docs.flatpak.org/en/latest/flatpak-builder.html).  You can find extensive information on building Flatpaks and on hosting and signing flatpak repostories [here](https://blogs.gnome.org/alexl/2017/02/10/maintaining-a-flatpak-repository/).
+
+Create an empty repository in a *repo* folder with this command:
+
+```console
+$ ostree init --mode=archive-z2 --repo=repo
+```
+
+To tell flatpak-builder to import the end result of a build into this repository, pass the *--repo* option to use the folder you created:
+
+```console
+$ flatpak-builder --verbose --force-clean \
+        --repo=repo --gpg-homedir=gpg --gpg-sign=$GPG_KEY \
+	recipes flatpak/org.example.Frobnicator.json
+```
+
+To generate appstream branches and static deltas in this repository use this command:
+
+```console
+$ flatpak build-update-repo --generate-static-deltas \
+        --gpg-homedir=gpg --gpg-sign=$GPG_KEY repo
+```
+
+Note that both of these commands take a *--gpg-sign* argument. Flatpak
+uses GPG as a means to ensure that the repository can be trusted, so
+you should sign your public repositories.
+
+To make your application and its Flatpak repository available to users is to publish a flatpakref file:
+
+```console
+[Flatpak Ref]
+Title=Frobnicator
+Name=org.example.Frobnicator
+Url=https://raw.githubusercontent.com/username/reponame/master/repo/
+Branch=1.0
+IsRuntime=False
+GPGKey=...
+RuntimeRepo=https://sdk.gnome.org/gnome.flatpakrepo
+Comment=GNOME loves to Frobnicate
+```
+
+## Hosting a Flatpak repository on Github
+
+Github isn't ideal for hosting Flatpak repositories, but this method currently works.
+
+1. Once you create a local copy of your repository, create a new
+   project on Github, enable Github pages for the project and point it
+   at the master branch.
+
+1. Next, import your repository into Github.
+
+	```console
+$ git remote add origin [email protected]:yourgitaccount/myrepo.git
+$ git push -u origin master
+	```
+
+Now you should be able to refer to your repo with a
+*raw.githubusercontent.com/* URL as shown in the flatpakrepo example
+above.
+
+## A note on third party repositories
+
+For more information on inclusion in Fedora as a third party software
+repository, consult with the [Fedora Workstation working
+group](https://fedoraproject.org/wiki/Workstation).

deployment/desktop/software-appdata.md

@@ -0,0 +1,137 @@
+---
+title: Adding Applications to GNOME Software
+section: deployment
+subsection: desktop
+description: >
+  How to build and package your GUI desktop applications for easy deployment by your users
+---
+
+# Adding Applications to GNOME Software
+
+The GNOME Software app provides a cross-distribution software center from which users can browse and manage apps for their Linux system.  This guide will help you produce the necessary metadata so your app can be listed in the software center.  Note that this guide covers apps as opposed to other system add-on components such as drivers and codecs.
+
+![GNOME Software](/content/deployment/desktop/steam-gnome-software.png  "Example of Steam listing in GNOME Software")
+
+This guide assumes an application package called Frobnicator, which contains an executable called *frob*.  It also assumes you are running Fedora Workstation with the standard GNOME desktop environment.
+
+## Install helper utilities
+
+Install the following packages on your Fedora system to help assemble
+and validate the metadata for your application:
+
+```console
+$ sudo dnf install desktop-file-utils appstream-util gnome-shell-extension-screenshot-window-sizer
+```
+
+## Create a desktop application file
+
+1. Write a *.desktop* file that follows the [Desktop File
+   Specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#introduction).
+   The required fields are *Name*, *Comment*, *Icon*, *Categories*,
+   *Keywords*, and *Exec*.  Here is an example:
+
+   ```console
+[Desktop Entry]
+Type=Application
+Name=Frobnicator
+Comment=Frobnicate a PNG into a 3D object
+Icon=frob
+Exec=frob %f
+MimeType=application/x-frob;
+Categories=Graphics;3DGraphics;Engineering;
+Keywords=3d;solid;geometry;csg;model;stl;
+	```
+
+   Your package should install this file in the
+   */usr/share/application* folder.  You may assign the desktop file a
+   short name such as *frob.desktop* in this example.  However, new
+   applications typically use a reverse-DNS style name, for example
+   *org.example.Frobnicator.desktop*.
+
+1. Create a PNG icon for the file at least 64x64 in size, with a
+   transparent background.  The icon should be named as in the *Icon*
+   field above, for example *frob.png*.  Your package should install
+   this file in one of the following locations:
+   - */usr/share/icons*
+   - */usr/share/icons/hicolor/apps*
+   - */usr/share/${app_name}/icons*
+
+1. Verify the desktop file with the *desktop-file-validate* command:
+
+   ```console
+$ desktop-file-validate org.example.Frobnicator.desktop
+   ```
+
+## Create an AppData file
+
+The AppData file provides XML metadata that follows the [AppStream
+specification](https://www.freedesktop.org/software/appstream/docs/),
+and is used by the GNOME Software app to display the app to users in
+the software center.
+
+1. Create an XML file for your application that follows the template
+   below. Note that you should consult the [AppStream
+   specification](https://www.freedesktop.org/software/appstream/docs/)
+   to provide correct data for your application in this file.  Here is
+   an example for the Frobnicator app:
+
+   ```console
+    <?xml version="1.0" encoding="UTF-8"?>
+    <component type="desktop">
+      <id>org.frobnicator.Frobnicator.desktop</id>
+      <metadata_license>CC0-1.0</metadata_license>
+      <project_license>GPL-2.0+</project_license>
+      <name>Frobnicator</name>
+      <summary>Frobnicate a PNG into a 3D object</summary>
+      <description>
+        <p>You can use Frobnicator to turn a PNG file into a 3D object magically, if you have the appropriate Frob interface card installed on your system.</p>
+      </description>
+      <screenshots>
+        <screenshot type="default">
+          <image>https://frobnicator.org/git/browse/frobnicator/plain/data/appdata/frob-startup.png</image>
+          <caption>Initial screen for the application</caption>
+        </screenshot>
+      </screenshots>
+      <releases>
+        <release version="1.0.0" date="2017-12-02">
+          <description>
+            <p>This is the first stable release</p>
+          </description>
+        </release>
+      </releases>
+      <url type="homepage">https://example.org/Frobnicator</url>
+      <provides>
+        <binary>frob</binary>
+      </provides>
+      <mimetypes>
+        <mimetype>application/x-frob</mimetype>
+      </mimetypes>
+    </component>
+	```
+
+1. Next, make the appropriate 16:9 aspect ratio screenshots for your
+   package, showing the application in action.  To make screenshot
+   creation easier, use the GNOME Shell extension called *Screenshot
+   Window Sizer* which you installed earlier.  To resize the window of
+   your application to 16:9 format, focus it and press *Ctrl+Alt+s*.
+   Your application window is resized to a perfect 16:9 aspect ratio
+   so you can screenshot it with *Alt+PrtScn*.
+
+   Store the screenshots at the URL referenced in your AppData XML file.
+
+1. Validate the AppData XML file:
+
+	```console
+$ appstream-util validate foo.appdata.xml
+	```
+
+NOTE: Do not install two applications with one single package. If
+necessary, split up a package into multiple subpackages or mark one
+*.desktop* file with *NoDisplay=true*. In this case, make sure the
+application subpackages depend on any *-common* subpackage, and that
+you deal with upgrades (perhaps using a metapackage) if you’ve shipped
+the application before.
+
+Normally distributions take care of hosting operations from this
+point.  However, if you want to host your own metadata for use with
+yum/DNF or Flatpak, [this guide](hosting-metadata.html) may be of use.