forked from quickshell/quickshell
docs: add build, packaging and development instructions
This commit is contained in:
parent
238ca8cf0b
commit
bd504daf56
GPG key ID:
4C88A185FB89301E
151
BUILD.md
Normal file
151
BUILD.md
Normal 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
69
CONTRIBUTING.md
Normal 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.
|
||||
92
README.md
92
README.md
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue