kosslan/quickshell
1
0
Fork 0
forked from quickshell/quickshell
Code Pull requests Activity

docs: add build, packaging and development instructions

Browse source
This commit is contained in:
outfoxxed 2024-06-02 14:37:48 -07:00
parent 238ca8cf0b
commit bd504daf56
Signed by: outfoxxed
GPG key ID: 4C88A185FB89301E
3 changed files with 241 additions and 73 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

151
BUILD.md Normal file
View file

@ -0,0 +1,151 @@
# Build instructions
Instructions for building from source and distro packagers. We highly recommend
distro packagers read through this page fully.
## Dependencies
Quickshell has a set of base dependencies you will always need, names vary by distro:
- `cmake`
- `qt6base`
- `qt6declarative`
- `pkg-config`
At least Qt 6.6 is required.
All features are enabled by default and some have their own dependencies.
##### Additional note to packagers:
If your package manager supports enabling some features but not others,
we recommend not exposing the subfeatures and just the main ones that introduce
new dependencies: `wayland`, `x11`, `pipewire`, `hyprland`
### Jemalloc
We recommend leaving Jemalloc enabled as it will mask memory fragmentation caused
by the QML engine, which results in much lower memory usage. Without this you
will get a perceived memory leak.
To disable: `-DUSE_JEMALLOC=OFF`
Dependencies: `jemalloc`
### Unix Sockets
This feature allows interaction with unix sockets and creating socket servers
which is useful for IPC and has no additional dependencies.
WARNING: Disabling unix sockets will NOT make it safe to run arbitrary code using quickshell.
There are many vectors which mallicious code can use to escape into your system.
To disable: `-DSOCKETS=OFF`
### Wayland
This feature enables wayland support. Subfeatures exist for each particular wayland integration.
WARNING: Wayland integration relies on featurs that are not part of the public Qt API and which
may break in minor releases. Updating quickshell's dependencies without ensuring without ensuring
that the current Qt version is supported WILL result in quickshell failing to build or misbehaving
at runtime.
Currently supported Qt versions: `6.6`, `6.7`.
To disable: `-DWAYLAND=OFF`
Dependencies:
- `qt6wayland`
- `wayland` (libwayland-client)
- `wayland-scanner` (may be part of your distro's wayland package)
- `wayland-protocols`
#### Wlroots Layershell
Enables wlroots layershell integration through the [wlr-layer-shell-unstable-v1] protocol,
enabling use cases such as bars overlays and backgrounds.
This feature has no extra dependencies.
To disable: `-DWAYLAND_WLR_LAYERSHELL=OFF`
[wlr-layer-shell-unstable-v1]: https://wayland.app/protocols/wlr-layer-shell-unstable-v1
#### Session Lock
Enables session lock support through the [ext-session-lock-v1] protocol,
which allows quickshell to be used as a session lock under compatible wayland compositors.
[ext-session-lock-v1]: https://wayland.app/protocols/ext-session-lock-v1
### X11
This feature enables x11 support. Currently this implements panel windows for X11 similarly
to the wlroots layershell above.
To disable: `-DX11=OFF`
Dependencies: `libxcb`
### Pipewire
This features enables viewing and management of pipewire nodes.
To disable: `-DSERVICE_PIPEWIRE=OFF`
Dependencies: `libpipewire`
### StatusNotifier / System Tray
This feature enables system tray support using the status notifier dbus protocol.
To disable: `-DSERVICE_STATUS_NOTIFIER=OFF`
Dependencies: `qt6dbus` (usually part of qt6base)
### MPRIS
This feature enables access to MPRIS compatible media players using its dbus protocol.
To disable: `-DSERVICE_MPRIS=OFF`
Dependencies: `qt6dbus` (usually part of qt6base)
### Hyprland
This feature enables hyprland specific integrations. It requires wayland support
but has no extra dependencies.
To disable: `-DHYPRLAND=OFF`
#### Hyprland Global Shortcuts
Enables creation of global shortcuts under hyprland through the [hyprland-global-shortcuts-v1]
protocol. Generally a much nicer alternative to using unix sockets to implement the same thing.
This feature has no extra dependencies.
To disable: `-DHYPRLAND_GLOBAL_SHORTCUTS=OFF`
[hyprland-global-shortcuts-v1]: https://github.com/hyprwm/hyprland-protocols/blob/main/protocols/hyprland-global-shortcuts-v1.xml
#### Hyprland Focus Grab
Enables windows to grab focus similarly to a context menu undr hyprland through the
[hyprland-focus-grab-v1] protocol. This feature has no extra dependencies.
To disable: `-DHYPRLAND_FOCUS_GRAB=OFF`
[hyprland-focus-grab-v1]: https://github.com/hyprwm/hyprland-protocols/blob/main/protocols/hyprland-focus-grab-v1.xml
## Building
*For developers and prospective contributors: See [CONTRIBUTING.md](CONTRIBUTING.md).*
We highly recommend using `ninja` to run the build, but you can use makefiles if you must.
#### Configuring the build
```sh
$ cmake -GNinja -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo [additional disable flags from above here]
```
Note that features you do not supply dependencies for MUST be disabled with their associated flags
or quickshell will fail to build.
Additionally, note that clang builds much faster than gcc if you care.
You may disable debug information but it's only a couple megabytes and is extremely helpful
for helping us fix problems when they do arise.
#### Building
```sh
$ cmake --build build
```
#### Installing
```sh
$ cmake --install build
```

69
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,69 @@
# Contributing / Development
Instructions for development setup and upstreaming patches.
If you just want to build or package quickshell see [BUILD.md](BUILD.md).
## Development
Install the dependencies listed in [BUILD.md](BUILD.md).
You probably want all of them even if you don't use all of them
to ensure tests work correctly and avoid passing a bunch of configure
flags when you need to wipe the build directory.
Quickshell also uses `just` for common development command aliases.
The dependencies are also available as a nix shell or nix flake which we recommend
using with nix-direnv.
Common aliases:
- `just configure [<debug|release> [extra cmake args]]` (note that you must specify debug/release to specify extra args)
- `just build` - runs the build, configuring if not configured already.
- `just run [args]` - runs quickshell with the given arguments
- `just clean` - clean up build artifacts. `just clean build` is somewhat common.
### Formatting
All contributions should be formatted similarly to what already exists.
Group related functionality together.
Run the formatter using `just fmt`.
If the results look stupid, fix the clang-format file if possible,
or disable clang-format in the affected area
using `// clang-format off` and `// clang-format on`.
### Linter
All contributions should pass the linter.
Note that running the linter requires disabling precompiled
headers and including the test codepaths:
```sh
$ just configure debug -DNO_PCH=ON -DBUILD_TESTING=ON
$ just lint
```
If the linter is complaining about something that you think it should not,
please disable the lint in your MR and explain your reasoning.
### Tests
If you feel like the feature you are working on is very complex or likely to break,
please write some tests. We will ask you to directly if you send in an MR for an
overly complex or breakable feature.
At least all tests that passed before your changes should still be passing
by the time your contribution is ready.
You can run the tests using `just test` but you must enable them first
using `-DBUILD_TESTING=ON`.
### Documentation
Most of quickshell's documentation is automatically generated from the source code.
You should annotate `Q_PROPERTY`s and `Q_INVOKABLE`s with doc comments. Note that the parser
cannot handle random line breaks and will usually require you to disable clang-format if the
lines are too long.
Before submitting an MR, if adding new features please make sure the documentation is generated
reasonably using the `quickshell-docs` repo.
Doc comments take the form `///` or `///!` (summary) and work with markdown.
Look at existing code for how it works.
Quickshell modules additionally have a `module.md` file which contains a summary, description,
and list of headers to scan for documentation.

94
README.md
View file

@ -11,7 +11,7 @@ Hosted on: [outfoxxed's gitea], [github]
Documentation available at [quickshell.outfoxxed.me](https://quickshell.outfoxxed.me) or
can be built from the [quickshell-docs](https://git.outfoxxed.me/outfoxxed/quickshell-docs) repo.
Some fully working examples can be found in the [quickshell-examples](https://git.outfoxxed.me/outfoxxed/quickshell-examples)
Some fully working examples can be found in the [quickshell-examples](https://git.outfoxxed.me/outfoxxed/quickshell-examples)
repo.
Both the documentation and examples are included as submodules with revisions that work with the current
@ -48,84 +48,32 @@ This repo has a nix flake you can use to install the package directly:
Quickshell's binary is available at `quickshell.packages.<system>.default` to be added to
lists such as `environment.systemPackages` or `home.packages`.
`quickshell.packages.<system>.nvidia` is also available for nvidia users which fixes some
common crashes.
The package contains several features detailed in [BUILD.md](BUILD.md) which can be enabled
or disabled with overrides:
```nix
quickshell.packages.<system>.default.override {
enableWayland = true;
enableX11 = true;
enablePipewire = true;
withQtSvg = true;
withJemalloc = true;
}
```
Note: by default this package is built with clang as it is significantly faster.
## Manual
## Arch (AUR)
Quickshell has a third party [AUR package] available under the same name.
As is usual with the AUR it is not maintained by us and should be looked over before use.
If not using nix, you'll have to build from source.
[AUR package]: https://aur.archlinux.org/packages/quickshell
### Dependencies
To build quickshell at all, you will need the following packages (names may vary by distro)
## Anything else
See [BUILD.md](BUILD.md) for instructions on building and packaging quickshell.
- just
- cmake
- ninja
- pkg-config
- Qt6 [ QtBase, QtDeclarative ]
Jemalloc is recommended, in which case you will need:
- jemalloc
To build with wayland support you will additionally need:
- wayland
- wayland-scanner (may be part of wayland on some distros)
- wayland-protocols
- Qt6 [ QtWayland ]
To build with x11 support you will additionally need:
- libxcb
To build with pipewire support you will additionally need:
- libpipewire
### Building
To make a release build of quickshell run:
```sh
$ just release
```
If running an nvidia GPU, instead run:
```sh
$ just configure release -DNVIDIA_COMPAT=ON
$ just build
```
(These commands are just aliases for cmake commands you can run directly,
see the Justfile for more information.)
If you have all the dependencies installed and they are in expected
locations this will build correctly.
To install to /usr/local/bin run as root (usually `sudo`) in the same folder:
```
$ just install
```
### Building (Nix)
You can build directly using the provided nix flake or nix package.
```
nix build
nix build -f package.nix # calls default.nix with a basic callPackage expression
```
# Development
For nix there is a devshell available from `shell.nix` and as a devShell
output from the flake.
The Justfile contains various useful aliases:
- `just configure [<debug|release> [extra cmake args]]`
- `just build` (runs configure for debug mode)
- `just run [args]`
- `just clean`
- `just test [args]` (configure with `-DBUILD_TESTING=ON` first)
- `just fmt`
- `just lint`
# Contributing / Development
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
#### License