docs: add build, packaging and development instructions

BUILD.md

@@ -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
+```

CONTRIBUTING.md

@@ -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.

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
+The package contains several features detailed in [BUILD.md](BUILD.md) which can be enabled
-common crashes.
+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
+## Anything else
-To build quickshell at all, you will need the following packages (names may vary by distro)
+See [BUILD.md](BUILD.md) for instructions on building and packaging quickshell.
 
-- just
+# Contributing / Development
-- cmake
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
-- 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`
 
 #### License