From 9f836599fcf725d711909d49e1bad28bbbdc3680 Mon Sep 17 00:00:00 2001 From: Geoffrey Washburn Date: Mon, 2 Dec 2024 23:15:48 -0500 Subject: [PATCH] Reference pre-built binaries and restructure some for clarity. --- README.md | 116 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 66 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 2dca17c..de19951 100644 --- a/README.md +++ b/README.md @@ -26,65 +26,27 @@ A simple command-line tool for manipulating the configuration of macOS displays. ## Installation -Until someone creates packages for knoll, probably the most common way to -install it will be to use cargo or Nix. +### Pre-built binaries -### Cargo +Pre-built Intel and Apple Silicon binaries are available from the GitHub +repository [releases](https://github.com/gawashburn/knoll/releases/) page. -If you already have a Rust environment set up, you can use the -`cargo install` command: +Note that after downloading and unpacking, as these binaries are not signed +you may need to run the following command so that macOS will allow them to +be run: ```bash -cargo install knoll +xattr -d com.apple.quarantine /path/to/knoll ``` -### launchd - -The recommended solution for running knoll as a daemon is to make use of -[ -`launchd`](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html). -Choose a service name unique to your host using -the [reverse domain name](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) -convention and create a `.plist` file in `~/Library/LaunchAgents`: - -```xml - - - - - EnvironmentVariables - - PATH - ... - - KeepAlive - - Label - my.service.knoll - ProgramArguments - - /path/to/knoll - daemon - -vvv - --input=/path/to/config-file - - RunAtLoad - - StandardErrorPath - /tmp/knoll.err - StandardOutPath - /tmp/knoll.out - - -``` +### Cargo -You can then enable and start service using +If you already have a Rust environment set up, you can use the +`cargo install` command: ```bash -launchctl enable gui/$(id -u)/my.service.knoll` -launchctl start gui/$(id -u)/my.service.knoll` -```` +cargo install knoll +``` ### Nix @@ -130,6 +92,9 @@ use the following `launchd` definition like: }; ``` +The particulars of the configuration file you craft in your Nix definition will +be explained in the subsequent sections. + ## Usage knoll has three primary usage modes: pipeline mode, listing mode, and @@ -382,6 +347,57 @@ level of responsiveness, it can be configured: host$ knoll daemon --wait=500ms --input=my_config.json ``` +### launchd + +The recommended solution for running knoll as a daemon is to make use of +[ +`launchd`](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html). +If you are not using nix-darwin as described in +the [Installation](#installation) +section, you can still configure `launchd` manually. +Choose a service name unique to your host using +the [reverse domain name](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) +convention and create a `.plist` file in `~/Library/LaunchAgents`: + +```xml + + + + + EnvironmentVariables + + PATH + ... + + KeepAlive + + Label + my.service.knoll + ProgramArguments + + /path/to/knoll + daemon + -vvv + --input=/path/to/config-file + + RunAtLoad + + StandardErrorPath + /tmp/knoll.err + StandardOutPath + /tmp/knoll.out + + +``` + +You can then enable and start service using + +```bash +launchctl enable gui/$(id -u)/my.service.knoll` +launchctl start gui/$(id -u)/my.service.knoll` +```` + ## Configuration reference A configuration may contain the following fields: