Skip to content
This repository has been archived by the owner on Jun 2, 2024. It is now read-only.

Commit

Permalink
docs: update readme to support new build system (#183) (#185)
Browse files Browse the repository at this point in the history 
* improve readme

* update readme

* fix some stuff

* fix alot of stuff

* fix alot of stuff (again)

* fixes by duk

* fix: apply suggestions from code review

* fix: apply suggestions from code review



* fixing some stuff

---------

Co-authored-by: Omar <[email protected]>
  • Loading branch information
@nullishamy
nullishamy and Omar authored May 19, 2024
1 parent 4050bab commit d8a7720
Showing 1 changed file with 55 additions and 153 deletions.
208 changes: 55 additions & 153 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,39 +15,72 @@
<img src="assets/res.webp"/>
</p>

# About

This GTK theme is based on the [Colloid](https://github.com/vinceliuice/Colloid-gtk-theme) theme made by [Vinceliuice](https://github.com/vinceliuice)
This GTK theme is based on the [Colloid](https://github.com/vinceliuice/Colloid-gtk-theme) theme made by [vinceliuice](https://github.com/vinceliuice)

## Usage

### Requirements

- GTK `>=3.20`
- GTK >=3.20
- `python3`
- `gnome-themes-extra` (or `gnome-themes-standard`)

### Installation
To build the theme, make sure the following packages are installed:
- `sassc`
- `inkscape`
- `optipng`

### Manually

1. Download and extract the theme zip from the [latest release](https://github.com/catppuccin/gtk/releases/latest/).
2. Move the theme folder to the `~/.local/share/themes` directory.
3. Select the downloaded theme via your desktop specific tweaks application (GNOME Tweaks on GNOME 3+).
4. To theme other apps that are using GTK, make sure to run the following command:
```bash
export THEME_DIR="~/.local/share/themes/catppuccin-<flavor>-<accent>-standard+default"
mkdir -p "${HOME}/.config/gtk-4.0" &&
ln -sf "${THEME_DIR}/gtk-4.0/assets" "${HOME}/.config/gtk-4.0/assets" &&
ln -sf "${THEME_DIR}/gtk-4.0/gtk.css" "${HOME}/.config/gtk-4.0/gtk.css" &&
ln -sf "${THEME_DIR}/gtk-4.0/gtk-dark.css" "${HOME}/.config/gtk-4.0/gtk-dark.css"
```

### Flatpak

1. Download and extract the theme zip from [releases](https://github.com/catppuccin/gtk/releases/).
2. Move the theme folder to **".themes"** in your home directory. **(~/.themes)** (Skip this step if you are using the AUR package)
3. Select the downloaded theme via your desktop specific tweaks application (**gnome-tweaks** on Gnome 3+).
In order for Flatpak to access the theme, make sure to run the following command:
```bash
sudo flatpak override --filesystem=$HOME/.local/share/themes
```

Then, run the following command to apply the theme.
```bash
export THEME_DIR="~/.local/share/themes/catppuccin-<flavor>-<accent>-standard+default"
sudo flatpak override --env=GTK_THEME=$THEME_DIR
```

### Using the install script to install the theme

To install the theme using the install script, run `install.py`:
```
python3 install.py <flavor> <accent>
```

### For Arch Linux users
If you have adwaita installed, make sure to include `--link` in order to add symlinks for it:
```
python3 install.py <flavor> <accent> --link
```
Run the command and the gtk theme should be installed!

We have 4 AUR packages for all the 4 flavours of the theme:
### AUR

- [Latte](https://aur.archlinux.org/packages/catppuccin-gtk-theme-latte)
- [Frappe](https://aur.archlinux.org/packages/catppuccin-gtk-theme-frappe)
- [Macchiato](https://aur.archlinux.org/packages/catppuccin-gtk-theme-macchiato)
- [Mocha](https://aur.archlinux.org/packages/catppuccin-gtk-theme-mocha)
We have 4 AUR packages for all the 4 flavours (Latte, Frappe, Macchiato, Mocha)

With your favourite AUR helper, install them:
With your favourite AUR helper, you can install one of these flavors:

```bash
yay -S catppuccin-gtk-theme-mocha catppuccin-gtk-theme-macchiato catppuccin-gtk-theme-frappe catppuccin-gtk-theme-latte
yay -S catppuccin-gtk-theme-<flavor>
```

### For Nix users
### Nix

We suggest you use [catppuccin/nix](https://github.com/catppuccin/nix).
Alternatively, you can use [catppuccin-gtk](https://github.com/NixOS/nixpkgs/blob/master/pkgs/data/themes/catppuccin-gtk/default.nix) from nixpkgs.
Expand All @@ -72,143 +105,12 @@ Alternatively, you can use [catppuccin-gtk](https://github.com/NixOS/nixpkgs/blo
> [!TIP]
> For further information on the options available, see the [full documentation](https://github.com/catppuccin/nix/blob/main/docs/home-manager-options.md#gtkcatppuccinenable).
### For GTK 4 users

To theme GTK 4 applications you have to manually symlink the `~/.config/gtk-4.0/` to the themes folder. Use the following commands

```bash
mkdir -p "${HOME}/.config/gtk-4.0"
ln -sf "${THEME_DIR}/gtk-4.0/assets" "${HOME}/.config/gtk-4.0/assets"
ln -sf "${THEME_DIR}/gtk-4.0/gtk.css" "${HOME}/.config/gtk-4.0/gtk.css"
ln -sf "${THEME_DIR}/gtk-4.0/gtk-dark.css" "${HOME}/.config/gtk-4.0/gtk-dark.css"
```

### For Flatpak users

1. To give your Flatpaks access to your themes folder run:

```bash
sudo flatpak override --filesystem=$HOME/.themes
```

2. To set the theme for all Flatpaks, replace `##theme##` with the name of the theme you want to use and run this command:

```bash
sudo flatpak override --env=GTK_THEME=##theme##
```

3. For a more in depth tutorial see Hamza Algohary's tutorial on [It's FOSS](https://itsfoss.com/flatpak-app-apply-theme/)

### Handling GTK theme installation from window manager

1. Install unzip and curl.
2. Go to your window manager config file.
3. Add an entrance to the config file to be executed when your window manager is loaded.
- i3/sway example:
```
# catppuccin
set $ctp-version v0.6.1
exec_always if [ ! -e ~/.themes/Catppuccin-Frappe-Standard-Lavender-dark ]; then \
mkdir -p ~/.themes \
&& curl -L https://github.com/catppuccin/gtk/releases/download/$ctp-version/Catppuccin-Frappe-Standard-Lavender-dark.zip -o ~/.themes/catppuccin.zip \
&& unzip ~/.themes/catppuccin.zip -d ~/.themes/ \
&& rm -rf ~/.themes/catppuccin.zip; fi
```
> Note: The previous example execute that script every time i3/sway is reloaded.
4. Set the GTK_THEME environment variable:

```sh
export GTK_THEME='Catppuccin-Frappe-Standard-Lavender-dark:dark'
```

> [!NOTE]
> in order to update the theme's version, just change the variable `$ctp-version`.
### GDM Theme

> [!WARNING]
> Applying a custom theme to GDM is not recommended as it is not themeable, however you can do it through certain *hacks*.
To apply the theme to GDM, A new `gnome-shell-theme.gresource.xml` needs to be complied.
To achieve this, you can run the following:

```bash
# Backup the current gresource file.
sudo cp -av /usr/share/gnome-shell/gnome-shell-theme.gresource{,~}
sudo glib-compile-resources --target="/usr/share/gnome-shell/gnome-shell-theme.gresource" --sourcedir="$THEME_DIR" "$THEME_DIR/gnome-shell-theme.gresource.xml"
```

Make sure to replace `$THEME_DIR` to where the theme was extracted accordingly.

- For nix users, it'll be the nix store path of the package.
- For AUR users, it'll be in `~/.themes`
- Otherwise, it'll be wherever you extracted the theme.

### Using the script

**Note**: Ensure that you have at least Python version 3.10 installed

Set up the installer using

```bash
git clone --recurse-submodules [email protected]:catppuccin/gtk.git
cd gtk
virtualenv -p python3 venv # to be created only once and only if you need a virtual env
source venv/bin/activate
pip install -r requirements.txt
```

To check out the install script, run

```bash
python install.py --help
```

> Tip: `python install.py --help` allows the following options:
```
Compulsory field Specify color variant(s) [mocha|frappe|macchiato|latte|all]
-d, --dest DIR Specify destination directory (Default: ~/.themes)
-n, --name NAME Specify theme name (Default: Colloid)
-a, --accent VARIANT... Specify theme color variant(s) [rosewater|flamingo|pink|mauve|red|maroon|peach|yellow|green|teal|sky|
sapphire|blue|lavender|all] (Default: blue)
-s, --size VARIANT... Specify size variant [standard|compact] (Default: standard variant)
-l, --link Link installed gtk-4.0 theme to config folder for all libadwaita app use this theme
--zip Zips up the finally produced themes.
--tweaks Specify versions for tweaks [black|rimless|normal|float]
1. black: Blackness color version
2. rimless: Remove the 1px border about windows and menus
3. normal: Normal windows button style (titlebuttons: max/min/close)
4. float: Floating gnome-shell panel style
-h, --help Show help
```

You can install any theme like the following example

```bash
python install.py mocha -a sky --tweaks rimless -d ~/.themes

```

You can build all possible variations of the theme possible using the following command and it will install it to releases folder

```bash
python install.py all -a all
```

## Development

You need to install the following packages to build the theme. Check with your distribution for the package names in the repository

- `sassc`
- `inkscape`
- `optipng`
### For Other Distros

A few important notes to keep in mind
Refer to [Using the install script to install the theme](https://github.com/catppuccin/gtk/edit/refactor/build-system/README.md#installing-the-theme-manually) or [Installing the theme manually](https://github.com/catppuccin/gtk/edit/refactor/build-system/README.md#installing-the-theme-manually).

- `recolor.py` handles all changes that needs to be done to colloid to ensure it generated catppuccin colors. If vinceliuice changes anything in his theme in future, that is where you must change
- `var.py` includes all different variables that you can tinker around as per your personal requirements.
- `create_theme.py` consists of a wrapper that will recolor the colloid theme, install it as per the args provided and rename it accordingly.
### Theming the GDM Theme
In order to theme the GDM theme, install the `gdm-settings` app, select the Catppuccin theme, and click *Save*.

## 💝 Thanks to

Expand All @@ -221,7 +123,7 @@ A few important notes to keep in mind
**Contributions**

- [rubyowo](https://github.com/rubyowo) - CI and docs
- [braheezy](https://github.com/braheezy) - Instructions for the GDM theme.
- [braheezy](https://github.com/braheezy) - Instructions for the GDM theme

**Previous maintainer(s)**

Expand Down

0 comments on commit d8a7720

Please sign in to comment.