Merge pull request #95 from TomChapple/flatpak-app

Define a Flatpak App Manifest for Gearsystem

platforms/flatpak/.gitignore

@@ -0,0 +1,2 @@
+#Ignore any files created during the build of the Flatpak application
+.flatpak-builder/

platforms/flatpak/Makefile

@@ -0,0 +1,9 @@
+include ../desktop-shared/Makefile.sources
+
+SOURCES_CXX += $(DESKTOP_SRC_DIR)/nfd/nfd_portal.cpp
+CPPFLAGS += `pkg-config --cflags dbus-1`
+CPPFLAGS += -DPREVENT_ROM_FOLDER_USAGE
+LDFLAGS += `pkg-config --libs dbus-1`
+
+include ../desktop-shared/Makefile.common
+include ../desktop-shared/Makefile.install

platforms/flatpak/README.md

@@ -0,0 +1,153 @@
+# Flatpak Platform for Gearsystem
+
+[Flatpak](https://flatpak.org/) is a method of packaging and distributing
+applications independent of the operating system and surrounding dependencies.
+These applications also take advantage of sandboxing for security purposes, only
+allowing applications access to services and files that they require.
+
+Gearsystem can be built as a Flatpak application to take advantage of the
+packaging format as well as the sandbox features available.
+
+## Features
+
+Building and distributing Gearsystem as a Flatpak has the following key
+advantages:
+
+* **Embedded SDL, GLU and GLEW libraries**. Compared to manual installation,
+  all dependencies are included and sandboxed within the Gearsystem application.
+  Outside of Flatpak's setup, no prerequisite commands are required!
+* **Automatically created Desktop entries**. The Flatpak installation comes with
+  the appropriate files to define desktop and menu entries for Gearsystem,
+  allowing for the application to be quickly started from anywhere. These are
+  also removed entirely when the application is uninstalled.
+* **Consistent development environment**. Similar to how the application is
+  sandboxed, the build environment is also sandboxed, ensuring all developers
+  have the same experience when enhancing or troubleshooting Gearsystem.
+
+This unfortunately comes with some trade-offs in functionality:
+
+* **Adjacent Save files and Savestate files cannot be loaded**. The API used to
+  load files into Gearsystem only loads specific files or directories. When
+  this is done, only those file are permitted within the sandbox, resulting in
+  adjacent files being invisible to the Gearsystem application. Instead, the
+  application will only save files separate directory.
+* **Some file paths may not reflect real paths**. As part of the above
+  sandboxing, files can appear in Gearsystem to come from another location.
+  These files are physically the same and use the same file name, but it can be
+  a jarring first experience.
+
+## Getting Started
+
+This section is dedicated to preparing the development environment for
+Gearsystem. This allows for building in-development versions and contributing
+changes to Gearsystem. These instructions will predominantly use the
+command-line and assume that `bash` is the shell being used.
+
+1. **Install Flatpak and Flatpak builder**
+
+   Flatpak can be installed by following [the quick setup steps for your
+   distribution][Flatpak Setup]. Once Flatpak is installed, the
+   `flatpak-builder` application must also be installed. This can be done
+   either in a similar manner to how Flatpak was installed, or with `flatpak
+   install flathub org.flatpak.Builder`. Once this is complete, Flatpak
+   applications are built using one of the following:
+
+   * `flatpak-builder`
+   * `flatpak run org.flatpak.Builder`
+
+   For the purposes of this tutorial, we will use `flatpak-builder`, but know
+   that this can be interchanged with any of the above commands.
+
+2. **Install the Runtime and SDK**
+
+   Each Flatpak application has a base Runtime and SDK that they are built from,
+   acting as a starting point for packages. These must be installed for builds
+   to begin.
+
+   For Gearsystem, the Runtime and SDK are `org.freedesktop.Platform` and
+   `org.freedesktop.Sdk` respectively, running on version `23.08`. These can be
+   installed via the command line with the following commands:
+
+   ```bash
+   flatpak install flathub \
+       org.freedesktop.Platform//23.08 \
+       org.freedesktop.Sdk//23.08
+   ```
+
+3. **Build the application**
+
+   Builds are completed using `flatpak-builder` as follows (assuming
+   `platforms/flatpak` is the current working directory):
+
+   ```bash
+   flatpak-builder \
+       --force-clean \
+       --user \
+       --install \
+       build-dir io.github.drhelius.Gearsystem.yml
+   ```
+
+   The `--force-clean --user --install` flags specify that the build should
+   start from the beginning and, once completed, automatically install the
+   application as a user-specific application. In these cases the application
+   will be installed as `io.github.drhelius.Gearsystem//master`.
+
+   The `build-dir` option indicates that any build files will be kept in a
+   subdirectory with the same name. This may be deleted after a build is
+   complete.
+
+   The final option, `io.github.drhelius.Gearsystem.yml` indicates which
+   manifest file to use for the application build. This manifest file contains
+   the core configuration for how the application is built and any metadata
+   associated with it. Some common modifications include changing the `make`
+   command to `make DEBUG=1` to include debugging symbols or replacing the `git`
+   source with a relative path for local development such as:
+
+   ```yaml
+   - type: dir
+     path: ../..
+   ```
+
+   More information on this command and the manifest can be found on [the
+   Flatpak Builder Command Reference][Flatpak Builder Reference].
+
+4. **Run the application**
+
+   Once installed, the application can be run with the following command:
+
+   ```bash
+   flatpak run io.github.drhelius.Gearsystem
+   ```
+
+   You may also be able to find the application in as a desktop entry, allowing
+   you to search for it in your operating system's desktop environment.
+
+   Starting this application in either manner should result in Gearsystem
+   launching with full functionality.
+
+   There are other options available to this command in [the Flatpak Command
+   Reference][Flatpak Reference] if further debugging is available.
+
+   One such option is the ability to debug the application with gdb. This can
+   be done with the following commands:
+
+   ```bash
+   flatpak install gearsystem-origin io.github.drhelius.Gearsystem.Debug
+   flatpak run \
+       --devel \
+       --command=gdb \
+       io.github.drhelius.Gearsystem /app/bin/gearsystem
+   ```
+
+   The first command installs the `.Debug` extension with the debugging symbols
+   from the local environment `gearsystem-origin`. This should be defined as you
+   build the application, but if this does not work, simple run `flatpak list`
+   and use the value in the `Origin` column corresponding to the `Gearsystem`
+   application.
+
+   The second command will start the GDB application on the Gearsystem binary.
+   You may also run other applications such as `sh` for further debugging.
+
+[Flatpak Builder Reference]: <https://docs.flatpak.org/en/latest/flatpak-builder-command-reference.html>
+[Flatpak Reference]: <https://docs.flatpak.org/en/latest/flatpak-command-reference.html>
+[Flatpak Setup]: <https://flatpak.org/setup/>

platforms/flatpak/io.github.drhelius.Gearsystem.desktop

@@ -0,0 +1,7 @@
+[Desktop Entry]
+Name=Gearsystem
+Comment=Emulator for SMS/GG/SG-1000 games
+Exec=gearsystem
+Type=Application
+Icon=io.github.drhelius.Gearsystem
+Categories=Game;Emulator;

platforms/flatpak/io.github.drhelius.Gearsystem.metainfo.xml

@@ -0,0 +1,178 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<component type="desktop-application">
+  <id>io.github.drhelius.Gearsystem</id>
+
+  <name>Gearsystem</name>
+  <summary>A very accurate, cross-platform Sega Master System / Game Gear / SG-1000 emulator</summary>
+  <content_rating type="oars-1.1" />
+  <developer id="io.github.drhelius">
+    <name>Ignacio Sanchez Gines</name>
+  </developer>
+  <icon type="stock">io.github.drhelius.Gearsystem</icon>
+
+  <metadata_license>CC0-1.0</metadata_license>
+  <project_license>GPL-3.0-only</project_license>
+
+  <supports>
+    <control>pointing</control>
+    <control>keyboard</control>
+    <control>gamepad</control>
+  </supports>
+
+  <description>
+    <p>Gearsystem is a very accurate, cross-platform Sega Master System / Game Gear / SG-1000 emulator written in C++ that runs on Windows, macOS, Linux, BSD and RetroArch.</p>
+    <p>Features include:</p>
+    <ul>
+      <li>Accurate Z80 core, including undocumented opcodes and behavior like R and MEMPTR registers.</li>
+      <li>Supported cartridges: ROM, ROM + RAM, SEGA, Codemasters, Korean, MSX + Nemesis, Janggun, SG-1000.</li>
+      <li>Automatic region detection: NTSC-JAP, NTSC-USA, PAL-EUR.</li>
+      <li>Accurate VDP emulation including timing and Master System 2 only 224 video mode support.</li>
+      <li>Support for YM2413 (OPLL) FM sound chip.</li>
+      <li>Internal database for rom detection.</li>
+      <li>Battery powered RAM save support.</li>
+      <li>Save states.</li>
+      <li>Compressed rom support (ZIP).</li>
+      <li>Game Genie and Pro Action Replay cheat support.</li>
+      <li>Supported platforms (standalone): Windows, Linux, BSD and macOS.</li>
+      <li>Supported platforms (libretro): Windows, Linux, macOS, Raspberry Pi, Android, iOS, tvOS, PlayStation Vita, PlayStation 3, Nintendo 3DS, Nintendo GameCube, Nintendo Wii, Nintendo WiiU, Nintendo Switch, Emscripten, Classic Mini systems (NES, SNES, C64, ...), OpenDingux, RetroFW and QNX.</li>
+      <li>Full debugger with just-in-time disassembler, cpu breakpoints, memory access breakpoints, code navigation (goto address, JP JR and CALL double clicking), debug symbols, memory editor, IO inspector and VRAM viewer including tiles, sprites, backgrounds and palettes.</li>
+      <li>Windows and Linux Portable Mode.</li>
+      <li>Rom loading from the command line by adding the rom path as an argument.</li>
+      <li>Support for modern game controllers through gamecontrollerdb.txt file located in the same directory as the application binary.</li>
+    </ul>
+  </description>
+
+  <categories>
+    <category>Emulator</category>
+    <category>Game</category>
+  </categories>
+
+  <launchable type="desktop-id">io.github.drhelius.Gearsystem.desktop</launchable>
+  <url type="homepage">https://github.com/drhelius/Gearsystem</url>
+  <url type="bugtracker">https://github.com/drhelius/Gearsystem/issues</url>
+  <url type="vcs-browser">https://github.com/drhelius/Gearsystem</url>
+
+  <provides>
+    <binary>gearsystem</binary>
+    <id>io.github.drhelius.Gearsystem.desktop</id>
+  </provides>
+  <bundle type="flatpak">io.github.drhelius.Gearsystem</bundle>
+
+  <releases>
+    <release version="3.5.0" date="2024-03-04">
+      <description>
+        <p><em>What's Changed</em></p>
+        <ul>
+          <li>Support for YM2413</li>
+          <li>Native file dialogs</li>
+          <li>Drag and drop rom files to open</li>
+          <li>Overscan options</li>
+          <li>Improved Game Gear timings</li>
+          <li>Improved PAL detection</li>
+          <li>Debugger improvements</li>
+          <li>Custom folders for saves and savestates</li>
+          <li>Scaling improvements like fit to window size or fit to window height</li>
+          <li>Hide cursor when hovering output window or when main menu is disabled</li>
+          <li>Load symbol files from command line</li>
+          <li>Support for WLA symbol files</li>
+          <li>Improve input response time</li>
+          <li>Save screenshots</li>
+          <li>Support for WSL</li>
+          <li>Automatic builds in GitHub Actions</li>
+          <li>Several bug fixes</li>
+          <li>Add support for zoomed sprites in SMS/GG modes</li>
+          <li>Pixel perfect rendering even with non integer HDPI values on Windows</li>
+          <li>Fixed bug where when resetting, the first opcode would not be disassembled. by @samizzo in #50</li>
+          <li>Added a generalised shortcut system so any gui events can have a shortcut key defined in the config.ini by @samizzo in #52</li>
+          <li>add retrofw target</li>
+          <li>Fix window title flicker</li>
+          <li>Define <code>install</code> and <code>uninstall</code> targets</li>
+          <li>Update NFDe implementation to v1.1.1</li>
+        </ul>
+      </description>
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/3.5.0</url>
+      <artifacts>
+        <artifact type="source">
+          <location>https://github.com/drhelius/Gearsystem/archive/refs/tags/3.5.0.tar.gz</location>
+          <checksum type="sha256">fb284c2c71ab78f5127c5c9b1039dcf18ac518259649ef79900299ac2ea4151f</checksum>
+          <size type="download">6359063</size>
+          <filename>Gearsystem-3.5.0.tar.gz</filename>
+        </artifact>
+      </artifacts>
+    </release>
+    <release version="3.4.1" date="2021-09-04">
+      <description>
+        <p>This patch contains the following bugfixes:</p>
+        <ul>
+          <li>Fixed a crash in RetroArch (libretro) when loading ROMs.</li>
+        </ul>
+      </description>
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-3.4.1</url>
+      <issues>
+        <issue url="https://github.com/drhelius/Gearsystem/issues/48">#48</issue>
+      </issues>
+      <artifacts>
+        <artifact type="source">
+          <location>https://github.com/drhelius/Gearsystem/archive/refs/tags/gearsystem-3.4.1.tar.gz</location>
+          <checksum type="sha256">c71c8415d18afee104aece2b04de0b6736dd2783b0c87b9a6a2bee9530d2d798</checksum>
+          <size type="download">14570974</size>
+          <filename>gearsystem-3.4.1.tar.gz</filename>
+        </artifact>
+      </artifacts>
+    </release>
+    <release version="3.4.0" date="2021-08-14">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-3.4.0</url>
+    </release>
+    <release version="3.3.0" date="2021-02-15">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-3.3.0</url>
+    </release>
+    <release version="3.2.0" date="2020-12-31">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-3.2.0</url>
+    </release>
+    <release version="3.1.0" date="2020-05-24">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-3.1.0</url>
+    </release>
+    <release version="3.0.3" date="2020-04-22">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-3.0.3</url>
+    </release>
+    <release version="3.0.2" date="2020-04-20">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-3.0.2</url>
+    </release>
+    <release version="3.0.1" date="2020-04-13">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-3.0.1</url>
+    </release>
+    <release version="3.0.0" date="2020-04-11">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-3.0.0</url>
+    </release>
+    <release version="2.6.1" date="2019-06-30">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-2.6.1</url>
+    </release>
+    <release version="2.6.0" date="2019-06-29">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-2.6.0</url>
+    </release>
+    <release version="2.5.1" date="2019-03-26">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-2.5.1</url>
+    </release>
+    <release version="2.5.0" date="2019-03-26">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-2.5.0</url>
+    </release>
+    <release version="2.2" date="2016-03-04">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-2.2</url>
+    </release>
+    <release version="2.1" date="2014-11-24">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-2.1</url>
+    </release>
+    <release version="2.0" date="2014-11-11">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-2.0</url>
+    </release>
+    <release version="1.2" date="2014-07-14">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-1.2</url>
+    </release>
+    <release version="1.1" date="2014-06-25">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-1.1</url>
+    </release>
+    <release version="1.0" date="2013-11-01">
+      <url>https://github.com/drhelius/Gearsystem/releases/tag/gearsystem-1.0</url>
+    </release>
+  </releases>
+</component>