From 2ddebb3189ccd54c7741f6feaaa9d131685a62c5 Mon Sep 17 00:00:00 2001 From: Malo Bourgon Date: Wed, 24 Aug 2022 17:35:42 -0700 Subject: [PATCH] Improve documentation of `homebrew` module --- modules/homebrew.nix | 90 +++++++++++++++++++++++++++++++------------- 1 file changed, 63 insertions(+), 27 deletions(-) diff --git a/modules/homebrew.nix b/modules/homebrew.nix index d462aaec..200e0d7d 100644 --- a/modules/homebrew.nix +++ b/modules/homebrew.nix @@ -70,14 +70,15 @@ let example = "uninstall"; description = '' This option manages what happens to formulae installed by Homebrew, that aren't present in - the Brewfile generated by this module, during nix-darwin activation. + the Brewfile generated by this module, during nix-darwin system + activation. When set to "none" (the default), formulae not present in the generated Brewfile are left installed. When set to "uninstall", nix-darwin invokes brew bundle [install] with the --cleanup flag. This - uninstalls all formulae not listed in generate Brewfile, i.e., + uninstalls all formulae not listed in generated Brewfile, i.e., brew uninstall is run for those formulae. When set to "zap", nix-darwin invokes @@ -96,10 +97,14 @@ let default = false; description = '' Whether to enable Homebrew to auto-update itself and all formulae during - nix-darwin activation. The default is false so that - repeated invocations of darwin-rebuild switch are idempotent. + nix-darwin system activation. The default is false + so that repeated invocations of darwin-rebuild switch are idempotent. Note that Homebrew auto-updates when it's been more then 5 minutes since it last updated. + + Although auto-updating is disabled by default during system activation, note that Homebrew + will auto-update when you manually invoke certain Homebrew commands. To modify this + behavior see ${mkDocOptionLink "homebrew.global.autoUpdate"}. ''; }; upgrade = mkOption { @@ -107,8 +112,8 @@ let default = false; description = '' Whether to enable Homebrew to upgrade outdated formulae and Mac App Store apps during - nix-darwin activation. The default is false so - that repeated invocations of darwin-rebuild switch are idempotent. + nix-darwin system activation. The default is false + so that repeated invocations of darwin-rebuild switch are idempotent. ''; }; @@ -330,7 +335,8 @@ let description = '' Target location for Audio Unit Plugins. - Homebrew's default is ~/Library/Audio/Plug-Ins/Components. + Homebrew's default is + ~/Library/Audio/Plug-Ins/Components. ''; }; vst_plugindir = mkNullOrStrOption { @@ -363,7 +369,11 @@ let example = "zh-TW"; }; require_sha = mkNullOrBoolOption { - description = "Whether to require cask(s) to have a checksum."; + description = '' + Whether to require cask(s) to have a checksum. + + Homebrew's default is false. + ''; }; no_quarantine = mkNullOrBoolOption { description = "Whether to disable quarantining of downloads."; @@ -448,8 +458,8 @@ let brewfileLine = "brew ${sCfg.name}" + optionalString (sCfgSubset != { }) ", ${mkBrewfileLineOptionsListString sCfgSubset}" - # We need to handle the `restart_service` option seperately since it can be either bool - # or the string value "changed". + # We need to handle the `restart_service` option seperately since it can be either a bool + # or `:changed` in the Brewfile. + optionalString (sCfg ? restart_service) ( ", restart_service: " + ( if isBool config.restart_service then sCfg.restart_service @@ -468,11 +478,16 @@ let args = mkOption { type = types.nullOr (types.submodule caskArgsOptions); default = null; + visible = "shallow"; # so that options from `homebrew.caskArgs` aren't repeated. + description = '' + Arguments passed to brew install --cask when installing this cask. See + ${mkDocOptionLink "homebrew.caskArgs"} for the available options. + ''; }; greedy = mkNullOrBoolOption { description = '' - Whether to always upgrade auto-updated or unversioned cask to the latest version even if - it's already installed. + Whether to always upgrade this cask regardless of whether it's unversioned or it updates + itself. ''; }; @@ -502,11 +517,29 @@ in options.homebrew = { enable = mkEnableOption '' - configuring your Brewfile, and installing/updating the formulae therein via - the brew bundle command, using nix-darwin. + nix-darwin to manage installing/updating/upgrading Homebrew taps, formulae, + and casks, as well as Mac App Store apps and Docker containers, using Homebrew Bundle. - Note that enabling this option does not install Homebrew. See the Homebrew - website for installation instructions + Note that enabling this option does not install Homebrew, see the Homebrew + website for installation instructions. + + Use the ${mkDocOptionLink "homebrew.brews"}, ${mkDocOptionLink "homebrew.casks"}, + ${mkDocOptionLink "homebrew.masApps"}, and ${mkDocOptionLink "homebrew.whalebrews"} options + to list the Homebrew formulae, casks, Mac App Store apps, and Docker containers you'd like to + install. Use the ${mkDocOptionLink "homebrew.taps"} option, to make additional formula + repositories available to Homebrew. This module uses those options (along with the + ${mkDocOptionLink "homebrew.caskArgs"} options) to generate a Brewfile that + nix-darwin passes to the brew bundle command during + system activation. + + The default configuration of this module prevents Homebrew Bundle from auto-updating Homebrew + and all formulae, as well as upgrading anything that's already installed, so that repeated + invocations of darwin-rebuild switch (without any change to the + configuration) are idempotent. You can modify this behavior using the options under + ${mkDocOptionLink "homebrew.onActivation"}. + + This module also provides a few options for modifying how Homebrew commands behave when + you manually invoke them, under ${mkDocOptionLink "homebrew.global"} ''; brewPrefix = mkOption { @@ -558,7 +591,7 @@ in ] ''; description = '' - Homebrew formula repositories to tap. + List of Homebrew formula repositories to tap. Taps defined as strings, e.g., "user/repo", are a shorthand for: @@ -575,7 +608,10 @@ in require_sha = true; } ''; - description = "Arguments to apply to all ."; + description = '' + Arguments passed to brew install --cask for all casks listed in + ${mkDocOptionLink "homebrew.casks"}. + ''; }; brews = mkOption { @@ -604,9 +640,9 @@ in ] ''; description = '' - Homebrew brews to install. + List of Homebrew formulae to install. - Brews defined as strings, e.g., "imagemagick", are a shorthand for: + Formulae defined as strings, e.g., "imagemagick", are a shorthand for: { name = "imagemagick"; } ''; @@ -635,7 +671,7 @@ in ] ''; description = '' - Homebrew casks to install. + List of Homebrew casks to install. Casks defined as strings, e.g., "google-chrome", are a shorthand for: @@ -656,12 +692,12 @@ in Applications to install from Mac App Store using mas. When this option is used, "mas" is automatically added to - . + ${mkDocOptionLink "homebrew.brews"}. Note that you need to be signed into the Mac App Store for mas to successfully install and upgrade applications, and that unfortunately apps removed from this option will not be uninstalled automatically even if - is set to "uninstall" + ${mkDocOptionLink "homebrew.onActivation.cleanup"} is set to "uninstall" or "zap" (this is currently a limitation of Homebrew Bundle). For more information on mas see: @@ -674,10 +710,10 @@ in default = [ ]; example = [ "whalebrew/wget" ]; description = '' - Docker images to install using whalebrew. + List of Docker images to install using whalebrew. When this option is used, "whalebrew" is automatically added to - . + ${mkDocOptionLink "homebrew.brews"}. For more information on whalebrew see: github.com/whalebrew/whalebrew. @@ -691,7 +727,7 @@ in # 'brew cask install' only if '/usr/libexec/java_home --failfast' fails cask "java" unless system "/usr/libexec/java_home --failfast" ''; - description = "Extra lines to be added verbatim to bottom of the generated Brewfile."; + description = "Extra lines to be added verbatim to the bottom of the generated Brewfile."; }; brewfile = mkInternalOption { @@ -711,7 +747,7 @@ in ]; warnings = [ - (mkIf (options.homebrew.autoUpdate.isDefined || options.homebrew.cleanup.isDefined) "The `homebrew' module no longer upgrades outdated formulae and apps by default during `nix-darwin' activation. To enable upgrading, set `homebrew.onActivation.upgrade = true'.") + (mkIf (options.homebrew.autoUpdate.isDefined || options.homebrew.cleanup.isDefined) "The `homebrew' module no longer upgrades outdated formulae and apps by default during `nix-darwin' system activation. To enable upgrading, set `homebrew.onActivation.upgrade = true'.") ]; homebrew.brews =