Skip to content

Latest commit

 

History

History
191 lines (151 loc) · 8.22 KB

DEVELOP.md

File metadata and controls

191 lines (151 loc) · 8.22 KB
Raw

icon Develop, Build and Contribute to Tuner License: GPL v3

Discover and Listen to your favourite internet radio stations, and add improve the code!

Overview

Tuner is hosted on Github, packaged as a Flatpak and distributed by Flathub. Tuner is writen in Vala, a C#/Java/JavaFX-like language with a self-hosting compiler that generates C code and uses the GObject type system and wrapping a number of GTK libraries. It uses Meson as its build system.

Tuner has not undergone a lot of attention in a while, and would benefit from a review with an eye to refactoring and cleaning up the code, while in the short term addressing known bugs and fixing basic functional issues, documentation and also making it easier to build and test.

Tuner Development

Hosted on Github, the main branch reflects the current stable release. The development branch is the development branch and where releases are staged. Pull Requests should be made against the development branch.

Dependencies

Development dependencies for Tuner are:

granite
gstreamer-1.0
gstreamer-player-1.0
gtk+-3.0
json-glib-1.0
libgee-0.8
libsoup-3.0
meson
vala

Install required dependencies (Debian/Ubuntu):

sudo apt install git valac meson
sudo apt install libgtk-3-dev libgee-0.8-dev libgranite-dev libgstreamer1.0-dev libgstreamer-plugins-bad1.0-dev libsoup-3.0-dev libjson-glib-dev

Building the Tuner App From Source

There are two build configurations: debug and release. The debug build (manifest com.github.louis77.tuner.debug.yml) is recommended for development, while the release build (manifest com.github.louis77.tuner.yml) is for distribution. Build instructions will focus on the debug build. Copy the required manifest to com.github.louis77.tuner.xml before building.

Clone the repo and drop into the Tuner directory:

git clone https://github.com/louis77/tuner.git
cd tuner

Configure Meson for development debug build, build Tuner with Ninja, and run the result:

meson setup --buildtype=debug builddir
meson compile -C builddir
meson install -C builddir     # only needed once to get the gschema in place
./builddir/com.github.louis77.tuner

Tuner can be deployed to the local system to bypass flatpak if required, however it is recommended to use flatpak.To do deploy locally, run the following command:

meson configure -Dprefix=/usr
sudo ninja install

Building the Tuner Flatpak

Tuner uses the elementary.io platform, version 8. To build the tuner flatpak, install the elementry SDK and Platform:

apt-get install flatpak-builder
flatpak remote-add --user --if-not-exists elementary https://flatpak.elementary.io/repo.flatpakrepo
flatpak install elementary io.elementary.Sdk//8 io.elementary.Platform//8

Build the flatpak in the user scope:

flatpak-builder --force-clean --user --sandbox --install build-dir com.github.louis77.tuner.debug.yml

Run the Tuner flatpack:

flatpak --user run com.github.louis77.tuner

Check the app version to ensure that it matches the version in the manifest.

Readying code for a Pull Request

Before a pull request can be accepted, the code must pass linting. This is done by running the following command:

flatpak run --command=flatpak-builder-lint org.flatpak.Builder manifest com.github.louis77.tuner.yml

Linting currently produces the following issues (adddressed in ticket #140):

{
    "errors": [
        "appid-uses-code-hosting-domain"
    ],
    "info": [
        "appid-uses-code-hosting-domain: github.com"
    ],
    "message": "Please consult the documentation at https://docs.flathub.org/docs/for-app-authors/linter"
}

Ensure that the CI checks pass before pushing your changes.

NamingConventions

Going forward, all new code should conform to the following naming conventions:

  • Namespaces are named in camel case: NameSpaceName
  • Classes are named in camel case: ClassName
  • Method names are all lowercase and use underscores to separate words: method_name
  • Constants (and values of enumerated types) are all uppercase, with underscores between words: CONSTANT_NAME
  • Public properties are named in camel case: propertyName
  • Private member variables are named all lowercase and use underscores to separate words prefixed with an underscore: _var_name

Debugging

VSCode

Debugging from VSCode using GDB, set up the launch.json file as follows:

{
  "version": "0.2.0",
  "configurations": [    
    {
      "name": "Debug Vala with Meson",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/builddir/com.github.louis77.tuner",
      "args": [],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}",
      "environment": [],
      "externalConsole": false,
      "MIMode": "gdb",
      "miDebuggerPath": "/usr/bin/gdb",
      "setupCommands": [
        {
          "description": "Enable pretty-printing for gdb",
          "text": "-enable-pretty-printing",
          "ignoreFailures": true
        }
      ],
      "preLaunchTask": "meson build"
    }
  ]
}

Note: Variables appear as pointers, and generated code is not found. Please submit a better config if you have one.

Bug Introduction Deduction

Knowing when a bug was introduced requires building previous versions and looking for the aberrent behavior. The following commands can be used to check out previous versions of the code:

git fetch
git tag
git checkout <tag>

After checking out the required version, build and run the app as described above.

Release Process

Releasing Tuner comprises cutting a release of the code in tuner github and then updating the flathub repo which will automatically have the flatpak generated and rolled to Flathub for distribution.

Beta Releases

Beta releases should be tagged from the Tuner development branch in with a version number format of v1.*.*-beta.*

Once a beta release has been tagged, the Flathub beta branch can be updated via a pull request with the beta tag going into the manifest .json, and any patches and documentation updated as needed. The pull request will trigger a flathub build, but will not merge the pull request - pull requests should be merged only if they result in a successful build.

Once the beta is successfully built by flathub it will be available for installation and testing within the user community.

Once a beta roll is deamed a success its pull request can be merged, and a production release can be rolled.

Production Releases

Production releases are generated from development pull requests into main. The updated main branch should be tagged with a version number format of v1.*.*

Once a release has been tagged, the flathub repo main branch can be updated with the release tag going into the manifest .json, and any patches and documentation updated as needed. Updates from the main branch should be copied in from a direct pull request of the main branch. The main branch should not come from a merge beta branch to avoid triggering subsequent builds in beta .

Once the main production release is built by flathub it will be available for installation and automatically distributed to user community.