Skip to content
/ watson Public template

Watson is a best-practices application template for elementary OS 6 (Odin).

License

Notifications You must be signed in to change notification settings

small-tech/watson

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Watson

“It’s elementary, my dear…”

A best-practices application template for elementary OS 6 (Odin).

Looping GIF of a snippet of Aral Balkan’s video introducing Watson.

Watch the introductory screencast.

Status: Beta.

I’ve now backported everything I learned and created while making Comet into Watson.

Once Comet is on the AppCenter and I’m happy that Watson captures and supports the full elementary OS development cycle, I’ll remove the Beta status.

Want the wallpaper?

What Watson is (and what Watson is not).

Watson gets you up and running quickly with a bare-bones single-window elementary OS 6 (Odin) app that is based on the elementary OS Developer Documentation as well as a review of the conventions employed by the core apps that ship with elementary OS (like Code and Calculator).

It also makes it equally easy for other developers to build and run your application on their own machines after they clone your project’s repository.

Watson includes a number of scripts – to create and run Flatpak packages, update translations, and even take screenshots of your app and preview your app in AppCenter – that make the everyday tasks of working with your application easier.

Finally, Watson includes a simple web site for your app that’s automatically generated from your app’s metadata and contains a basic, progressively-enhanced and accessible carousel of your screenshots as well as a Flatpak repository for your app where people can sideload your app from. To host the generated site, you simply have to turn on GitHub Pages for your app and use the provided publish task script to publish your app and push to your GitHub repository. (You can also host your site on any static host, e.g., using Site.js. If you decide to put your app on the elementary OS AppCenter you can also uncomment a “Get It On AppCenter” button that will open AppCenter at your app’s page. To see an example how you can build on and customise this base site, see the web site for Comet.

When deciding what to include and what to leave out of the generated app, the guiding principle is to include base functionality expected of any elementary OS 6 app. The goal is for you to only have to add to the generated template, not remove from it or change the generated code for common types of apps (with the understanding that multi-window applications and highly custom apps might require a bit of fiddling).

Most importantly, the generated skeletal app complies with the elementary OS Human Interface Guidelines and follows other recommended elementary OS 6 conventions like coding style. If you haven’t already done so, please read through both of those important resources before continuing. Also, to refer to language or library details during development, bookmark Valadoc.

Once you’ve made the generated app your own by customising it and adding to it, you can submit it for inclusion in the elementary OS AppCenter as a curated app.

Watson is not a substitute for knowing what you’re doing. Watson is meant to lower the barrier of entry to creating an elementary OS application by automating the start of a new project to ensure you do not misconfigure your project or leave out important aspects (like window state preservation or translations). So, again, please read the above documents before starting to develop apps for elementary OS.

Goals

  1. The time from when a developer decides to make an elementary OS app to when they have a working project using Watson should be < 60 seconds.

  2. The time from when a developer clones a Watson-generated elementary OS application to when they have it up and running on their own machine should be < 60 seconds.

Furthermore, the generated project must:

Getting started

On GitHub:

  1. Press the green “Use this template” button for this repository to create your new project’s repository using Watson as the template.

On your development machine:

  1. Clone your project and switch to its directory in Terminal:

    git clone git@github.com:<my-org>/<my-app>.git
    cd <my-app>
  2. Initialise your project:

    ./watson

Note on the GitHub-centric workflow: The elementary OS AppCenter currently ties application bundle IDs and the directory structure for assets, etc., to the GitHub project. So your project’s application bundle ID will be something like com.github.small_tech.comet (the init script will automatically convert dashes to underscores as per flatpak’s naming requirements). I have raised my concerns about this both from a legal perspective as it is a trademark violation and, more generally, because it gives Microsoft a de-facto veto right on what apps are allowed on elementary OS. I do hope that this decision will be reviewed going forward. In the meanwhile, however, Watson is designed to make full use of the current system to make setting up a new elementary OS project as simple as possible while following all relevant platform guidelines and encouraging good practices. – Aral

What to expect

Interactive app configuration screens

Watson will ask for your app details in a series of graphical dialogue windows and update the necessary bits of the template files (application bundle IDs, asset paths, etc.) to customise them for your project based on your answers.

It will also replace this README and the CHANGELOG with your application’s versions, recreate the git repository (so you start with a fresh history), make an initial commit, and set up your git remote so origin points to your repository.

Next, Watson will run the install task (task/install).

The install task is also what developers who clone your project will run to ensure that they can build and run your project.

The install task

The install task first checks whether you have the elementary OS development libraries installed and asks you to install them if it can’t find them.

The elementary OS development libraries – also known as the elementary OS Software Development Kit (SDK) – are a metapackage of elementary OS libraries required when creating apps for elementary OS. You can see which libraries are included in the SDK based on the architecture of your development machine by reviewing the following metapackage definitions: AMD64, ARM64, ARMHF.

Next, Watson will check if you have VSCodium installed. If you do, it will check whether or not you have useful set of VSCodium extensions for elementary OS development installed and ask you to install them if you don’t.

You do not need to use VSCodium to create elementary OS apps. You can, for instance, use elementary OS Code, which comes preinstalled, or a different third-party editor like Builder. However, if you do have VSCodium installed, there are a number of extensions that will make creating your elementary OS app easier (Vala, Meson, CodeLLDB, XML, YAML). If Watson cannot find these extensions installed, it will ask you if you’d like to install them now. With these extensions installed, once you’ve initialised your project, you can simple open it in VSCodium and hit F5 to run/debug it and Ctrl + Shift + BBuild all targets to rebuild it after making changes. You will also get code intelligence, etc., for all your source files. Finally, your project will also inform VSCodium of the set of recommended extensions for your project so even if you choose not to install them now, you can easily find and install them later yourself.

Post install

Once the install task is done, Watson will delete itself, leaving only your project behind.

It will also commit and push the changes to your git repository.

And that’s it!

At this point, your project is ready and you can customise the template further to create your own unique and wonderful app, knowing you have a base that adheres to elementary OS guidelines.

You can also run your project using the run script:

task/run

Or, if you’re using VSCodium, just open your project and hit F5 to run/debug it and Ctrl + Shift + BBuild all targets to rebuild it after making changes.

You can find more task scripts in the task folder of your project and the workflow is also documented in the README file that’s generated for your project.

Here’s hoping Watson will make it easier for you to start building and maintaining excellent apps for elementary OS.

What’s included?

What’s not included?

Watson creates a basic single-window elementary OS application using good practices.

Watson’s goal with the generated app is that you should only have to either customise existing functionality (e.g., replace the app logo SVGs with your own), use existing functionality (e.g., add your custom icons or your own translations), or add specialised logic to the generated app. So you shouldn’t have to remove any of the generated functionality. This is why there are no sample widgets or even basic layout generated as that will differ from app to app.

The generated skeleton is just that, the structure you need to quickly get you started with building your own application.

In other words, Watson does not generate a sample app. For widget demos of the underlying libraries, see the Granite demo (sudo apt install granite-demo && granite-demo) and Gtk+ 3 examples/demo (sudo apt install gtk-3-examples && gtk3-demo).

Watson is also not meant to teach you how to build an elementary OS app (see the elementary OS Developer Documentation) and is not a substitute for knowing and applying the elementary OS Human Interface Guidelines as you develop your app.

Finally, while Watson will install the elementary OS development tools and even the recommended VSCodium extensions for you if you ask it to, you need to configure your GitHub account and set up git on your machine yourself. For instructions on how to do this, please see the Basic Setup section of the elementary OS Developer Documentation.

Common functionality you might want to add to your app

Here are some quick links showing you how to add common functionality to your app after you’ve generated it:

General resources

At the risk of sounding like a broken record, please work your way through the elementary OS Developer Documentation) and elementary OS Human Interface Guidelines before starting to create an app for elementary OS 6.

Also please review the AppCenter publishing requirements before you submit your app.

Other important references include:

Similar projects

Get the wallpaper

Illustration, Sherlock Holmes, Watson, Enola Holmes and the three cats from Catts are in a swamp full of alligators. Sherlock is standing on a makeshift wooden bridge examining a bird (one foot on an alligator’s nose). Watson is in the swamp gathering more wood for the bridge. Enola and the blue cat are in a row boat in the background. The purple and green cats are on branches.

The wallpaper you see in the screencast was commissioned for Watson from the singular Margo de Weerdt. And you’re welcome to download and use it in all its 4K glory on your own computer if you like.

(Also available with shallower depth of field – and even shallower depth of field – which you might prefer if you place icons on your desktop so they don’t get lost in the detail.)

Released under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. Please credit Margo de Weerdt and Watson by Small Technology Foundation.

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.

Copyright

© 2021-present Aral Balkan, Small Technology Foundation.

License

GPL version 3.0

About

Watson is a best-practices application template for elementary OS 6 (Odin).

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Sponsor this project

Packages

No packages published