From 9c5c0d1afee2b83d166c0ece77f6481541a3dada Mon Sep 17 00:00:00 2001 From: Sean Molenaar Date: Sun, 13 Feb 2022 15:00:19 +0100 Subject: [PATCH 1/2] docs: document service block --- docs/Formula-Cookbook.md | 90 +++++++++++++++++++++++++++------------- 1 file changed, 62 insertions(+), 28 deletions(-) diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 43bf92ad2c949..6a8c9144ea426 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -761,44 +761,78 @@ For example, Ruby 1.9’s gems should be installed to `var/lib/ruby/` so that ge Another example would be configuration files that should not be overwritten on package upgrades. If after installation you find that to-be-persisted configuration files are not copied but instead *symlinked* into `/usr/local/etc/` from the Cellar, this can often be rectified by passing an appropriate argument to the package’s configure script. That argument will vary depending on a given package’s configure script and/or Makefile, but one example might be: `--sysconfdir=#{etc}` -### launchd plist files +### Service files -Homebrew provides two formula DSL methods for launchd plist files: - -* [`plist_name`](https://rubydoc.brew.sh/Formula#plist_name-instance_method) will return e.g. `homebrew.mxcl.` -* [`plist_path`](https://rubydoc.brew.sh/Formula#plist_path-instance_method) will return e.g. `/usr/local/Cellar/foo/0.1/homebrew.mxcl.foo.plist` - -There is two ways to add plists to a formula, so that [`brew services`](https://github.com/Homebrew/homebrew-services) can pick it up: -1. If the formula already provides a plist file the formula can install it into the prefix like so. +There are two ways to add plists and systemd services to a formula, so that [`brew services`](https://github.com/Homebrew/homebrew-services) can pick it up: +1. If the formula already provides a file the formula can install it into the prefix like so. ```ruby prefix.install_symlink "file.plist" => "#{plist_name}.plist" +prefix.install_symlink "file.service" => "#{service_name}.service" +``` + +2. If the formula does not provide a service you can generate one using the following stanza. +```rb +service do + run bin/"script" +end +``` + +#### Service block methods +There are many more options you can set within such a block, and in this table you will find them all. +The only required field in a `service` block is the `run` field to indicate what to run. + +| Method | Default | macOS | Linux | Description | +|-------------------------|--------------|-------|-------|------------------------------------------------------------------------------------------| +| `run` | - | yes | yes | Command to execute, an array with arguments or a path | +| `run_type` | `:immediate` | yes | yes | The type of service, `:immediate`, `:interval` or `:cron` | +| `keep_alive` | `false` | yes | yes | If the service needs to keep the process running after exit | +| `interval` | - | yes | yes | Controls the start interval, required for the `:interval` type | +| `cron` | - | yes | yes | Controls the trigger times, required for the `:cron` type | +| `launch_only_once` | false | yes | yes | If the command should only run once | +| `environment_variables` | - | yes | yes | A hash of variables to set | +| `working_dir` | - | yes | yes | The directory to operate from | +| `root_dir` | - | yes | yes | The directory to use as a chroot for the process | +| `input_path` | - | yes | yes | Path to use as input for the process | +| `log_path` | - | yes | yes | Path to write stdout to | +| `error_log_path` | - | yes | yes | Path to write stderr to | +| `restart_delay` | - | yes | yes | The delay before restarting a process | +| `process_type` | - | yes | no-op | The type of process to manage, `:background`, `:standard`, `:interactive` or `:adaptive` | +| `macos_legacy_timers` | - | yes | no-op | Timers created by launchd jobs are coalesced unless this is set | + +For services that start and keep running alive you can use the default `run_type :` like so: +```ruby + service do + run [opt_bin/"beanstalkd", "test"] + keep_alive true + run_type :immediate # This should be omitted since it's the default + end ``` -1. If the formula does not provide a plist you can add a plist using the following stanzas. -This will define what the user can run manually instead of the launchd service. +If a service needs to run on an interval, use `run_type :interval` and specify an interval: ```ruby - plist_options manual: "#{HOMEBREW_PREFIX}/var/some/bin/stuff run" + service do + run [opt_bin/"beanstalkd", "test"] + run_type :interval + interval 500 + end ``` -This provides the actual plist file, see [Apple's plist(5) man page](https://www.unix.com/man-page/mojave/5/plist/) for more information. +If a service needs to run at certain times, use `run_type :cron` and specify a time with the crontab syntax: ```ruby - def plist - <<~EOS - - - - - Label - #{plist_name} - ProgramArguments - - #{var}/some/bin/stuff - run - - - - EOS + service do + run [opt_bin/"beanstalkd", "test"] + run_type :interval + cron "5 * * * *" + end +``` + +For environment variables you can specify a hash. For the path there is the helper method `std_service_path_env`. +This method will set the path to `#{HOMEBREW_PREFIX}/bin:#{HOMEBREW_PREFIX}/sbin:/usr/bin:/bin:/usr/sbin:/sbin` so the service can find other `brew` commands. +```rb + service do + run opt_bin/"beanstalkd" + environment_variables PATH: std_service_path_env end ``` From 1d742d243bb947d412560d573d8803e51656fcf5 Mon Sep 17 00:00:00 2001 From: Sean Molenaar Date: Fri, 18 Feb 2022 18:10:06 +0100 Subject: [PATCH 2/2] Update docs/Formula-Cookbook.md Co-authored-by: Nanda H Krishna --- docs/Formula-Cookbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 6a8c9144ea426..5ca891fdd7168 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -822,7 +822,7 @@ If a service needs to run at certain times, use `run_type :cron` and specify a t ```ruby service do run [opt_bin/"beanstalkd", "test"] - run_type :interval + run_type :cron cron "5 * * * *" end ```