Skip to content

DEVELOP.md

Latest commit

 

History

History
293 lines (219 loc) · 10.1 KB

DEVELOP.md

File metadata and controls

293 lines (219 loc) · 10.1 KB

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 written in Vala, a C#/Java/JavaFX-like language with a self-hosting compiler that generates C code, uses the GObject type system and wrapping a number of GTK libraries, and utilizes GNOME internationalization and localization (i18n) for user-facing strings, which are translated via Weblate. Meson is the build system.

TL;DR

gh repo clone yourusername/tuner
cd tuner
checkout development
meson setup --buildtype=debug builddir
meson compile -C builddir
./builddir/io.github.tuner_labs.tuner
flatpak-builder --force-clean --user --sandbox --install build-dir io.github.tuner_labs.tuner.yml
flatpak --user run io.github.tuner_labs.tuner

Prerequisites

Licenses

Tuner is licensed under GPL-3.0-or-later Compliance can be checked using Reuse linter:

reuse lint

Naming Conventions

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

Dependencies

Development dependencies for Tuner are:

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 libgstreamer1.0-dev libgstreamer-plugins-bad1.0-dev libsoup-3.0-dev libjson-glib-dev

Tuner Development Lifecycle

Hosted on Github, the main branch reflects captured the current release and tags. The development branch is the destination for in progress code, translations and where releases are staged. Fork the project and develop on your forks' development branch. All Pull Requests should be made against the development branch.

The development lifecycle is:

  • Build Tuner from Source
    • Checkout development branch
    • Setup the build
    • Local build and confirm
  • Update the Code
    • Modify code
    • Local build
    • Test
    • Flatpak Build
    • Local Flatpak User build and test
    • Github Flatpak build and test
    • Pull Request

Building Tuner From Source

After Forking your own copy of the Tuner project from https://github.com/tuner-labs/tuner, clone your copy to your development machine then checkout the development branch:

gh repo clone yourusername/tuner
cd tuner
checkout development

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

Clone the repo and drop into the Tuner directory:

git clone https://github.com/tuner-app/tuner.git
cd tuner

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

meson setup --buildtype=debug builddir -Dtranslate=update
meson compile -C builddir
meson install -C builddir     # only needed once to get the gschema in place
./builddir/io.github.tuner_labs.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

Valadoc

valadoc --force \
  --pkg gtk+-3.0 --pkg glib-2.0 \
  --pkg gee-0.8 --pkg gio-2.0 \
  --pkg libsoup-3.0 --pkg json-glib-1.0 \
  --pkg gstreamer-1.0 --pkg gstreamer-player-1.0 \
  --pkg granite \
  --package-name=Tuner \
  --directory=src \
  -o apidocs \
  --verbose
  $(find src -type f -name '*.vala')

Local Build and Test

meson compile -C builddir meson compile -C builddir export-and-compile-local-schemas GSETTINGS_SCHEMA_DIR="builddir/data" ./builddir/io.github.tuner_labs.tuner gdb -ex "set environment GSETTINGS_SCHEMA_DIR=builddir/data" -ex run -ex bt --args ./builddir/io.github.tuner_labs.tuner

Building the Tuner Flatpak

Tuner uses the org.freedesktop.Sdk version 25.08 with the Vala extension. To build the tuner flatpak, install the freedesktop SDK, Platform and Vala extension. For example, for x86:

apt-get install flatpak-builder
flatpak install flathub org.freedesktop.Platform//x86_64//25.08
flatpak install flathub org.freedesktop.Sdk//x86_64//25.08
flatpak install flathub org.freedesktop.Sdk.Extension.vala/x86_64/25.08

Build the flatpak in the user scope with and without debug:

flatpak-builder --force-clean --user --sandbox --install build-dir io.github.tuner_labs.tuner.debug.yml

flatpak-builder --force-clean --user --sandbox --install build-dir io.github.tuner_labs.tuner.yml

Run the Tuner flatpak:

flatpak --user run io.github.tuner_labs.tuner

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

Readying code for a Pull Request

Build Changes

If the build has changed it may be required to update repository check-in Action workflows in the .github directory prior to check-in. For example if the Platform changes the Repository Build and Test and CI actions need to be updated and pushed prior to code changes are pushed. It is also good practice to check to see if the action components themselves have been superseded and need to reference new versions.

Language Changes & Translations

Changes to strings that are internationalized require translation via Weblate and reintegration of the new translations, the .po files, into the build via a Weblate pull request.

If translatable strings have been update for translation by GNOME gettext require that the .pot file be regenerated, checked in and pushed to the development branch for Weblate to pick them up. If Countries or Languages, or if other strings in the Application have changed, or if the package extra metadata has changed, the regeneration commands are:

meson compile -C builddir countries-pot
meson compile -C builddir application-pot
meson compile -C builddir extra-pot

If the .po files change, the meson build setup should be rerun.

Code Changes

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 io.github.tuner_labs.tuner.yml

Linting currently produces the following issues (addressed 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.

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/io.github.tuner_labs.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 aberrant 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

Cutting a releasing Tuner on github and packaging and pushing out a new Flathub distribution are covered in the release doc