Introduction

Astal is a collection of libraries written in Vala and C, designed to serve as the foundation for both lightweight widgets and fully-featured desktop shells. It handles the backend logic, so you can focus entirely on building the frontend.

History

This project began as a JavaScript-only solution under the AGS project, known as AGS v1. While experimenting with Lua and Python ports, the idea emerged to move most of the codebase to Vala and use GObject Introspection to share components across different language ports. This marked the birth of Astal and the release of AGS v2.

However, I mistakenly included frontend abstractions in Astal, which turned out to be a misstep. Over time, I lost interest in languages other than TypeScript. Eventually, I realized not only that, but also that the initial JSX implementation wasn’t well-suited for GTK4.

After going through several iterations and decoupling the project from Astal, Gnim was created, leading to the emergence of AGS v3.

About this Documentation

The goal of this documentation is to help you get started with writing a GTK application. It provides code snippets, templates, examples, and a list of references to help you learn more about GTK and the Astal libraries.

Supported Languages

For a list of languages that support Gtk see this wikipedia article.

Interpreted languages like JavaScript and Python is supported out of the box while some compiled languages might need extra work to make use of Astal libraries.

Currently we have examples for

• Vala
• JavaScript (GJS)
• Python (PyGObject)

Tools for Frontend

While this documentation shows you how to start building GTK applications, you might also be interested in these projects below. If you decide to use them, be sure to read their documentation first, then return here to pick up libraries you need.

AGS

AGS is a scaffolding tool for Astal + Gnim projects written in TypeScript. Gnim is a library which brings JSX to GJS.

Eww

Eww is a tool that simplifies GTK usage by exposing only a limited set of widgets and allowing you to define UIs using a Lisp-inspired DSL. Many Astal libraries include CLI tools that output JSON, which can be easily integrated into Eww.