mirror of
https://github.com/pjones/plasma-manager.git
synced 2024-10-04 03:07:17 +03:00
144 lines
7.3 KiB
Markdown
144 lines
7.3 KiB
Markdown
# Manage KDE Plasma with Home Manager
|
|
|
|
This project aims to provide [Home Manager][home-manager] modules which allow you
|
|
to configure KDE Plasma using Nix.
|
|
|
|
## Table of contents
|
|
- [Manage KDE Plasma with Home Manager](#manage-kde-plasma-with-home-manager)
|
|
- [Table of contents](#table-of-contents)
|
|
- [Supported versions](#supported-versions)
|
|
- [What's supported](#whats-supported)
|
|
- [What's not well supported (at the moment)](#whats-not-well-supported-at-the-moment)
|
|
- [What will not be supported](#what-will-not-be-supported)
|
|
- [Getting started](#getting-started)
|
|
- [Make your configuration more declarative with overrideConfig](#make-your-configuration-more-declarative-with-overrideconfig)
|
|
- [Capturing Your Current Configuration with rc2nix](#capturing-your-current-configuration-with-rc2nix)
|
|
- [Contributions and Maintenance](#contributions-and-maintenance)
|
|
- [Special Thanks](#special-thanks)
|
|
|
|
## Supported versions
|
|
`plasma-manager` supports both plasma 5 and plasma 6. The `trunk` branch is the
|
|
most up-to-date branch and is mainly focused on plasma 6, but may still work on
|
|
plasma 5. If you are running plasma 5, it's recommended to use the `plasma-5`
|
|
branch, which is designed to have better compatibility with plasma 5. To do this
|
|
with flakes you can use "github:nix-community/plasma-manager/plasma-5" as your
|
|
flake url, or if you are using nix-channels you can set the channel url to
|
|
"https://github.com/nix-community/plasma-manager/archive/plasma-5.tar.gz". It's
|
|
worth noting that the plasma 5 branch, due to the extra work required for
|
|
maintaining, may lag behind a bit in features, but in general it should be less
|
|
broken when used with plasma 5. If you want the best experience with
|
|
`plasma-manager` it's recommended running plasma 6.
|
|
|
|
## What's supported
|
|
At the moment `plasma-manager` supports configuring the following:
|
|
- KDE configuration files (via the `files` module)
|
|
- Global themes, colorschemes, icons, cursortheme, wallpaper (via the `workspace` module)
|
|
- Desktop icons, widgets, and mouse actions (via the `desktop` module)
|
|
- Configuration of spectacle shortcuts (via the `spectacle` module)
|
|
- Shortcuts (via the `shortcuts` module)
|
|
- Hotkeys (via the `hotkeys` module)
|
|
- Panels and Extra Widgets (via the `panels` module)
|
|
- Keyboards, Touchpads and Mice (via the `input` module)
|
|
- Screen locker (via the `kscreenlocker` module)
|
|
- Fonts (via the `fonts` module)
|
|
- Window Rules (via the `window-rules` module)
|
|
- KDE apps (via the `apps` module). In particular the following kde apps have
|
|
modules in `plasma-manager`:
|
|
- kate
|
|
- konsole
|
|
- okular
|
|
|
|
Additionally there are more functionality than just listed above, and more
|
|
functionality to come in the future!
|
|
|
|
## What's not well supported (at the moment)
|
|
There also are some things which at the moment isn't very well supported, in
|
|
particular:
|
|
- Real-time updates of configuration without having to log out and back in
|
|
- Usage of high-level modules in the configuration generated by `rc2nix`
|
|
- Keybindings to some key combinations (`Ctrl+Alt+T` and `Print` for example, see https://github.com/nix-community/plasma-manager/issues/109 and https://github.com/nix-community/plasma-manager/issues/136)
|
|
|
|
There may also be more things we aren't aware of. If you find some other
|
|
limitations don't hesitate to open an issue or submit a pr.
|
|
|
|
## What will not be supported
|
|
There are some things which are out of bounds for this project due to technical
|
|
reasons. For example
|
|
- SDDM configuration (requires root-privileges and thus not suited for a `home-manager` module)
|
|
|
|
## Getting started
|
|
We provide some examples to help you get started. These are located in the
|
|
[examples](./examples/) directory. Here you in particular can find:
|
|
- [An example home-manager configuration](./examples/homeManager/home.nix) [with instructions](./examples/homeManager/README.md)
|
|
- [An example flake.nix for usage with home-manager only](./examples/homeManagerFlake//flake.nix)
|
|
- [An example flake.nix for usage with the system configuration](./examples/systemFlake/flake.nix)
|
|
- [An example home.nix showing some of the capabilities of plasma-manager](./examples/home.nix)
|
|
|
|
See the manual for [Plasma-Manager Options](https://nix-community.github.io/plasma-manager/options.xhtml).
|
|
|
|
With more to come! These should give you some idea how to get started with
|
|
`plasma-manager`.
|
|
|
|
## Make your configuration more declarative with overrideConfig
|
|
By default `plasma-manager` will simply write the specified configurations to
|
|
various config-files and leave all other options alone. This way settings not
|
|
specified in `plasma-manager` will be left alone, meaning that configurations
|
|
made outside `plasma-manager` will still be set. This can lead to different
|
|
settings on different machines even with the same `plasma-manager`
|
|
configuration. If you like a declarative approach better consider enabling
|
|
`overrideConfig`. This makes it so all options not set by `plasma-manager` will
|
|
be set to the default on login. In practice this then becomes a declarative
|
|
setup, much like what you would expect from most `home-manager` options/modules.
|
|
|
|
One thing to keep in mind is that enabling this option will delete all the KDE
|
|
config-files on `home-manager` activation, and replace them with config-files
|
|
generated by `plasma-manager`. Therefore make sure you backup your KDE
|
|
config-files before enabling this option if you don't want to lose them.
|
|
|
|
## Capturing Your Current Configuration with rc2nix
|
|
|
|
To make it easier to migrate to `plasma-manager`, and to help maintain your Nix
|
|
configuration when not using `overrideConfig`, this project includes a tool
|
|
called `rc2nix`.
|
|
|
|
This tool will read KDE configuration files and translate them to Nix. The
|
|
translated configuration is written to standard output. This makes it easy to:
|
|
|
|
- Generate an initial Plasma Manager configuration file.
|
|
- See what settings are changed by a GUI tool by capturing a file
|
|
before and after using the tool and then using `diff`.
|
|
|
|
Keep in mind that the `rc2nix` module isn't perfect and often will give somewhat
|
|
suboptimal configurations (it will in some cases prefer using the `files` module
|
|
when better configurations can be achieved using higher-level modules). However,
|
|
it is still a useful tool to quickly get your configuration up and running or
|
|
converting config-files generated by the gui settings app to nix expressions.
|
|
|
|
To run the `rc2nix` tool without having to clone this repository run
|
|
the following shell command:
|
|
|
|
```sh
|
|
nix run github:nix-community/plasma-manager
|
|
```
|
|
|
|
## Contributions and Maintenance
|
|
|
|
This is a community project and we welcome all contributions. KDE plasma and its
|
|
apps consists of a lot of configuration options, and if you find that some
|
|
options are missing and have the skills to implement this, PRs are very welcome.
|
|
Issues are also welcome for everything from feature-requests to bug-reports or
|
|
just general suggestions for improving the project.
|
|
|
|
## Special Thanks
|
|
|
|
`plasma-manager` started off it's development under
|
|
[pjones](https://github.com/pjones), whose contributions have laid the
|
|
foundation of the project to this day. The project was otherwise inspired by the
|
|
suggestions on [Home Manager Issue
|
|
#607][hm607] by people such as [bew](https://github.com/bew) and
|
|
[kurnevsky](https://github.com/kurnevsky). Thank you.
|
|
|
|
[home-manager]: https://github.com/nix-community/home-manager
|
|
[hm607]: https://github.com/nix-community/home-manager/issues/607
|
|
[nix-community]: https://github.com/nix-community
|