From 89102aeda39bddbed8475902841a06e4e2978915 Mon Sep 17 00:00:00 2001 From: Mihai Fufezan Date: Tue, 30 Jul 2024 17:37:26 +0300 Subject: [PATCH] Getting Started: reword/revamp --- pages/Getting Started/Installation.md | 127 +++++++++++++---------- pages/Getting Started/Master-Tutorial.md | 64 ++++++------ pages/Getting Started/_index.md | 5 + 3 files changed, 110 insertions(+), 86 deletions(-) diff --git a/pages/Getting Started/Installation.md b/pages/Getting Started/Installation.md index 05211ba..5ea9210 100644 --- a/pages/Getting Started/Installation.md +++ b/pages/Getting Started/Installation.md @@ -1,15 +1,17 @@ --- -weight: 2 +weight: 1 title: Installation --- -# Foreword +{{< callout type=warning >}} Due to their proprietary nature, Nvidia GPUs have limited compatibility with Hyprland. If you want to try Hyprland on Nvidia regardless (many people have reported successes), follow the [Nvidia page](../../Nvidia) after installing Hyprland. +{{< /callout >}} + ## Distros Arch, NixOS and openSUSE Tumbleweed are very supported. For any other distro @@ -210,9 +212,15 @@ Refer to the gist if anything fails. {{% details title="Void Linux*" closed="true" %}} -Hyprland is not available from Void Linux's official repositories [due to a conflict of packaging philosophy](https://github.com/void-linux/void-packages/issues/37544). However, a [third party repository](https://github.com/Makrennel/hyprland-void) is available with [binary packages](https://github.com/Makrennel/hyprland-void/tree/repository-x86_64-glibc) built in CI by GitHub Actions. +Hyprland is not available from Void Linux's official repositories +[due to a conflict of packaging philosophy](https://github.com/void-linux/void-packages/issues/37544). +However, a [third party repository](https://github.com/Makrennel/hyprland-void) +is available with +[binary packages](https://github.com/Makrennel/hyprland-void/tree/repository-x86_64-glibc) +built in CI by GitHub Actions. -You can add this repository by creating a file such as `/etc/xbps.d/hyprland-void.conf` with the following contents: +You can add this repository by creating a file such as +`/etc/xbps.d/hyprland-void.conf` with the following contents: ```plain repository=https://raw.githubusercontent.com/Makrennel/hyprland-void/repository-x86_64-glibc @@ -228,7 +236,11 @@ sudo xbps-install -S xdg-desktop-portal-hyprland xbps-query -Rs hypr # This will require you to have already accepted the repository's fingerprint using xbps-install -S ``` -More information is available in the [hyprland-void README](https://github.com/Makrennel/hyprland-void/blob/master/README.md), including information about how you can [manually build](https://github.com/Makrennel/hyprland-void?tab=readme-ov-file#manually-building) Hyprland for Void Linux using the templates provided. +More information is available in the +[hyprland-void README](https://github.com/Makrennel/hyprland-void/blob/master/README.md), +including information about how you can +[manually build](https://github.com/Makrennel/hyprland-void?tab=readme-ov-file#manually-building) +Hyprland for Void Linux using the templates provided. {{% /details %}} @@ -268,20 +280,15 @@ community-driven, and no guarantee is provided for their validity.**_ ### Manual (Releases, Linux-only) -Download the most recent release. - -copy the binary (Hyprland) to `/usr/bin/`. - -copy hyprctl to `/usr/bin/`. - -copy hyprpm to `/usr/bin/`. - -copy the desktop entry (`example/hyprland.desktop`) to -`/usr/share/wayland-sessions/` +1. Download the most recent release. +2. copy the binaries (Hyprland, hyprctl, hyprpm) to `/usr/bin/`. +3. copy the desktop entry (`example/hyprland.desktop`) to + `/usr/share/wayland-sessions/` the example config is in `example/hyprland.conf`. -For updating later on, you can overwrite the binaries (hyprctl, hyprland, hyprpm ...). You don't need to update anything else. +For updating later on, you can overwrite the binaries (Hyprland, hyprctl, +hyprpm) . You don't need to update anything else. ### Manual (Manual Build) @@ -330,6 +337,11 @@ export CC=gcc CXX=g++ LDFLAGS="-static-libstdc++ -static-libgcc" refer to the Ubuntu tab above +Please note that Hyprland uses the C++23 standard, so both your compiler and +your C++ library has to support that (`gcc>=13.0.0` or `clang>=15`). On +Clang-based systems libc++ may be used by default, so until libc++ supports +C++23 you have to pass `-stdlib=libstdc++` or switch to GCC. + {{% /details %}} {{< callout type=warning >}} @@ -373,20 +385,25 @@ See [Crashes and Bugs](../../Crashes-and-Bugs). ## Custom installation (legacy renderer, etc) -cd into the hyprland repo. +1. cd into the hyprland repo. +2. for legacy renderer: -for legacy renderer: - -```plain -make legacyrenderer && sudo cp ./build/Hyprland /usr/bin && sudo cp ./example/hyprland.desktop /usr/share/wayland-sessions +```bash +make legacyrenderer +sudo make install ``` -_please note the legacy renderer may not support some graphical features._ -

Any other config: (replace \[PRESET\] with your preset, `release` -`debug` `legacyrenderer` `legacyrendererdebug`) +{{< callout type=info >}} -```plain -make [PRESET] && sudo cp ./build/Hyprland /usr/bin && sudo cp ./example/hyprland.desktop /usr/share/wayland-sessions +_please note the legacy renderer may not support some graphical features._ + +{{< /callout >}} + +3. Any other config: (replace `` with your preset: `release`, `debug`, + `legacyrenderer`, `legacyrendererdebug`) + +```bash +make && sudo cp ./build/Hyprland /usr/bin && sudo cp ./example/hyprland.desktop /usr/share/wayland-sessions ``` ## Custom Build flags @@ -395,51 +412,46 @@ To apply custom build flags, you'll have to ditch make. Supported custom build flags: -```plain +```bash +LEGACY_RENDERER - Compiles with the legacy renderer (see above) NO_XWAYLAND - Removes XWayland support NO_SYSTEMD - Removes systemd dependencies ``` -How to? +Flags can be passed to CMake like this: -Go to the root repo. - -Then, configure CMake: - -```plain -mkdir -p build && cmake --no-warn-unused-cli -DCMAKE_BUILD_TYPE:STRING=Release -D:STRING=true -H./ -B./build -G Ninja +```bash +cmake --no-warn-unused-cli -DCMAKE_BUILD_TYPE:STRING=Release -D:STRING=true -B build -G Ninja ``` -Change `` to one of the custom build flags. You **are allowed to** -use multiple at once, then add another `-D:STRING=true` +Change `` to one of the custom build flags. Multiple flags can be used at +once, by adding more `-D:STRING=true`. -You can of course also change the `BUILD_TYPE` to `Debug`. +The `BUILD_TYPE` can also be changed to `Debug`. -Now, build: +To build, run: -```plain -cmake --build ./build --config Release --target all -j $(nproc) +```bash +cmake --build ./build --config Release --target all ``` If you configured in `Debug`, change the `--config` to `Debug` as well. -Now, of course, install manually. +To install, run: -```plain -sudo cp ./build/Hyprland /usr/bin && sudo cp ./example/hyprland.desktop /usr/share/wayland-sessions +```bash +sudo cmake --install ./build ``` -Lastly, copy hyprctl, hyprpm, etc as mentioned -[here](#manual-releases-linux-only) - ## Running In a VM _YMMV, this is not officially supported._ -Read through the [libvirt Arch wiki page](https://wiki.archlinux.org/title/Libvirt) -and get `libvirt`, `virsh`, and `virt-viewer` setup and installed. +Read through the +[libvirt Arch wiki page](https://wiki.archlinux.org/title/Libvirt) and get +`libvirt`, `virsh`, and `virt-viewer` setup and installed. -```sh +```bash # Install libvirt and qemu things. sudo pacman -S libvirt virt-viewer qemu-common # Add yourself to the libvirt group. @@ -448,18 +460,19 @@ sudo usermod -a -G libvirt USER # Replace 'USER' with your username. systemctl enable --now libvirtd ``` -Go to the [arch-boxes gitlab](https://gitlab.archlinux.org/archlinux/arch-boxes/-/packages) +Go to the +[arch-boxes gitlab](https://gitlab.archlinux.org/archlinux/arch-boxes/-/packages) and download the latest arch qemu basic image. You can also download via any of arch's mirrors. -```sh +```bash curl https://geo.mirror.pkgbuild.com/images/latest/Arch-Linux-x86_64-basic.qcow2 \ -o ~/Downloads/arch-qemu.qcow2 # Or download wherever you want. ``` Create the VM with virsh. -```sh +```bash # Use virt-install (included with libvirt) to install the vm from the image. virt-install \ --graphics spice,listen=none,gl.enable=yes,rendernode=/dev/dri/renderD128 \ @@ -486,12 +499,12 @@ pre-connected socket to the display.\* virt-viewer --attach hypr-vm ``` -Finally on the guest follow the instructions above for either [installing -hyprland-git from the aur](#installation) or [building manually](#manual-manual-build). - +Finally on the guest follow the instructions above for either +[installing hyprland-git from the aur](#installation) or +[building manually](#manual-manual-build). {{< callout >}} -Make sure you install `mesa` as the OpenGL driver. The virgl drivers -are included in `mesa`. +Make sure you install `mesa` as the OpenGL driver. The virgl drivers are +included in `mesa`. {{}} diff --git a/pages/Getting Started/Master-Tutorial.md b/pages/Getting Started/Master-Tutorial.md index 9e8d71c..5512842 100644 --- a/pages/Getting Started/Master-Tutorial.md +++ b/pages/Getting Started/Master-Tutorial.md @@ -1,49 +1,51 @@ --- -weight: 1 +weight: 2 title: Master tutorial --- If you are coming to Hyprland for the first time, this is the main tutorial to read. -This tutorial will cover literally -everything you need to just get things going. It does link to other pages where -necessary. +This tutorial covers everything you need to get things going. It links to other +pages where necessary. ## Install Hyprland See [Installation](../Installation) and come back here once you have successfully installed Hyprland. -Install `kitty` (default terminal emulator) terminal. This is available in most -distros' repositories. +Install `kitty` (default terminal emulator). This is available in most distros' +repositories. -## NVIDIA? +## Nvidia? -_If not using an NVIDIA card, skip this step_ +_If not using an Nvidia card, skip this step_ -Please take a look at [The Nvidia page](../../Nvidia) before launching. It has a -lot of info regarding the needed environment and tweaks. +Please take a look at [The Nvidia page](../../Nvidia) before launching. It has +information regarding the needed environment and tweaks. ## VM? _If not using a VM, skip this step_ -In a VM, make sure you have 3D acceleration enabled in your virtio config (or -virt-manager) otherwise Hyprland _**will not work**_. +In a VM, make sure you have 3D acceleration enabled in your `virtio` config (or +`virt-manager`) otherwise Hyprland _**will not work**_. You can also passthru a GPU to make it work. -Please bear in mind 3D accel in VMs may be pretty slow. +Please bear in mind 3D acceleration in VMs may be pretty slow. ## Launching Hyprland -Now, you can just execute `Hyprland` in your tty. +Hyprland can be executed by typing `hyprland` in your tty. -**!IMPORTANT**: Do **not** launch Hyprland with `root` permissions (don't -`sudo`) +{{< callout type=warning >}} -You can see some launch flags by doing `Hyprland -h`, these include setting the +Do **not** launch Hyprland with `root` permissions (don't `sudo`) + +{{< /callout >}} + +You can see some launch flags by doing `hyprland -h`, these include setting the config path, ignoring a check for the above, etc. Login managers are not officially supported, but here's a short compatibility @@ -53,8 +55,10 @@ list: [latest git version](https://github.com/sddm/sddm) (or [sddm-git](https://aur.archlinux.org/packages/sddm-git) from AUR) to prevent SDDM bug [1476](https://github.com/sddm/sddm/issues/1476) (90s shutdowns). -- GDM → Works with the caveat of crashing Hyprland on the first launch -- ly → Works poorly +- GDM → Works with the caveat of crashing Hyprland on the first launch. +- greetd → Works flawlessly, especially with + [ReGreet](https://github.com/rharish101/ReGreet). +- ly → Works poorly. ## In Hyprland @@ -81,42 +85,44 @@ configuring your displays. See the [Useful Utilities page](../../Useful-Utilities) and the [Sway wiki page](https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway) -just about that. You can also visit the +about that. You can also visit the [Awesome-Hyprland](https://github.com/hyprland-community/awesome-hyprland) repository for a more comprehensive list. -## Fully configure +## Fully configure Hyprland Head onto the [Configuring Hyprland page](../../Configuring/Configuring-Hyprland) to learn all -about configuring Hyprland to your likings. +about configuring Hyprland to your liking. ## Cursors Cursors are a notorious pain to set up when you don't know how. See [this FAQ entry](../../FAQ#how-do-i-change-me-mouse-cursor) -If your cursor does not appear, then see +If your cursor does not appear, see [this FAQ entry](../../FAQ#me-cursor-no-render) ## Themes -Since this is not a fully-fledged Desktop Environment, you will need to use tools -such as `lxappearance` and `nwg-look` (recommended) for GTK, and `qt5ct` / +Since Hyprland is not a fully-fledged Desktop Environment, you will need to use +tools such as `lxappearance` or `nwg-look` (recommended) for GTK, and `qt5ct` / `qt6ct` for their respective Qt versions. Some older applications may also require `qt4ct`. ## Force apps to use Wayland A lot of apps will use Wayland by default. Chromium (and other browsers based on -it or electron) don't. You need to pass +it, or Electron) don't. You need to pass `--enable-features=UseOzonePlatform --ozone-platform=wayland` to them or use `.conf` files where possible. Chromium-based browsers also should have a toggle -in `chrome://flags`. Search for _"ozone"_ and select Wayland. If you are on NixOS -you can also set the environment variable `NIXOS_OZONE_WL=1` in your configuration. +in `chrome://flags`. Search for _"ozone"_ and select Wayland. If you are on +NixOS you can also set the environment variable `NIXOS_OZONE_WL=1` in your +configuration. For most electron apps, you should put the above in -`~/.config/electron-flags.conf`. VSCode is known to not work with that though. +`~/.config/electron-flags.conf`. Note that VSCode is known **not** to work with +it. A few more environment variables for forcing Wayland mode are documented [here](../../Configuring/Environment-variables). diff --git a/pages/Getting Started/_index.md b/pages/Getting Started/_index.md index 162728b..aa9203b 100644 --- a/pages/Getting Started/_index.md +++ b/pages/Getting Started/_index.md @@ -4,3 +4,8 @@ title: Getting Started sidebar: open: true --- + +If you are coming to Hyprland for the first time, read the +[Installation](./Installation) page. + +After you've installed Hyprland, read the [Master tutorial](./Master-Tutorial).