From 16ffb26fba04813cc48e3739662c328e7cc900c7 Mon Sep 17 00:00:00 2001 From: outfoxxed Date: Sat, 26 Jul 2025 22:02:07 -0700 Subject: [PATCH] update install guide for v0.2.0 --- src/guide/v0_1_0/install-setup.md | 3 - src/guide/v0_2_0/install-setup.md | 194 ++++++++++++++++++++++++++++++ 2 files changed, 194 insertions(+), 3 deletions(-) create mode 100644 src/guide/v0_2_0/install-setup.md diff --git a/src/guide/v0_1_0/install-setup.md b/src/guide/v0_1_0/install-setup.md index dcdc612..4f9cfd0 100644 --- a/src/guide/v0_1_0/install-setup.md +++ b/src/guide/v0_1_0/install-setup.md @@ -116,9 +116,6 @@ If you want to write your own configuration, installing a QML grammar and the LS Read the [Usage Guide](@docs/guide) after configuring your editor. -> [!NOTE] -> Qmlls versions prior to 6.8.2 do not require `-E` - ### Emacs Install the [yuja/tree-sitter-qml](https://github.com/yuja/tree-sitter-qmljs) tree-sitter grammar, and the [xhcoding/qml-ts-mode](https://github.com/xhcoding/qml-ts-mode) mode. diff --git a/src/guide/v0_2_0/install-setup.md b/src/guide/v0_2_0/install-setup.md new file mode 100644 index 0000000..8989a58 --- /dev/null +++ b/src/guide/v0_2_0/install-setup.md @@ -0,0 +1,194 @@ +--- +title: "Installation & Setup" +index: 0 +--- +> [!NOTE] +> Quickshell is still in a somewhat early stage of development. +> There will be breaking changes before 1.0, however a migration guide will be provided. + +## Installation + +Since Quickshell 0.1, you can now choose whether to install by tracking the master branch, +or install by latest release. + +Note that you may want to install some additional packages (names vary by distro): +- `qtsvg`: support for SVG image loading (bundled with most packages) +- `qtimageformats`: support for WEBP images as well as some less common ones +- `qtmultimedia`: support for playing videos, audio, etc +- `qt5compat`: extra visual effects, notably gaussian blur. @@QtQuick.Effects.MultiEffect is usually preferable + +### Nix +Release versions of Quickshell are available from Nixpkgs under the `quickshell` package. + +The Quickshell repo also has an embedded flake which can be used from either mirror: +- `git+https://git.outfoxxed.me/outfoxxed/quickshell` +- `github:quickshell-mirror/quickshell` + +> [!NOTE] +> You can use `?ref=` to specify a tag if you want a tagged release. + +```nix +{ + inputs = { + nixpkgs.url = "nixpkgs/nixos-unstable"; + + quickshell = { + # add ?ref= to track a tag + url = "git+https://git.outfoxxed.me/outfoxxed/quickshell"; + + # THIS IS IMPORTANT + # Mismatched system dependencies will lead to crashes and other issues. + inputs.nixpkgs.follows = "nixpkgs"; + }; + }; +} +``` + +The package is available as `quickshell.packages..default`, which can be added to +your `environment.systemPackages`, `home.packages` if you use home-manager, or a devshell. + +When using the flake, additional QML packages can be added to Quickshell's environment using +`.withModules [ ]`. + +### Arch +Quickshell is available from the aur under: +- the [quickshell](https://aur.archlinux.org/packages/quickshell) package for the latest release +- the [quickshell-git](https://aur.archlinux.org/packages/quickshell-git) package that tracks the master branch + +> [!WARNING] +> When using an AUR package, Quickshell may break whenever Qt is updated. +> The AUR gives us no way to actually fix this, but Quickshell will attempt to +> warn you if it detects a breakage when updating. If warned of a breakage, +> please reinstall the package. + +Install using the command below: +```sh +yay -S quickshell +# or +yay -S quickshell-git +``` +(or your AUR helper of choice) + +### Fedora +Quickshell is available from the [errornointernet/quickshell] COPR, as either: +- `quickshell` that tracks the latest release +- `quickshell-git` that tracks the master branch + +[errornointernet/quickshell]: https://copr.fedorainfracloud.org/coprs/errornointernet/quickshell + +Install using the command below: +```sh +sudo dnf copr enable errornointernet/quickshell + +sudo dnf install quickshell +# or +sudo dnf install quickshell-git +``` + +### Guix +Release versions of Quickshell are available from the standard Guix repository +as `quickshell` from the `(gnu packages wm)` module. + +Install using the command below: +```sh +guix install quickshell +``` + +You can also add `quickshell` to your Guix system configuration or Guix Home configuration. + +For the git version, Quickshell's source repository works as a channel. +Add the following to your channel list: + +```scheme +(channel + (name quickshell) + (url "https://git.outfoxxed.me/outfoxxed/quickshell") + (branch "master")) +``` + +However, since the package definition is located in the source repository, it cannot be used +as a channel out of the box. You can clone the repository and use `guix shell -f quickshell.scm` +to use the git version of the package. + +### Manual build +See [BUILD.md](https://git.outfoxxed.me/quickshell/quickshell/src/branch/master/BUILD.md) +for build instructions and configurations. + +## Editor configuration +If you want to write your own configuration, installing a QML grammar and the LSP is recommended. + +Read the [Usage Guide](@docs/guide) after configuring your editor. + +> [!NOTE] +> Qmlls versions prior to 6.8.2 do not require `-E` + +### Emacs +Install the [yuja/tree-sitter-qml](https://github.com/yuja/tree-sitter-qmljs) tree-sitter grammar, +and the [xhcoding/qml-ts-mode](https://github.com/xhcoding/qml-ts-mode) mode. + +Both are packaged for nix via [outfoxxed/nix-qml-support](https://git.outfoxxed.me/outfoxxed/nix-qml-support). + +Either `lsp-mode` or `eglot` should be usable for LSP ([caveats below](#language-server)). + +The author's personal emacs config uses `lsp-mode` and `qml-ts-mode` as follows: +```elisp +(use-package qml-ts-mode + :after lsp-mode + :config + (add-to-list 'lsp-language-id-configuration '(qml-ts-mode . "qml-ts")) + (lsp-register-client + (make-lsp-client :new-connection (lsp-stdio-connection '("qmlls")) + :activation-fn (lsp-activate-on "qml-ts") + :server-id 'qmlls)) + (add-hook 'qml-ts-mode-hook (lambda () + (setq-local electric-indent-chars '(?\n ?\( ?\) ?{ ?} ?\[ ?\] ?\; ?,)) + (lsp-deferred)))) +``` + +### Neovim +Neovim has built-in syntax highlighting for QML, however tree-sitter highlighting +may work better than the built-in highlighting. You can install the grammar +using `:TSInstall qmljs`. + +To use the language server ([caveats below](#language-server)), +install [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig) +and the following snippet to your configuration: + +```lua +require("lspconfig").qmlls.setup {} +``` + +### Helix +Helix has built-in syntax highlighting and qmlls support. + +### Vscode +1. Install the [Official QML Support extension] +2. Enable the `qt-qml.qmlls.useQmlImportPathEnvVar` setting. +![](/assets/images/vscode-qml-env.png) + +[Official QML Support extension]: https://marketplace.visualstudio.com/items?itemName=TheQtCompany.qt-qml + +## Language Server +The QML language has an associated language server, +[qmlls](https://doc.qt.io/qt-6/qtqml-tooling-qmlls.html). +We recommend using it, as it will catch a lot of bad practice that may +make your configuration harder to maintain later. + +To enable language server support for your shell, create an empty file named `.qmlls.ini` +next to the `shell.qml` file. Quickshell will replace it with a managed qmlls configuration. +You should gitignore the `.qmlls.ini` file, as its content depends on information that +is different on every computer. + +We are aware of the following issues: +- Qmlls does not work well when a file is not correctly structured. + This means that completions and lints won't work unless braces are closed + correctly and such. +- The LSP cannot provide any documentation for Quickshell types. +- `PanelWindow` in particular cannot be resolved. + +Keeping in mind the above caveats, qmlls should be able to guide you towards a +more correct code should you choose to use it. + +# Next steps + +Create your first configuration by reading the [Intro](@docs/configuration/intro).