docs: linter & packagers guide & chores (#64)

add prettier, move most markdown into `docs/` and add a packagers guide --- * lint(md): add prettier * docs(packagers): add a guide * docs(correctness): Index -> ToC * docs: link to package maintainers guide * docs: move install docs to `./docs` * docs(fix): typo
2025-08-30 18:08:00 +02:00 · 2025-07-16 18:13:12 +02:00
parent 589f33ffec
commit 4a1b868b8e
7 changed files with 137 additions and 71 deletions
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -13,33 +13,33 @@ For small fixes or incremental improvements simply fork the repo and follow the

 1. [Fork](https://help.github.com/articles/fork-a-repo/) the repository and [clone](https://help.github.com/articles/cloning-a-repository/) your fork.

-2. Start coding! (it might be helpful to read a [quide on the project structure and conventions](structure.md) before this)
-   * Configure clangd LSP by generating `compile_commands.json` (e.g. `bear -- make` or `compiledb make`)
-   * Implement your feature.
-   * Check your code works as expected.
-   * Run the code formatter: `clang-format -i $(git ls-files "*.c" "*.h")`
-   * Run the code linter: `clang-tidy -p . $(git ls-files "*.c" "*.h")`. Some checks are pretty pedantic, feel free to ignore or debate some of the rules.
-   * If you prefer, you can run `make pre-commit` to run several code style checks like the above along a few extra stuff.
+2. Start coding! (it might be helpful to read a [quide on the project structure and conventions](./structure.md) before this)
+   - Configure clangd LSP by generating `compile_commands.json` (e.g. `bear -- make` or `compiledb make`)
+   - Implement your feature.
+   - Check your code works as expected.
+   - Run the code formatter: `clang-format -i $(git ls-files "*.c" "*.h")`.
+   - Run the code linter: `clang-tidy -p . $(git ls-files "*.c" "*.h")`. Some checks are pretty pedantic, feel free to ignore or debate some of the rules.
+   - If you prefer, you can run `make pre-commit` to run several code style checks like the above along a few extra stuff (shellcheck, spellcheck, prettier, etc).

 3. Commit your changes to a new branch (not `master`, one change per branch) and push it:
-   * Commit messages should:
-     * Header line: explain the commit in one line (use the imperative) ("feat" for features, "fix", "style", "chore", "docs", etc)
-     * Be descriptive.
-     * Don't make the title too long and add commit descriptions if you think the changes need it.
-     * e.g. "feat: add support for X", "fix(config): config parser segfaulting", "docs(typo): fix a typo in README.md"
+   - Commit messages should:
+     - Header line: explain the commit in one line (use the imperative) ("feat" for features, "fix", "style", "chore", "docs", etc)
+     - Be descriptive.
+     - Don't make the title too long and add commit descriptions if you think the changes need it.
+     - e.g. "feat: add support for X", "fix(config): config parser segfaulting", "docs(typo): fix a typo in README.md"

 4. Once you are happy with your changes, submit a pull request.
-   * Open the pull request.
-   * Add a short description explaining what you've done (or if it's a work-in-progress - what you need to do)
+   - Open the pull request.
+   - Add a short description explaining what you've done (or if it's a work-in-progress - what you need to do)

 ## Issues

 1. Do a quick search on GitHub to check if the issue has already been reported.
 2. [Open an issue](https://github.com//javalsai/lidm/issues/new) and describe the issue you are having - you could include:
-   * Screenshots.
-   * Ways to reproduce the issue.
-   * Your lidm version.
-   * Your platform (e.g. arch linux or Ubuntu 15.04 x64) and init system if you know.
+   - Screenshots.
+   - Ways to reproduce the issue.
+   - Your lidm version.
+   - Your platform (e.g. arch linux or Ubuntu 15.04 x64) and init system if you know.

 After reporting you should aim to answer questions or clarifications as this helps pinpoint the cause of the issue.

--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -0,0 +1,128 @@
+# Table of Contents
+
+- [Installing from Source](#installing-from-source)
+- [AUR](#aur)
+- [Nix Flake](#nix-flake)
+- [Nix Module](#nix-module)
+
+> [!CAUTION]
+> I encourage you to read the manual installation steps to understand what will get installed in your computer by this package.
+
+# Installing from Source
+
+Firstly, you'll need to build the package, this also includes man pages, default config, themes and other files you might need.
+
+To build it you only need to have some basic packages (should come pre-installed in almost all distros): `make`, `gcc` or another `gcc`ish compiler, and libpam headers. If it builds, it surely works anyways.
+
+```sh
+git clone https://github.com/javalsai/lidm.git
+cd lidm
+make # 👍
+```
+
+> [!NOTE]
+> There's pre-built binaries on the [releases tab](https://github.com/javalsai/lidm/releases) too.
+
+Then you can install the files onto your filesystem with:
+
+```sh
+make install
+```
+
+And additionally, to install service files (start-up behavior). <sup>[more docs](./assets/services/README.md)</sup>
+
+```sh
+# automatically detects your init system
+# and install service file (for tty7)
+make install-service
+
+# or if you don't like autodetection
+make install-service-systemd # systemd
+make install-service-dinit # dinit
+make install-service-runit # runit (/etc/sv)
+make install-service-runit-etc # runit (/etc/runit/sv)
+make install-service-openrc # openrc
+make install-service-s6 # s6 (/etc/sv)
+make install-service-s6-etc # s6 (/etc/s6/sv)
+
+#  For runit and s6, some distros (e.g. Artix) like to put it in /etc/<init>/sv
+# to better isolate their packages while other distros (e.g. Void) just put it
+# in /etc/sv
+```
+
+# AUR
+
+[AUR packages](https://aur.archlinux.org/packages?K=lidm&SeB=n) will automatically install most files.
+
+> [!CAUTION]
+> [service files](./assets/pkg/aur#services) have to be manually installed by now.
+
+# Nix Flake
+
+You can install by doing
+
+```sh
+nix profile install github:javalsai/lidm
+```
+
+or try it out without installing by:
+
+```sh
+nix run github:javalsai/lidm
+```
+
+> [!CAUTION]
+> This doesn't include [service files](./assets/pkg/aur#services) neither
+
+# Nix Module
+
+<details>
+<summary>Sidenote</summary>
+
+The nix module lacks on several aspects, if you know much about nix and know
+how to improve this package, feel free to open an issue or a PR to help. The
+nix package maintainer position is open too.
+
+</details>
+
+Lidm includes a nix module in `assets/pkg/nix/module.nix` that you can add
+(along the included nix files) and import in your `configuration.nix`.
+
+Once imported you'll need to add:
+
+```nix
+services.displayManager.enable = true;
+systemd.services.lidm.enable = true;
+```
+
+Optionally, you can configure it setting `services.lidm.config`. You can either
+pass:
+
+- A string to copy the config from a theme in `themes/` with said name
+  (**name**, e.g `"cherry"`).
+- An attribute tree with the same names as the config file, e.g:
+
+```nix
+with config.lidm.keysEnum; {
+    strings = {
+        f_poweroff = "custom_poweroff";
+    };
+
+    behavior = {
+        include_defshell = true;
+        source = [
+            "path1"
+            "path2"
+        ];
+    };
+
+    functions = { poweroff = F1; };
+
+    # etc...
+};
+```
+
+> _it's not necessary to cover all keys and anything can be put there, even if it's not valid config_
+
+> [!NOTE]
+> [service files](./assets/pkg/aur#services) **are** included and enabled
--- a/docs/PACKAGERS.md
+++ b/docs/PACKAGERS.md
@@ -0,0 +1,62 @@
+This is a guide listing all possible options packagers have to tweak behavior of lidm and the extra stuff to package.
+
+# Components
+
+If you want to package lidm for a distribution you have to package the binary and:
+
+- Man pages ([`../assets/man/`](../assets/man/))
+- Service files ([`../assets/services/`](../assets/services/))
+- PAM (see [#preprocessor-defines](#preprocessor-defines))
+- And optionally you can include some default themes in `/usr` ([`../themes/`](../themes/))
+
+# Preprocessor Defines
+
+Most of the behavior that can be tweaked using preprocessor `#define`s, to include some simply add `CPPFLAGS+='-D{{name}}={{value}}'` to your `make` command. e.g:
+
+```sh
+make \
+    CPPFLAGS+='-DSESSIONS_XSESSIONS=\"/var/empty\"' \
+    CPPFLAGS+='-DSESSIONS_WAYLAND=\"/var/empty\"'
+```
+
+The list of possible `#define`s is:
+
+| Name                   | Default                         | Description                                                                | Env Override?            |
+| ---------------------- | ------------------------------- | -------------------------------------------------------------------------- | ------------------------ |
+| `PAM_SERVICE_FALLBACK` | `"login"`                       | Name of the default PAM module to use. Defaults to the distro's `"login"`. | Yes (`LIDM_PAM_SERVICE`) |
+| `SESSIONS_XSESSIONS`   | `"/usr/share/xsessions"`        |                                                                            | No                       |
+| `SESSIONS_WAYLAND`     | `"/usr/share/wayland-sessions"` |                                                                            | No                       |
+| `LIDM_CONF_PATH`       | `"/etc/lidm.ini"`               | Path of the default configuration.                                         | Yes (`LIDM_CONF`)        |
+
+# Other Build Settings
+
+## Compiler
+
+Lidm attempts to support being built by `gcc` and `clang` with preference over the first. However, if you wish to take advantage of LLVM's optimizations over GNU's you can change the compiler with `make CC=clang` or try any other compiler.
+
+## Compiler Flags
+
+Compiler flags should be passed with `CFLAGS`, its `-O3 -Wall` by default so adding anything will overwrite this.
+
+## Target Directory
+
+`DESTDIR` can be used to for installation recipes to install on alternative root directories. Along with `PREFIX` (defaults to `/usr`) for systems which don't use the common `/usr` structure. e.g. `make install DESTDIR=$out PREFIX=`
+
+```txt
+$ fd -t f . --base-directory $out
+bin/lidm
+etc/lidm.ini
+share/man/man1/lidm.1
+share/man/man5/lidm-config.5
+```
+
+# Build Recipes for Packaging
+
+To ease most of the installation process there's several `make` recipes to install man pages and service files, I encpurage you to check their source yourself, but:
+
+- `make` / `make lidm`: Builds the app binary.
+- `make install`: Attempts to install the binary, place a default config file in `/etc/lidm.ini` and install the man pages.
+- `make install-service-(systemd|dinit|runit|openrc|s6)(|-etc)`: Just check the source, service files for different init systems and `-etc` variants for alternative paths.
+- `make print-version`: Outputs the current version in the `Makefile` for scripts that might want to extract that info.
+
+You can choose to use these packages or create your own service files / etc. There's are merely suggestions on what to use.