Add LICENSE and README.md

2 files changed, 43 insertions, 0 deletions

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..f55a5b6
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024 Andreas Grois
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6e35f5e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,34 @@
+# swaystatus
+
+This is a small status bar application that I write/maintain because I use it myself. You probably do not want to use this.
+The only reason I published it is because I wanted to have it available somewhere online, for reference.
+
+## Information for users
+
+Let me start with the important part: For most users this program is not a good choice. Mainly because it is rather limited feature-wise, and I have no plans to extend it beyond my own personal needs.
+So, if you just want to have a nice status bar for sway or i3, check out [i3status-rust](https://github.com/greshake/i3status-rust) instead. It's very similar, but has way more features.
+
+However, if you want something that's similar to i3status-rust, but with a fully modular plugin architecture, then this might be of interest to you. Instead of having to choose at build-time which features should be enabled, with this program you can just add/remove features by installing/removing plugins.
+
+### Setup
+
+This repo is a cargo workspace. Just clone it, and run `cargo build --release`. That will generate a swaystatus executable, as well as a bunch of plugin .so files in the target/release folder. To exclude certain plugins from a build (for instance), use `cargo build --release --workspace --exclude <whatever>`. This is useful if you don't have all dependencies of all plugins on your machine (for instance swaystatus-pulse needs pulseaudio, but if you don't have pulseaudio, you likely won't need swaystatus-pulse either). Then toss the binary and the plugin files at folders that are convenient to you.
+
+For more information, run `swaystatus --help`. The last few lines of help output detail where plugins are searched by default, and how you can override the plugin path.
+
+#### Configuration
+
+You'll need a config file. The easiest way to get started is to run `swaystatus --print-sample-config` and start from there. Each plugin has its own configuration, of course, so you might get some valuable insights from `swaystatus --plugin-help` too.
+
+#### Launching
+
+Unless you put the libraries and the configuration exactly where this program expects them to be, you'll want to pass both paths: `swaystatus -p <plugin-folder> -c <config-file>`.
+
+
+## Info for developers
+
+First things first again: Feel free to extend this, PRs are welcome. Hoever, my motivation to work on this tool is limited, so, please keep your expectations low. If you want, feel free to fork and do whatever you like - but, if possible, keep the plugin interface compatible. That way people can easily mix plugins from different forks.
+
+### Making a new plugin
+
+Plugins are Rust crates that compile to shared libraries. Check out the Cargo.toml file of the clock plugin to get started. The plugin interface is in the swaystatus-plugin crate. It's rather straightforward to implement. You'll need three objects, a `SwayStatusModule`, a `SwayStatusModuleInstance` and a `SwayStatusModuleRunnable`. The Module describes the plugin itself, and offers ways to spawn a `SwayStatusModuleInstance` (either with default values, or with deserialized configuration). The `SwayStatusModuleInstance` stores the configuration, and allows spawning of a `SwayStatusModuleRunnable`, which does the work. Communication between plugin and main program is done via traits too. The main program passes a means to send data to it when spawning the runnable, and wants to get a way to pass messages to the runnable in return. Check out the clock plugin for a simple channel-based approach, and the pulse (or the WIP alsa) plugins for more exotic solutions. Happy hacking.
\ No newline at end of file