diff options
Diffstat (limited to 'docs/guide')
24 files changed, 663 insertions, 851 deletions
diff --git a/docs/guide/getting-started/installation.md b/docs/guide/getting-started/installation.md index fa7863e..e32b6a9 100644 --- a/docs/guide/getting-started/installation.md +++ b/docs/guide/getting-started/installation.md @@ -1,11 +1,5 @@ # Installation -## Nix - -maintainer: [@Aylur](https://github.com/Aylur) - -Read more about it on the [nix page](./nix#astal) - ## Arch maintainer: [@kotontrion](https://github.com/kotontrion) @@ -22,7 +16,13 @@ yay -S libastal-meta ::: -## Bulding libastal from source +## Nix + +maintainer: [@Aylur](https://github.com/Aylur) + +Read more about it on the [nix page](./nix#astal) + +## Bulding From Source 1. Install the following dependencies diff --git a/docs/guide/getting-started/nix.md b/docs/guide/getting-started/nix.md index 1e0572e..6bc5d9b 100644 --- a/docs/guide/getting-started/nix.md +++ b/docs/guide/getting-started/nix.md @@ -5,13 +5,15 @@ next: --- # Nix -## Astal - Using Astal on Nix will require you to package your project. +## TypeScript + +Using [AGS](https://aylur.github.io/ags/) as the bundler. + :::code-group -```nix [<i class="devicon-lua-plain"></i> Lua] +```nix [<i class="devicon-nixos-plain"></i> flake.nix] { inputs = { nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; @@ -19,80 +21,49 @@ Using Astal on Nix will require you to package your project. url = "github:aylur/astal"; inputs.nixpkgs.follows = "nixpkgs"; }; + ags = { + url = "github:aylur/ags"; + inputs.nixpkgs.follows = "nixpkgs"; + }; }; - outputs = { self, nixpkgs, astal }: let + outputs = { self, nixpkgs, astal, ags }: let system = "x86_64-linux"; pkgs = nixpkgs.legacyPackages.${system}; in { - packages.${system}.default = astal.lib.mkLuaPackage { - inherit pkgs; - src = ./path/to/project; # should contain init.lua - - # add extra glib packages or binaries - extraPackages = [ - astal.packages.${system}.battery - pkgs.dart-sass + packages.${system}. default = pkgs.stdenvNoCC.mkDerivation rec { + name = "my-shell"; + src = ./.; + + nativeBuildInputs = [ + ags.packages.${system}.default + pkgs.wrapGAppsHook + pkgs.gobject-introspection ]; - }; - }; -} -``` -```nix [<i class="devicon-python-plain"></i> Python] -# Not documented yet -``` - -```nix [<i class="devicon-vala-plain"></i> Vala] -# keep in mind that this is just the nix derivation -# and you still have to use some build tool like meson -{ - inputs = { - nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; - astal.url = "github:aylur/astal"; - }; - - outputs = { self, nixpkgs, astal }: let - system = "x86_64-linux"; - pkgs = nixpkgs.legacyPackages.${system}; - in { - packages.${system} = { - default = pkgs.stdenv.mkDerivation { - name = "my-shell"; - src = ./.; - - nativeBuildInputs = with pkgs; [ - meson - ninja - pkg-config - vala - gobject-introspection - ]; + buildInputs = with astal.packages.${system}; [ + astal3 + io + # any other package + ]; - # add extra packages - buildInputs = [ - astal.packages.${system}.astal - ]; - }; + installPhase = '' + mkdir -p $out/bin + ags bundle app.ts $out/bin/${name} + ''; }; }; } ``` -```nix [<i class="devicon-typescript-plain"></i> TypeScript] -# The usage of AGS (read below) is recommended -# Usage without AGS is not yet documented -``` - ::: -## AGS - -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`. +:::tip +You can use any other bundler too like `esbuild` +which is what `ags` uses under the hood. +::: -<!--TODO: remove v2 after merge--> +## Lua :::code-group @@ -100,28 +71,26 @@ Example content of a `flake.nix` file that contains your `homeConfigurations`. { inputs = { nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; - home-manager = { - url = "github:nix-community/home-manager"; + astal = { + url = "github:aylur/astal"; inputs.nixpkgs.follows = "nixpkgs"; }; - - # add ags https://github.com/Aylur/ags/pull/504 - ags.url = "github:aylur/ags/v2"; }; - outputs = { home-manager, nixpkgs, ... }@inputs: - let + outputs = { self, nixpkgs, astal }: let system = "x86_64-linux"; - in - { - homeConfigurations."${username}" = home-manager.lib.homeManagerConfiguration { - pkgs = import nixpkgs { inherit system; }; - - # pass inputs as specialArgs - extraSpecialArgs = { inherit inputs; }; + pkgs = nixpkgs.legacyPackages.${system}; + in { + packages.${system}.default = astal.lib.mkLuaPackage { + inherit pkgs; + name = "my-shell"; # how to name the executable + src = ./path/to/project; # should contain init.lua - # import your home.nix - modules = [ ./home-manager/home.nix ]; + # add extra glib packages or binaries + extraPackages = [ + astal.packages.${system}.battery + pkgs.dart-sass + ]; }; }; } @@ -129,65 +98,58 @@ Example content of a `flake.nix` file that contains your `homeConfigurations`. ::: -Example content of `home.nix` file +## Python :::code-group -```nix [<i class="devicon-nixos-plain"></i> home.nix] -{ inputs, pkgs, ... }: -{ - # add the home manager module - imports = [ inputs.ags.homeManagerModules.default ]; - - programs.ags = { - enable = true; - configDir = ../ags; - - # additional packages to add to gjs's runtime - extraPackages = with pkgs; [ - inputs.ags.packages.${pkgs.system}.battery - fzf - ]; - }; -} +```nix [<i class="devicon-nixos-plain"></i> flake.nix] +# Not documented yet ``` ::: -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. - -:::warning -The `configDir` option symlinks the given path to `~/.config/ags`. -If you already have your source code there leave it as `null`. -::: +## Vala -The AGS flake does not expose the `astal` cli to the home environment, you have to do that yourself if you want: +Keep in mind that this is just the nix derivation +and you still have to use some build tool like meson. :::code-group -```nix [<i class="devicon-nixos-plain"></i> home.nix] -home.packages = [ inputs.ags.packages.${pkgs.system}.io ]; -``` - -```sh [<i class="devicon-bash-plain"></i> sh] -astal --help -``` - -::: - -Same applies to the `extraPackages` option, it does not expose the passed packages to the home environment. -To make astal cli tools available to home environments, you have to add them yourself: - -:::code-group +```nix [<i class="devicon-nixos-plain"></i> flake.nix] +{ + inputs = { + nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; + astal = { + url = "github:aylur/astal"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + }; -```nix [<i class="devicon-nixos-plain"></i> home.nix] -home.packages = [ inputs.ags.packages.${pkgs.system}.notifd ]; -``` + outputs = { self, nixpkgs, astal }: let + system = "x86_64-linux"; + pkgs = nixpkgs.legacyPackages.${system}; + in { + packages.${system}.default = pkgs.stdenv.mkDerivation { + name = "my-shell"; + src = ./.; + + nativeBuildInputs = with pkgs; [ + meson + ninja + pkg-config + vala + gobject-introspection + ]; -```sh [<i class="devicon-bash-plain"></i> sh] -astal-notifd --help + buildInputs = [ + astal.packages.${system}.io + astal.packages.${system}.astal3 + astal.packages.${system}.battery + # add extra packages + ]; + }; + }; +} ``` ::: diff --git a/docs/guide/libraries/apps.md b/docs/guide/libraries/apps.md index 1871d18..f1748db 100644 --- a/docs/guide/libraries/apps.md +++ b/docs/guide/libraries/apps.md @@ -3,40 +3,6 @@ Library and CLI tool for querying and launching applications that have a corresponding `.desktop` file. -## Installation - -1. install dependencies - -:::code-group - -```sh [<i class="devicon-archlinux-plain"></i> Arch] -sudo pacman -Syu meson vala json-glib gobject-introspection -``` - -```sh [<i class="devicon-fedora-plain"></i> Fedora] -sudo dnf install meson vala valadoc json-glib-devel gobject-introspection-devel -``` - -```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] -sudo apt install meson valac libjson-glib-dev gobject-introspection -``` - -::: - -2. clone repo - -```sh -git clone https://github.com/aylur/astal.git -cd astal/lib/apps -``` - -3. install - -```sh -meson setup --prefix /usr build -meson install -C build -``` - ## Usage You can browse the [Apps reference](https://aylur.github.io/libastal/apps). @@ -106,3 +72,37 @@ foreach (var app in apps.fuzzy_query("firefox")) { ``` ::: + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala json-glib gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson vala valadoc json-glib-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac libjson-glib-dev gobject-introspection +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/apps +``` + +3. install + +```sh +meson setup --prefix /usr build +meson install -C build +``` diff --git a/docs/guide/libraries/auth.md b/docs/guide/libraries/auth.md index d5f0a49..b52e38a 100644 --- a/docs/guide/libraries/auth.md +++ b/docs/guide/libraries/auth.md @@ -2,51 +2,6 @@ Library and CLI tool for authentication using [pam](https://github.com/linux-pam/linux-pam). -## Installation - -1. install dependencies - -:::code-group - -```sh [<i class="devicon-archlinux-plain"></i> Arch] -sudo pacman -Syu meson pam gobject-introspection -``` - -```sh [<i class="devicon-fedora-plain"></i> Fedora] -sudo dnf install meson pam-devel gobject-introspection-devel -``` - -```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] -# Not yet documented -``` - -::: - -::: warning On NixOS you have to add `astal-auth` to `security.pam`. -::: code-group - -```nix [configuration.nix] -{ - security.pam.services.astal-auth = {} -} -``` - -::: - -2. clone repo - -```sh -git clone https://github.com/aylur/astal.git -cd astal/lib/auth -``` - -3. install - -```sh -meson setup --prefix /usr build -meson install -C build -``` - ## Usage You can browse the [Auth reference](https://aylur.github.io/libastal/auth). @@ -105,3 +60,48 @@ end) ``` ::: + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson pam gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson pam-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +# Not yet documented +``` + +::: + +::: warning On NixOS you have to add `astal-auth` to `security.pam`. +::: code-group + +```nix [configuration.nix] +{ + security.pam.services.astal-auth = {} +} +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/auth +``` + +3. install + +```sh +meson setup --prefix /usr build +meson install -C build +``` diff --git a/docs/guide/libraries/battery.md b/docs/guide/libraries/battery.md index 56f955c..7e6fe24 100644 --- a/docs/guide/libraries/battery.md +++ b/docs/guide/libraries/battery.md @@ -2,45 +2,6 @@ Library and CLI tool for monitoring [upowerd](https://upower.freedesktop.org/) devices. -## Installation - -1. install dependencies - -:::code-group - -```sh [<i class="devicon-archlinux-plain"></i> Arch] -sudo pacman -Syu meson vala json-glib gobject-introspection -``` - -```sh [<i class="devicon-fedora-plain"></i> Fedora] -sudo dnf install meson vala valadoc json-glib-devel gobject-introspection-devel -``` - -```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] -sudo apt install meson valac libjson-glib-dev gobject-introspection -``` - -::: - -::: info -Although UPower is not a direct build dependency, -it should be self-explanatory that the daemon is required to be available at runtime. -::: - -2. clone repo - -```sh -git clone https://github.com/aylur/astal.git -cd astal/lib/battery -``` - -3. install - -```sh -meson setup --prefix /usr build -meson install -C build -``` - ## Usage You can browse the [Battery reference](https://aylur.github.io/libastal/battery). @@ -84,3 +45,42 @@ print(battery.percentage) ``` ::: + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala json-glib gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson vala valadoc json-glib-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac libjson-glib-dev gobject-introspection +``` + +::: + +::: info +Although UPower is not a direct build dependency, +it should be self-explanatory that the daemon is required to be available at runtime. +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/battery +``` + +3. install + +```sh +meson setup --prefix /usr build +meson install -C build +``` diff --git a/docs/guide/libraries/bluetooth.md b/docs/guide/libraries/bluetooth.md index 03ac9c9..9a3e5b8 100644 --- a/docs/guide/libraries/bluetooth.md +++ b/docs/guide/libraries/bluetooth.md @@ -2,45 +2,6 @@ Library for monitoring [bluez](https://www.bluez.org/) over dbus. -## Installation - -1. install dependencies - -:::code-group - -```sh [<i class="devicon-archlinux-plain"></i> Arch] -sudo pacman -Syu meson vala gobject-introspection -``` - -```sh [<i class="devicon-fedora-plain"></i> Fedora] -sudo dnf install meson vala valadoc gobject-introspection-devel -``` - -```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] -sudo apt install meson valac gobject-introspection -``` - -::: - -::: info -Although bluez is not a direct build dependency, -it should be self-explanatory that the daemon is required to be available at runtime. -::: - -2. clone repo - -```sh -git clone https://github.com/aylur/astal.git -cd astal/lib/bluetooth -``` - -3. install - -```sh -meson setup --prefix /usr build -meson install -C build -``` - ## Usage You can browse the [Bluetooth reference](https://aylur.github.io/libastal/bluetooth). @@ -91,3 +52,42 @@ end ``` ::: + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson vala valadoc gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac gobject-introspection +``` + +::: + +::: info +Although bluez is not a direct build dependency, +it should be self-explanatory that the daemon is required to be available at runtime. +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/bluetooth +``` + +3. install + +```sh +meson setup --prefix /usr build +meson install -C build +``` diff --git a/docs/guide/libraries/cava.md b/docs/guide/libraries/cava.md index e695e16..60b2824 100644 --- a/docs/guide/libraries/cava.md +++ b/docs/guide/libraries/cava.md @@ -2,6 +2,46 @@ Audio visualizer using [cava](https://github.com/karlstav/cava). +## Usage + +You can browse the [Cava reference](https://aylur.github.io/libastal/cava). + +### CLI + +There is no CLI for this library, use the one provided by cava. + +```sh +cava +``` + +### Library + +:::code-group + +```js [<i class="devicon-javascript-plain"></i> JavaScript] +import Cava from "gi://AstalCava" + +const cava = Cava.get_default() + +cava.connect("notify::values", () => { + print(cava.get_values()) +}) +``` + +```py [<i class="devicon-python-plain"></i> Python] +# Not yet documented +``` + +```lua [<i class="devicon-lua-plain"></i> Lua] +-- Not yet documented +``` + +```vala [<i class="devicon-vala-plain"></i> Vala] +// Not yet documented +``` + +::: + ## Installation 1. install dependencies @@ -49,43 +89,3 @@ meson setup --prefix /usr build ``` ::: - -## Usage - -You can browse the [Cava reference](https://aylur.github.io/libastal/cava). - -### CLI - -There is no CLI for this library, use the one provided by cava. - -```sh -cava -``` - -### Library - -:::code-group - -```js [<i class="devicon-javascript-plain"></i> JavaScript] -import Cava from "gi://AstalCava" - -const cava = Cava.get_default() - -cava.connect("notify::values", () => { - print(cava.get_values()) -}) -``` - -```py [<i class="devicon-python-plain"></i> Python] -# Not yet documented -``` - -```lua [<i class="devicon-lua-plain"></i> Lua] --- Not yet documented -``` - -```vala [<i class="devicon-vala-plain"></i> Vala] -// Not yet documented -``` - -::: diff --git a/docs/guide/libraries/greet.md b/docs/guide/libraries/greet.md index f0cd012..47f98b9 100644 --- a/docs/guide/libraries/greet.md +++ b/docs/guide/libraries/greet.md @@ -2,45 +2,6 @@ Library and CLI tool for sending requests to [greetd](https://sr.ht/~kennylevinsen/greetd/). -## Installation - -1. install dependencies - -:::code-group - -```sh [<i class="devicon-archlinux-plain"></i> Arch] -sudo pacman -Syu meson vala json-glib gobject-introspection -``` - -```sh [<i class="devicon-fedora-plain"></i> Fedora] -sudo dnf install meson vala valadoc json-glib-devel gobject-introspection-devel -``` - -```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] -sudo apt install meson valac libjson-glib-dev gobject-introspection -``` - -::: - -::: info -Although `greetd` is not a direct build dependency, -it should be self-explanatory that the daemon is required to be available at runtime. -::: - -2. clone repo - -```sh -git clone https://github.com/aylur/astal.git -cd astal/lib/greet -``` - -3. install - -```sh -meson setup --prefix /usr build -meson install -C build -``` - ## Usage You can browse the [Greet reference](https://aylur.github.io/libastal/greet). @@ -92,3 +53,42 @@ try { ``` ::: + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala json-glib gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson vala valadoc json-glib-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac libjson-glib-dev gobject-introspection +``` + +::: + +::: info +Although `greetd` is not a direct build dependency, +it should be self-explanatory that the daemon is required to be available at runtime. +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/greet +``` + +3. install + +```sh +meson setup --prefix /usr build +meson install -C build +``` diff --git a/docs/guide/libraries/hyprland.md b/docs/guide/libraries/hyprland.md index 94a398f..82d9e9d 100644 --- a/docs/guide/libraries/hyprland.md +++ b/docs/guide/libraries/hyprland.md @@ -2,40 +2,6 @@ Library and CLI tool for monitoring the [Hyprland socket](https://wiki.hyprland.org/IPC/). -## Installation - -1. install dependencies - -:::code-group - -```sh [<i class="devicon-archlinux-plain"></i> Arch] -sudo pacman -Syu meson vala json-glib gobject-introspection -``` - -```sh [<i class="devicon-fedora-plain"></i> Fedora] -sudo dnf install meson vala valadoc json-glib-devel gobject-introspection-devel -``` - -```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] -sudo apt install meson valac libjson-glib-dev gobject-introspection -``` - -::: - -2. clone repo - -```sh -git clone https://github.com/aylur/astal.git -cd astal/lib/hyprland -``` - -3. install - -```sh -meson setup --prefix /usr build -meson install -C build -``` - ## Usage You can browse the [Hyprland reference](https://aylur.github.io/libastal/hyprland). @@ -84,3 +50,37 @@ end ``` ::: + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala json-glib gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson vala valadoc json-glib-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac libjson-glib-dev gobject-introspection +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/hyprland +``` + +3. install + +```sh +meson setup --prefix /usr build +meson install -C build +``` diff --git a/docs/guide/libraries/mpris.md b/docs/guide/libraries/mpris.md index 30f3d13..c2283cc 100644 --- a/docs/guide/libraries/mpris.md +++ b/docs/guide/libraries/mpris.md @@ -6,52 +6,6 @@ exposing an mpris interface through dbus. An alternative for [playerctl](https://github.com/altdesktop/playerctl) that better integrates with astal. -:::warning -In order for network cover art urls to be cached (spotify for example) -make sure `gvfs` is enabled. - -:::code-group - -```nix [<i class="devicon-nixos-plain"></i> configuration.nix] -services.gvfs.enable = true; -``` - -::: - -## Installation - -1. install dependencies - -:::code-group - -```sh [<i class="devicon-archlinux-plain"></i> Arch] -sudo pacman -Syu meson vala gvfs json-glib gobject-introspection -``` - -```sh [<i class="devicon-fedora-plain"></i> Fedora] -sudo dnf install meson vala valadoc gvfs json-glib-devel gobject-introspection-devel -``` - -```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] -sudo apt install meson valac gvfs libjson-glib-dev gobject-introspection -``` - -::: - -2. clone repo - -```sh -git clone https://github.com/aylur/astal.git -cd astal/lib/mpris -``` - -3. install - -```sh -meson setup --prefix /usr build -meson install -C build -``` - ## Usage You can browse the [Mpris reference](https://aylur.github.io/libastal/mpris). @@ -99,3 +53,49 @@ end ``` ::: + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala gvfs json-glib gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson vala valadoc gvfs json-glib-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac gvfs libjson-glib-dev gobject-introspection +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/mpris +``` + +3. install + +```sh +meson setup --prefix /usr build +meson install -C build +``` + +:::warning +In order for network cover art urls to be cached (spotify for example) +make sure `gvfs` is enabled. + +:::code-group + +```nix [<i class="devicon-nixos-plain"></i> configuration.nix] +services.gvfs.enable = true; +``` + +::: diff --git a/docs/guide/libraries/network.md b/docs/guide/libraries/network.md index 21c7b10..79a217c 100644 --- a/docs/guide/libraries/network.md +++ b/docs/guide/libraries/network.md @@ -2,40 +2,6 @@ Wrapper library over [networkmanager](https://networkmanager.dev/) to better integrate with Astal. -## Installation - -1. install dependencies - -:::code-group - -```sh [<i class="devicon-archlinux-plain"></i> Arch] -sudo pacman -Syu meson vala libnm gobject-introspection -``` - -```sh [<i class="devicon-fedora-plain"></i> Fedora] -sudo dnf install meson vala valadoc NetworkManager-libnm-devel gobject-introspection-devel -``` - -```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] -sudo apt install meson valac libnm-dev gobject-introspection -``` - -::: - -2. clone repo - -```sh -git clone https://github.com/aylur/astal.git -cd astal/lib/network -``` - -3. install - -```sh -meson setup --prefix /usr build -meson install -C build -``` - ## Usage You can browse the [Network reference](https://aylur.github.io/libastal/network). @@ -81,3 +47,37 @@ print(network.wifi.ssid) ``` ::: + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala libnm gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson vala valadoc NetworkManager-libnm-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac libnm-dev gobject-introspection +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/network +``` + +3. install + +```sh +meson setup --prefix /usr build +meson install -C build +``` diff --git a/docs/guide/libraries/notifd.md b/docs/guide/libraries/notifd.md index 4208700..1d61099 100644 --- a/docs/guide/libraries/notifd.md +++ b/docs/guide/libraries/notifd.md @@ -6,40 +6,6 @@ A [notification daemon](https://specifications.freedesktop.org/notification-spec The first instantiation of the [Notifd](https://aylur.github.io/libastal/notifd/class.Notifd.html) class will become the daemon and every subsequent instantiation will queue up to act as the daemon and will act as a client in the meantime. This means this library can be used throughout multiple processes. -## Installation - -1. install dependencies - -:::code-group - -```sh [<i class="devicon-archlinux-plain"></i> Arch] -sudo pacman -Syu meson vala gdk-pixbuf2 json-glib gobject-introspection -``` - -```sh [<i class="devicon-fedora-plain"></i> Fedora] -sudo dnf install meson vala valadoc gdk-pixbuf2-devel json-glib-devel gobject-introspection-devel -``` - -```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] -sudo apt install meson valac libgdk-pixbuf-2.0-dev libjson-glib-dev gobject-introspection -``` - -::: - -2. clone repo - -```sh -git clone https://github.com/aylur/astal.git -cd astal/lib/notifd -``` - -3. install - -```sh -meson setup --prefix /usr build -meson install -C build -``` - ## Usage You can browse the [Notifd reference](https://aylur.github.io/libastal/notifd). @@ -93,3 +59,37 @@ end ``` ::: + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala gdk-pixbuf2 json-glib gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson vala valadoc gdk-pixbuf2-devel json-glib-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac libgdk-pixbuf-2.0-dev libjson-glib-dev gobject-introspection +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/notifd +``` + +3. install + +```sh +meson setup --prefix /usr build +meson install -C build +``` diff --git a/docs/guide/libraries/powerprofiles.md b/docs/guide/libraries/powerprofiles.md index bdafcde..b42d7c6 100644 --- a/docs/guide/libraries/powerprofiles.md +++ b/docs/guide/libraries/powerprofiles.md @@ -2,45 +2,6 @@ Library and CLI tool for monitoring [upowerd](https://upower.freedesktop.org/) powerprofiles. -## Installation - -1. install dependencies - -:::code-group - -```sh [<i class="devicon-archlinux-plain"></i> Arch] -sudo pacman -Syu meson vala json-glib gobject-introspection -``` - -```sh [<i class="devicon-fedora-plain"></i> Fedora] -sudo dnf install meson vala valadoc json-glib-devel gobject-introspection-devel -``` - -```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] -sudo apt install meson valac libjson-glib-dev gobject-introspection -``` - -::: - -::: info -Although UPower is not a direct build dependency, -it should be self-explanatory that the daemon is required to be available at runtime. -::: - -2. clone repo - -```sh -git clone https://github.com/aylur/astal.git -cd astal/lib/powerprofiles -``` - -3. install - -```sh -meson setup --prefix /usr build -meson install -C build -``` - ## Usage You can browse the [PowerProfiles reference](https://aylur.github.io/libastal/powerprofiles). @@ -84,3 +45,42 @@ print(powerprofiles.active_profile) ``` ::: + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala json-glib gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson vala valadoc json-glib-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson valac libjson-glib-dev gobject-introspection +``` + +::: + +::: info +Although UPower is not a direct build dependency, +it should be self-explanatory that the daemon is required to be available at runtime. +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/powerprofiles +``` + +3. install + +```sh +meson setup --prefix /usr build +meson install -C build +``` diff --git a/docs/guide/libraries/references.md b/docs/guide/libraries/references.md index 3a85d73..f8ab4d8 100644 --- a/docs/guide/libraries/references.md +++ b/docs/guide/libraries/references.md @@ -33,6 +33,8 @@ Reading their documentation will vary depending on the language they are used in - [Auth](https://aylur.github.io/libastal/auth): Authentication library using PAM - [Battery](https://aylur.github.io/libastal/battery): DBus proxy library for upower daemon - [Bluetooth](https://aylur.github.io/libastal/bluetooth): Library to control bluez over dbus +- [Cava](https://aylur.github.io/libastal/cava): Audio visualizer library using cava +- [Greet](https://aylur.github.io/libastal/greet): Library and CLI tool for sending requests to greetd - [Hyprland](https://aylur.github.io/libastal/hyprland): Library and cli tool for Hyprland IPC socket - [Mpris](https://aylur.github.io/libastal/mpris): Library and cli tool for controlling media players - [Network](https://aylur.github.io/libastal/network): NetworkManager wrapper library diff --git a/docs/guide/libraries/river.md b/docs/guide/libraries/river.md index 299aa8c..dc1c71e 100644 --- a/docs/guide/libraries/river.md +++ b/docs/guide/libraries/river.md @@ -2,40 +2,6 @@ Library and CLI tool for monitoring the [River Wayland Compositor](https://isaacfreund.com/software/river/). -## Installation - -1. install dependencies - -:::code-group - -```sh [<i class="devicon-archlinux-plain"></i> Arch] -sudo pacman -Syu meson json-glib gobject-introspection -``` - -```sh [<i class="devicon-fedora-plain"></i> Fedora] -sudo dnf install meson gcc json-glib-devel gobject-introspection-devel -``` - -```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] -sudo apt install meson libjson-glib-dev gobject-introspection -``` - -::: - -2. clone repo - -```sh -git clone https://github.com/aylur/astal.git -cd astal/lib/river -``` - -3. install - -```sh -meson setup --prefix /usr build -meson install -C build -``` - ## Usage You can browse the [River reference](https://aylur.github.io/libastal/river). @@ -84,3 +50,37 @@ end ``` ::: + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson json-glib gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson gcc json-glib-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson libjson-glib-dev gobject-introspection +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/river +``` + +3. install + +```sh +meson setup --prefix /usr build +meson install -C build +``` diff --git a/docs/guide/libraries/tray.md b/docs/guide/libraries/tray.md index b5cccc7..43b3aa6 100644 --- a/docs/guide/libraries/tray.md +++ b/docs/guide/libraries/tray.md @@ -2,40 +2,6 @@ Library for managing the systemtray by implementing the [StatusNotifierItem](https://www.freedesktop.org/wiki/Specifications/StatusNotifierItem/) protocol. -## Installation - -1. install dependencies - -:::code-group - -```sh [<i class="devicon-archlinux-plain"></i> Arch] -sudo pacman -Syu meson gtk3 gobject-introspection libdbusmenu-gtk3 -``` - -```sh [<i class="devicon-fedora-plain"></i> Fedora] -sudo dnf install meson gcc gtk3-devel libdbusmenu-gtk3 gobject-introspection-devel -``` - -```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] -sudo apt install meson libgtk-3-dev libdbusmenu-gtk3-dev gobject-introspection -``` - -::: - -2. clone repo - -```sh -git clone https://github.com/aylur/astal.git -cd astal/lib/tray -``` - -3. install - -```sh -meson setup --prefix /usr build -meson install -C build -``` - ## Usage You can browse the [Tray reference](https://aylur.github.io/libastal/tray). @@ -84,3 +50,37 @@ end ``` ::: + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson gtk3 gobject-introspection libdbusmenu-gtk3 +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson gcc gtk3-devel libdbusmenu-gtk3-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +sudo apt install meson libgtk-3-dev libdbusmenu-gtk3-dev gobject-introspection +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/tray +``` + +3. install + +```sh +meson setup --prefix /usr build +meson install -C build +``` diff --git a/docs/guide/libraries/wireplumber.md b/docs/guide/libraries/wireplumber.md index c06161e..d6faea1 100644 --- a/docs/guide/libraries/wireplumber.md +++ b/docs/guide/libraries/wireplumber.md @@ -2,40 +2,6 @@ Wrapper library over [wireplumber](https://pipewire.pages.freedesktop.org/wireplumber/) to better integrate with Astal. -## Installation - -1. install dependencies - -:::code-group - -```sh [<i class="devicon-archlinux-plain"></i> Arch] -sudo pacman -Syu meson vala wireplumber gobject-introspection -``` - -```sh [<i class="devicon-fedora-plain"></i> Fedora] -sudo dnf install meson vala valadoc wireplumber-devel gobject-introspection-devel -``` - -```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] -# Not yet documented -``` - -::: - -2. clone repo - -```sh -git clone https://github.com/aylur/astal.git -cd astal/lib/wireplumber -``` - -3. install - -```sh -meson setup --prefix /usr build -meson install -C build -``` - ## Usage You can browse the [Wireplumber reference](https://aylur.github.io/libastal/wireplumber). @@ -81,3 +47,37 @@ print(audio.default_speaker.volume) ``` ::: + +## Installation + +1. install dependencies + +:::code-group + +```sh [<i class="devicon-archlinux-plain"></i> Arch] +sudo pacman -Syu meson vala wireplumber gobject-introspection +``` + +```sh [<i class="devicon-fedora-plain"></i> Fedora] +sudo dnf install meson vala valadoc wireplumber-devel gobject-introspection-devel +``` + +```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] +# Not yet documented +``` + +::: + +2. clone repo + +```sh +git clone https://github.com/aylur/astal.git +cd astal/lib/wireplumber +``` + +3. install + +```sh +meson setup --prefix /usr build +meson install -C build +``` diff --git a/docs/guide/lua/first-widgets.md b/docs/guide/lua/first-widgets.md index efc1c4f..70cfe0c 100644 --- a/docs/guide/lua/first-widgets.md +++ b/docs/guide/lua/first-widgets.md @@ -13,8 +13,7 @@ local App = require("astal.gtk3.app") App:start({ main = function() -- you will instantiate Widgets here - -- or setup anything else if you need - print("hi") + -- and setup anything else if you need end }) ``` @@ -22,7 +21,7 @@ App:start({ ::: Then run `lua init.lua` in the terminal, and that's it! -Now you have an instance running with Lua. +Now you have an Astal instance running written in Lua. ## Root of every shell component: Window diff --git a/docs/guide/lua/theming.md b/docs/guide/lua/theming.md index 502e8e9..4f556fc 100644 --- a/docs/guide/lua/theming.md +++ b/docs/guide/lua/theming.md @@ -39,7 +39,7 @@ App:start({ ::: :::warning -When using relative paths, so for example `./style.css` keep in mind that they +When using relative paths, for example `./style.css` keep in mind that they will be relative to the current working directory. ::: diff --git a/docs/guide/typescript/cli-app.md b/docs/guide/typescript/cli-app.md index 85b117c..9b299aa 100644 --- a/docs/guide/typescript/cli-app.md +++ b/docs/guide/typescript/cli-app.md @@ -6,7 +6,6 @@ Depending on gtk version import paths will differ ```ts import { App } from "astal/gtk3" - import { App } from "astal/gtk4" ``` @@ -53,20 +52,11 @@ App.start({ }) ``` -:::code-group - -```sh [astal] +```sh astal say hi # hi cli ``` -```sh [ags] -ags request "say hi" -# hi cli -``` - -::: - If you want to run arbitrary JavaScript from CLI, you can use `App.eval` which will evaluate the passed string as the body of an `async` function. @@ -102,7 +92,7 @@ In order for Astal to know about your windows, you have to register them. You can do this by specifying a **unique** `name` and calling `App.add_window` ```tsx {4} -import { App } from "astal" +import { App } from "astal/gtk3" function Bar() { return <window name="Bar" setup={self => App.add_window(self)}> @@ -114,7 +104,7 @@ function Bar() { You can also invoke `App.add_window` by simply passing the `App` to the `application` prop. ```tsx {4} -import { App } from "astal" +import { App } from "astal/gtk3" function Bar() { return <window name="Bar" application={App}> @@ -128,24 +118,13 @@ When assigning the `application` prop make sure `name` comes before. Props are set sequentially and if name is applied after application it won't work. ::: -:::code-group - ```sh [astal] astal -t Bar ``` -```sh [ags] -ags toggle Bar -``` - -::: - -## Bundled scripts - -The produced scripts when bundling can run as the main instance -and a "client" instance. +## Client -The first time you execute your bundled script the `main` function gets called. +The first time you execute your script the `main` function gets called. While that instance is running any subsequent execution of the script will call the `client` function. diff --git a/docs/guide/typescript/faq.md b/docs/guide/typescript/faq.md index 48c802c..a151099 100644 --- a/docs/guide/typescript/faq.md +++ b/docs/guide/typescript/faq.md @@ -7,7 +7,7 @@ the same as the compositor. Instead use the `gdkmonitor` property which expects a `Gdk.Monitor` object. ```tsx -import { App } from "astal" +import { App } from "astal/gtk3" function Bar(gdkmonitor) { return <window gdkmonitor={gdkmonitor} /> @@ -162,7 +162,7 @@ export default function Bar(gdkmonitor: Gdk.Monitor) { :::code-group ```ts [app.ts] -import { Gdk, Gtk } from "astal" +import { Gdk, Gtk } from "astal/gtk3" import Bar from "./Bar" function main() { diff --git a/docs/guide/typescript/first-widgets.md b/docs/guide/typescript/first-widgets.md index 96a1275..a467382 100644 --- a/docs/guide/typescript/first-widgets.md +++ b/docs/guide/typescript/first-widgets.md @@ -2,41 +2,26 @@ ## Getting Started -Start by initializing a project +Start by importing the singleton +[Astal.Application](https://aylur.github.io/libastal/astal3/class.Application.html) instance. -```sh -ags init -``` +:::code-group -then run `ags run` in the terminal +```ts [app.ts] +import { App } from "astal/gtk3" -```sh -ags run +App.start({ + main() { + // you will instantiate Widgets here + // and setup anything else if you need + } +}) ``` -:::details Usage without AGS -🚧 Not yet documented. 🚧 -::: - -That's it! You have now a custom written bar using Gtk. - -:::tip -AGS will transpile every `.ts`, `.jsx` and `.tsx` files into regular JavaScript, then -it will bundle everything into a single JavaScript file which then GJS can execute. ::: -The AGS init command will generate the following files - -```txt -. -├── @girs/ # generated types -├── widget/ -│ └── Bar.tsx -├── app.ts # entry proint -├── env.d.ts # additional types -├── style.css -└── tsconfig.json # needed by LSPs -``` +After your [bundle step](./installation.md) run `gjs -m app.js`, and that's it! +Now you have an Astal instance running written in TypeScript. ## Root of every shell component: Window diff --git a/docs/guide/typescript/installation.md b/docs/guide/typescript/installation.md index e0f1bd5..0c19325 100644 --- a/docs/guide/typescript/installation.md +++ b/docs/guide/typescript/installation.md @@ -1,89 +1,19 @@ # Installation -It is recommended to use [AGS](https://github.com/aylur/ags) +It is recommended to use [AGS](https://aylur.github.io/ags/) to scaffold and run projects in TypeScript. It lets you - generate TypeScript types using [ts-for-gir](https://github.com/gjsify/ts-for-gir) -- generate a tsconfig which is used by LSPs -- bundle your TypeScript and JavaScript code using [esbuild](https://esbuild.github.io/). +- generate a tsconfig which is used by LSPs to provide intellisense +- bundle your TypeScript and JavaScript code using [esbuild](https://esbuild.github.io/) :::details Trivia AGS is the predecessor of Astal, which was written purely in TypeScript and so only supported -JavaScript/TypeScript. Now it serves as a scaffolding tool for Astal+TypeScript+JSX projects. +JavaScript/TypeScript. Now it serves as a scaffolding tool for Astal+TypeScript projects. ::: -## Nix - -maintainer: [@Aylur](https://github.com/Aylur) - -Read more about it on the [nix page](../getting-started/nix#ags) - -You can try without installing. - -<!--TODO: remove v2 after merge--> -```sh -nix run github:aylur/ags/v2#agsFull -- --help -``` - -## From source - -1. [Install Astal](../getting-started/installation.md) if you have not already - -2. Install the Astal GJS package - -```sh -git clone https://github.com/aylur/astal /tmp/astal -cd /tmp/astal/lang/gjs -meson setup --prefix /usr build -meson install -C build -``` - -:::tip -You might be wondering why it is recommended to install a JavaScript -package on the system instead of installing it as a node module. -It is solely to keep it in **sync** with the core `astal-io` and `astal3`/`astal4` package. -::: - -3. Install the following dependencies - -:::code-group - -```sh [<i class="devicon-archlinux-plain"></i> Arch] -sudo pacman -Syu go npm gjs -``` - -```sh [<i class="devicon-fedora-plain"></i> Fedora] -sudo dnf install golang npm gjs -``` - -```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu] -sudo apt install golang-go npm gjs -``` - -::: - -3. Clone the repo and Install - -<!--TODO: remove v2 after merge--> -```sh -git clone https://github.com/aylur/ags.git /tmp/ags -cd /tmp/ags -git checkout v2 # https://github.com/Aylur/ags/pull/504 -go install -``` - -:::tip -`go install` installs the `ags` binary to `$GOPATH/bin` so make sure its in your `$PATH`. -You can move it to another directory if you like. For example - -```sh -sudo mv $GOPATH/bin/ags /usr/bin/ags -``` - -::: - -## Without AGS +## Setting up a project 🚧 Setting up a dev environment without AGS is not yet documented. 🚧 diff --git a/docs/guide/typescript/theming.md b/docs/guide/typescript/theming.md index 10a3981..5944c4e 100644 --- a/docs/guide/typescript/theming.md +++ b/docs/guide/typescript/theming.md @@ -23,28 +23,24 @@ You can pass a path to a file or css as a string in `App.start` :::code-group ```ts [app.ts] -import style from "inline:./style.css" - -const inlineCssInCode = ` -window { - background-color: transparent; -} +const inlineCss = ` + window { + background-color: transparent; + } ` App.start({ - css: "./style.css", - css: style, - css: `${SRC}/style.css'`, css: inlineCss, + css: "./style.css", + css: "/path/to/style.css", }) ``` ::: -:::info -When using AGS the global `SRC` will point to the directory `app.ts` is in. -AGS will set the current working directory to `--config`, so `./style.css` also works. -If you are not using AGS you should inline import CSS instead. +:::warning +When using relative paths, for example `./style.css` keep in mind that they +will be relative to the current working directory. ::: ## Css Property on Widgets @@ -90,20 +86,11 @@ You can reset stylesheets with `App.resetCss` If you are not sure about the widget hierarchy or any CSS selector, you can use the [GTK inspector](https://wiki.gnome.org/Projects/GTK/Inspector) -::: code-group - -```sh [astal] +```sh # to bring up the inspector run astal --inspector ``` -```sh [ags] -# to bring up the inspector run -ags --inspector -``` - -::: - ## Using SCSS Gtk's CSS only supports a subset of what the web offers. @@ -126,54 +113,22 @@ npm install -g sass # not packaged on Ubuntu ::: -Importing `scss` files will simply return transpiled css. - :::code-group ```ts [app.ts] -import style from "./style.scss" +import { exec } from "astal/process" + +exec("sass", "./style.scss", "/tmp/style.css") App.start({ - css: style, + css: "/tmp/style.css", main() {}, }) ``` ::: -:::details Without AGS -AGS uses a plugin to transpile scss files before importing them. -If you are not using AGS, you can use a plugin for your chosen bundler. -::: - :::tip -If you for example want to set scss varibles from JS, -You can inline import, compose, and transpile yourself. - -```ts [app.ts] -import style1 from "inline:./style1.scss" -import style2 from "inline:./style2.scss" - -const tmpscss = "/tmp/style.scss" -const target = "/tmp/style.css" - -writeFile(tmpscss, ` - $var1: red; - $var1: blue; - ${style1} - ${style1} -`) - -exec(`sass ${tmpscss} ${target}`) - -App.start({ - css: target, -}) - -``` - -::: - -:::info -If you want other preprocessors support builtin open an Issue. +You could also transpile scss into css using a bundler +and simply passing the path of the resulting css file to `css`. ::: |