From c6e16ff27244dafecb654c65d1d416f12673ed71 Mon Sep 17 00:00:00 2001 From: raf Date: Thu, 10 Oct 2024 04:29:27 +0000 Subject: docs: fix typo in nix guide --- docs/guide/getting-started/nix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/guide/getting-started') diff --git a/docs/guide/getting-started/nix.md b/docs/guide/getting-started/nix.md index c9ed270..81f4e4d 100644 --- a/docs/guide/getting-started/nix.md +++ b/docs/guide/getting-started/nix.md @@ -20,7 +20,7 @@ Using Astal on Nix will require you to package your project. system = "x86_64-linux"; pkgs = nixpkgs.legacyPackages.${system}; in { - packages.${system}.default = astal.lib.mkLuaPacakge { + packages.${system}.default = astal.lib.mkLuaPackage { inherit pkgs; src = ./path/to/project; # should contain init.lua -- cgit v1.2.3 From dd3bae59362f0b6c3d47cc81b5c53888362e75fc Mon Sep 17 00:00:00 2001 From: Aylur <104676705+Aylur@users.noreply.github.com> Date: Fri, 11 Oct 2024 23:30:16 +0200 Subject: Update installation.md --- docs/guide/getting-started/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/guide/getting-started') diff --git a/docs/guide/getting-started/installation.md b/docs/guide/getting-started/installation.md index ef5c6e8..af82cf5 100644 --- a/docs/guide/getting-started/installation.md +++ b/docs/guide/getting-started/installation.md @@ -44,7 +44,7 @@ sudo dnf install meson gcc valac gtk3-devel gtk-layer-shell-devel gobject-intros ``` ```sh [ Ubuntu] -sudo apt install meson valac libgtk3-dev libgtk-layer-shell-dev gobject-introspection +sudo apt install meson valac libgtk-3-dev libgtk-layer-shell-dev gobject-introspection libgirepository1.0-dev ``` ::: -- cgit v1.2.3 From ede8890a08b3fbbb1f6df3b8c277ab6424d1befd Mon Sep 17 00:00:00 2001 From: Aylur Date: Tue, 15 Oct 2024 01:22:24 +0000 Subject: docs: better explain ags --- docs/guide/getting-started/installation.md | 14 ++++++++++++- docs/guide/getting-started/introduction.md | 19 +++++++++-------- docs/guide/getting-started/nix.md | 20 +++++++++++++++--- docs/guide/getting-started/supported-languages.md | 25 ++++++++++++----------- 4 files changed, 54 insertions(+), 24 deletions(-) (limited to 'docs/guide/getting-started') diff --git a/docs/guide/getting-started/installation.md b/docs/guide/getting-started/installation.md index af82cf5..6ad951a 100644 --- a/docs/guide/getting-started/installation.md +++ b/docs/guide/getting-started/installation.md @@ -10,6 +10,8 @@ Read more about it on the [nix page](./nix#astal) maintainer: [@kotontrion](https://github.com/kotontrion) + + :::code-group ```sh [Core Library] @@ -28,7 +30,6 @@ yay -S libastal-meta ```sh git clone https://github.com/aylur/astal.git -cd astal/core ``` 2. Install the following dependencies @@ -51,7 +52,18 @@ sudo apt install meson valac libgtk-3-dev libgtk-layer-shell-dev gobject-introsp 3. Build and install with `meson` +- astal-io + +```sh +cd lib/astal/io +meson setup build +meson install -C build +``` + +- astal3 + ```sh +cd lib/astal/gtk3 meson setup build meson install -C build ``` diff --git a/docs/guide/getting-started/introduction.md b/docs/guide/getting-started/introduction.md index 92d2ff1..af176c3 100644 --- a/docs/guide/getting-started/introduction.md +++ b/docs/guide/getting-started/introduction.md @@ -2,22 +2,25 @@ ## What is Astal? -Astal (_meaning "desk"_) is a bundle of libraries built using [GLib](https://docs.gtk.org/glib/) in Vala and C. -The core library [libastal](https://aylur.github.io/libastal) has some Gtk widgets that come packaged, -the most important one is the [Window](https://aylur.github.io/libastal/class.Window.html) which is the main toplevel component using [gtk-layer-shell](https://github.com/wmww/gtk-layer-shell). +Astal (_meaning "desk"_) is a suite of libraries in Vala and C. +The core library [astal3](https://aylur.github.io/libastal/astal3) and +[astal4](https://aylur.github.io/libastal/astal4) (not yet available) +has some Gtk widgets that come packaged, +the most important one being the [Window](https://aylur.github.io/libastal/class.Window.html) which is the main toplevel component using [gtk-layer-shell](https://github.com/wmww/gtk-layer-shell). This is what allows us to use Gtk as shell components on Wayland. -libastal also comes with some utility functions such as running external processes, -reading, writing and monitoring files. +The other part of the core library [astal-io](https://aylur.github.io/libastal/astal-io) +which contains some utility GLib shortcut for running external processes, +reading, writing and monitoring files, timeout and interval functions. ## Why Astal? -What makes Astal convenient to use is not the core library, as it could easily be replaced +What makes Astal convenient to use is not the core libraries, as they can easily be replaced by the standard library of any of your favorite language that has bindings to Gtk, it is the -accompanying libraries (_formerly known as "services" in AGS_) +accompanying libraries (_formerly known as "services" in AGS_). Have you ever wanted to write a custom bar, custom notification popups or an applauncher, but gave up because writing a workspace widget, implementing the notification daemon or handling a search filter was too much of a hassle? -Astal libraries have you [covered](/guide/libraries/references), you don't have to worry about these, +Astal libraries have you [covered](../libraries/references#astal-libraries), you don't have to worry about these, you just define the layout, style it with CSS and that's it. diff --git a/docs/guide/getting-started/nix.md b/docs/guide/getting-started/nix.md index 81f4e4d..5c0db28 100644 --- a/docs/guide/getting-started/nix.md +++ b/docs/guide/getting-started/nix.md @@ -1,3 +1,8 @@ +--- +next: + link: '/guide/getting-started/supported-languages' + text: 'Supported Languages' +--- # Nix ## Astal @@ -74,11 +79,16 @@ Using Astal on Nix will require you to package your project. } ``` +```nix [ TypeScript] +# The usage of AGS (read below) is recommended +# Usage without AGS is not yet documented +``` + ::: ## AGS -The recommended way to use AGS on NixOS is through the home-manager module. +The recommended way to use [AGS](../ags/first-widgets#first-widgets) on NixOS is through the home-manager module. Example content of a `flake.nix` file that contains your `homeConfigurations`. @@ -144,7 +154,7 @@ Example content of `home.nix` file ::: -AGS by default only includes the core `libastal` library. +AGS by default only includes the core `astal3/astal4` and `astal-io` libraries. If you want to include any other [library](../libraries/references) you have to add them to `extraPackages`. You can also add binaries which will be added to the gjs runtime. @@ -158,7 +168,11 @@ The AGS flake does not expose the `astal` cli to the home environment, you have :::code-group ```nix [ home.nix] -home.packages = [ inputs.ags.packages.${pkgs.system}.astal ]; +home.packages = [ inputs.ags.packages.${pkgs.system}.default ]; +``` + +```sh [ sh] +astal --help ``` ::: diff --git a/docs/guide/getting-started/supported-languages.md b/docs/guide/getting-started/supported-languages.md index 4cb7f3a..47d5dbd 100644 --- a/docs/guide/getting-started/supported-languages.md +++ b/docs/guide/getting-started/supported-languages.md @@ -1,9 +1,15 @@ # Supported Languages +There are currently two languages that have an additional +Astal package: Lua and Gjs. Their purpose is to abstract away +Gtk by implementing a state management and UI declaring solution. + ## JavaScript -The main intended usage of Astal is in TypeScript with [AGS](/guide/ags/first-widgets). -It supports JSX and has a state management solution similar to web frameworks. +The main intended usage of Astal is in TypeScript+JSX. +It is recommended to use [AGS](/guide/ags/first-widgets) to scaffold and run projects in TypeScript. +However, if you are familiar with JavaScript's tooling +ecosystem you can also setup an environment yourself. Only a minimal knowledge of JavaScript's syntax is needed to get started. :::info @@ -17,11 +23,7 @@ Examples: ## Lua -Similar to how there is a [TypeScript](https://github.com/Aylur/astal/tree/main/core/gjs) lib for GJS, there is also an accompanying library for [Lua](https://github.com/Aylur/astal/tree/main/core/lua). - -Unfortunately, I have encountered very heavy [performance issues](https://github.com/aylur/astal) with [lgi](https://github.com/lgi-devs/lgi), -and so currently I don't recommend using Lua for full desktop shells, but only for static -components that don't render child nodes dynamically, bars and panels for example. +Lua is well-supported, but I would still recommend TypeScript, as Lua lacks a type system, which in turn limits editor support. Examples: @@ -30,10 +32,9 @@ Examples: ## Python -There was a WIP [library for python](https://github.com/aylur/astal/tree/feat/python), to make it behave similar to the above two -but I don't plan on finishing it, because I'm not a fan of python. -If you are interested in picking it up, feel free to open a PR. -Nonetheless you can still use python the OOP way [pygobject](https://pygobject.gnome.org/tutorials/gobject/subclassing.html) intended it. +There is a WIP [package for python](https://github.com/aylur/astal/tree/feat/python), +to bring declaritivity to Python similar to the above two languages. +However, you can still use python the OOP way [pygobject](https://pygobject.gnome.org/tutorials/gobject/subclassing.html) intended it in the meantime. Examples: @@ -44,7 +45,7 @@ Examples: Vala is a language that simply put uses C# syntax and compiles to C. It is the language most of Astal is written in. I would still recommend -using TypeScript or Lua over Vala as they don't need a build step. +using TypeScript or Lua over Vala as they are simpler to work with. Examples: -- cgit v1.2.3 From fe11c037bad45697451b7264ff93fa37f1fac78f Mon Sep 17 00:00:00 2001 From: Aylur Date: Tue, 15 Oct 2024 11:55:53 +0000 Subject: docs: recommend /usr prefix by default --- docs/guide/getting-started/installation.md | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) (limited to 'docs/guide/getting-started') diff --git a/docs/guide/getting-started/installation.md b/docs/guide/getting-started/installation.md index 6ad951a..96cbdfa 100644 --- a/docs/guide/getting-started/installation.md +++ b/docs/guide/getting-started/installation.md @@ -56,7 +56,7 @@ sudo apt install meson valac libgtk-3-dev libgtk-layer-shell-dev gobject-introsp ```sh cd lib/astal/io -meson setup build +meson setup --prefix /usr build meson install -C build ``` @@ -64,18 +64,6 @@ meson install -C build ```sh cd lib/astal/gtk3 -meson setup build -meson install -C build -``` - -:::tip -Most distros recommend manual installs in `/usr/local`, -which is what `meson` defaults to. If you want to install to `/usr` -instead which most package managers do, set the `prefix` option: - -```sh meson setup --prefix /usr build meson install -C build ``` - -::: -- cgit v1.2.3 From bafd48d3df9b43a1d49ec015eff30619d595468b Mon Sep 17 00:00:00 2001 From: Aylur Date: Tue, 15 Oct 2024 13:25:45 +0000 Subject: update lua and gjs layout installing the gjs package through meson or npm now results in the same exposed structure lua: fix rockspec docs: aur package --- docs/guide/getting-started/installation.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs/guide/getting-started') diff --git a/docs/guide/getting-started/installation.md b/docs/guide/getting-started/installation.md index 96cbdfa..aaa6d0d 100644 --- a/docs/guide/getting-started/installation.md +++ b/docs/guide/getting-started/installation.md @@ -10,12 +10,10 @@ Read more about it on the [nix page](./nix#astal) maintainer: [@kotontrion](https://github.com/kotontrion) - - :::code-group ```sh [Core Library] -yay -S libastal-git +yay -S libastal-io-git libastal-git ``` ```sh [Every Library] -- cgit v1.2.3 From b33c3bf91dbbea13b1a2c8603e00809b22cd42c8 Mon Sep 17 00:00:00 2001 From: Aylur Date: Tue, 15 Oct 2024 13:36:16 +0000 Subject: docs: fix links --- docs/guide/getting-started/introduction.md | 2 +- docs/guide/getting-started/nix.md | 2 +- docs/guide/getting-started/supported-languages.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/guide/getting-started') diff --git a/docs/guide/getting-started/introduction.md b/docs/guide/getting-started/introduction.md index af176c3..782c069 100644 --- a/docs/guide/getting-started/introduction.md +++ b/docs/guide/getting-started/introduction.md @@ -6,7 +6,7 @@ Astal (_meaning "desk"_) is a suite of libraries in Vala and C. The core library [astal3](https://aylur.github.io/libastal/astal3) and [astal4](https://aylur.github.io/libastal/astal4) (not yet available) has some Gtk widgets that come packaged, -the most important one being the [Window](https://aylur.github.io/libastal/class.Window.html) which is the main toplevel component using [gtk-layer-shell](https://github.com/wmww/gtk-layer-shell). +the most important one being the [Window](https://aylur.github.io/libastal/astal3/class.Window.html) which is the main toplevel component using [gtk-layer-shell](https://github.com/wmww/gtk-layer-shell). This is what allows us to use Gtk as shell components on Wayland. The other part of the core library [astal-io](https://aylur.github.io/libastal/astal-io) which contains some utility GLib shortcut for running external processes, diff --git a/docs/guide/getting-started/nix.md b/docs/guide/getting-started/nix.md index 5c0db28..1d50d35 100644 --- a/docs/guide/getting-started/nix.md +++ b/docs/guide/getting-started/nix.md @@ -88,7 +88,7 @@ Using Astal on Nix will require you to package your project. ## AGS -The recommended way to use [AGS](../ags/first-widgets#first-widgets) on NixOS is through the home-manager module. +The recommended way to use [AGS](../typescript/first-widgets#first-widgets) on NixOS is through the home-manager module. Example content of a `flake.nix` file that contains your `homeConfigurations`. diff --git a/docs/guide/getting-started/supported-languages.md b/docs/guide/getting-started/supported-languages.md index 47d5dbd..d6d669d 100644 --- a/docs/guide/getting-started/supported-languages.md +++ b/docs/guide/getting-started/supported-languages.md @@ -7,7 +7,7 @@ Gtk by implementing a state management and UI declaring solution. ## JavaScript The main intended usage of Astal is in TypeScript+JSX. -It is recommended to use [AGS](/guide/ags/first-widgets) to scaffold and run projects in TypeScript. +It is recommended to use [AGS](/guide/typescript/first-widgets) to scaffold and run projects in TypeScript. However, if you are familiar with JavaScript's tooling ecosystem you can also setup an environment yourself. Only a minimal knowledge of JavaScript's syntax is needed to get started. -- cgit v1.2.3 From 41fcfae3b5624aa16a8046c0197c35bd80257288 Mon Sep 17 00:00:00 2001 From: Aylur <104676705+Aylur@users.noreply.github.com> Date: Sat, 19 Oct 2024 14:52:31 +0200 Subject: Update installation.md --- docs/guide/getting-started/installation.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'docs/guide/getting-started') diff --git a/docs/guide/getting-started/installation.md b/docs/guide/getting-started/installation.md index aaa6d0d..e936bc4 100644 --- a/docs/guide/getting-started/installation.md +++ b/docs/guide/getting-started/installation.md @@ -24,13 +24,8 @@ yay -S libastal-meta ## Bulding libastal from source -1. Clone the repo -```sh -git clone https://github.com/aylur/astal.git -``` - -2. Install the following dependencies +1. Install the following dependencies :::code-group @@ -46,6 +41,13 @@ sudo dnf install meson gcc valac gtk3-devel gtk-layer-shell-devel gobject-intros sudo apt install meson valac libgtk-3-dev libgtk-layer-shell-dev gobject-introspection libgirepository1.0-dev ``` +2. Clone the repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal +``` + ::: 3. Build and install with `meson` -- cgit v1.2.3 From eb3912af64038fb10b35a66ed64d4d9375b612a1 Mon Sep 17 00:00:00 2001 From: Aylur Date: Sat, 19 Oct 2024 13:03:03 +0000 Subject: update installation.md --- docs/guide/getting-started/installation.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) (limited to 'docs/guide/getting-started') diff --git a/docs/guide/getting-started/installation.md b/docs/guide/getting-started/installation.md index e936bc4..844de25 100644 --- a/docs/guide/getting-started/installation.md +++ b/docs/guide/getting-started/installation.md @@ -24,7 +24,6 @@ yay -S libastal-meta ## Bulding libastal from source - 1. Install the following dependencies :::code-group @@ -41,21 +40,20 @@ sudo dnf install meson gcc valac gtk3-devel gtk-layer-shell-devel gobject-intros sudo apt install meson valac libgtk-3-dev libgtk-layer-shell-dev gobject-introspection libgirepository1.0-dev ``` +::: + 2. Clone the repo ```sh -git clone https://github.com/aylur/astal.git -cd astal +git clone https://github.com/aylur/astal.git /tmp/astal ``` -::: - 3. Build and install with `meson` - astal-io ```sh -cd lib/astal/io +cd /tmp/astal/lib/astal/io meson setup --prefix /usr build meson install -C build ``` @@ -63,7 +61,7 @@ meson install -C build - astal3 ```sh -cd lib/astal/gtk3 +cd /tmp/astal/lib/astal/gtk3 meson setup --prefix /usr build meson install -C build ``` -- cgit v1.2.3 From e220873b5a9c124b742b221c209334045e2b783c Mon Sep 17 00:00:00 2001 From: Aylur <104676705+Aylur@users.noreply.github.com> Date: Wed, 23 Oct 2024 01:22:32 +0200 Subject: Update nix.md --- docs/guide/getting-started/nix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/guide/getting-started') diff --git a/docs/guide/getting-started/nix.md b/docs/guide/getting-started/nix.md index 1d50d35..1e0572e 100644 --- a/docs/guide/getting-started/nix.md +++ b/docs/guide/getting-started/nix.md @@ -168,7 +168,7 @@ The AGS flake does not expose the `astal` cli to the home environment, you have :::code-group ```nix [ home.nix] -home.packages = [ inputs.ags.packages.${pkgs.system}.default ]; +home.packages = [ inputs.ags.packages.${pkgs.system}.io ]; ``` ```sh [ sh] -- cgit v1.2.3