mirrors/nix-darwin
mirrors/nix-darwin
1
0
Fork 0
mirror of https://github.com/LnL7/nix-darwin.git synced 2025-03-17 05:48:18 +00:00
Code Activity

Improve documentation of homebrew module

Browse source
This commit is contained in:
Malo Bourgon 2022-08-24 17:35:42 -07:00
parent 7710d1d7d6
commit 2ddebb3189
1 changed files with 63 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

90
modules/homebrew.nix
View file

@ -70,14 +70,15 @@ let
example = "uninstall"; example = "uninstall";
description = '' description = ''
This option manages what happens to formulae installed by Homebrew, that aren't present in This option manages what happens to formulae installed by Homebrew, that aren't present in
the Brewfile generated by this module, during <command>nix-darwin</command> activation. the Brewfile generated by this module, during <command>nix-darwin</command> system
activation.
When set to <literal>"none"</literal> (the default), formulae not present in the generated When set to <literal>"none"</literal> (the default), formulae not present in the generated
Brewfile are left installed. Brewfile are left installed.
When set to <literal>"uninstall"</literal>, <command>nix-darwin</command> invokes When set to <literal>"uninstall"</literal>, <command>nix-darwin</command> invokes
<command>brew bundle [install]</command> with the <command>--cleanup</command> flag. This <command>brew bundle [install]</command> with the <command>--cleanup</command> flag. This
uninstalls all formulae not listed in generate Brewfile, i.e., uninstalls all formulae not listed in generated Brewfile, i.e.,
<command>brew uninstall</command> is run for those formulae. <command>brew uninstall</command> is run for those formulae.
When set to <literal>"zap"</literal>, <command>nix-darwin</command> invokes When set to <literal>"zap"</literal>, <command>nix-darwin</command> invokes
@ -96,10 +97,14 @@ let
default = false; default = false;
description = '' description = ''
Whether to enable Homebrew to auto-update itself and all formulae during Whether to enable Homebrew to auto-update itself and all formulae during
<command>nix-darwin</command> activation. The default is <literal>false</literal> so that <command>nix-darwin</command> system activation. The default is <literal>false</literal>
repeated invocations of <command>darwin-rebuild switch</command> are idempotent. so that repeated invocations of <command>darwin-rebuild switch</command> are idempotent.
Note that Homebrew auto-updates when it's been more then 5 minutes since it last updated. 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 { upgrade = mkOption {
@ -107,8 +112,8 @@ let
default = false; default = false;
description = '' description = ''
Whether to enable Homebrew to upgrade outdated formulae and Mac App Store apps during Whether to enable Homebrew to upgrade outdated formulae and Mac App Store apps during
<command>nix-darwin</command> activation. The default is <literal>false</literal> so <command>nix-darwin</command> system activation. The default is <literal>false</literal>
that repeated invocations of <command>darwin-rebuild switch</command> are idempotent. so that repeated invocations of <command>darwin-rebuild switch</command> are idempotent.
''; '';
}; };
@ -330,7 +335,8 @@ let
description = '' description = ''
Target location for Audio Unit Plugins. Target location for Audio Unit Plugins.
Homebrew's default is <filename class='directory'>~/Library/Audio/Plug-Ins/Components</filename>. Homebrew's default is
<filename class='directory'>~/Library/Audio/Plug-Ins/Components</filename>.
''; '';
}; };
vst_plugindir = mkNullOrStrOption { vst_plugindir = mkNullOrStrOption {
@ -363,7 +369,11 @@ let
example = "zh-TW"; example = "zh-TW";
}; };
require_sha = mkNullOrBoolOption { 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 <literal>false</literal>.
'';
}; };
no_quarantine = mkNullOrBoolOption { no_quarantine = mkNullOrBoolOption {
description = "Whether to disable quarantining of downloads."; description = "Whether to disable quarantining of downloads.";
@ -448,8 +458,8 @@ let
brewfileLine = brewfileLine =
"brew ${sCfg.name}" "brew ${sCfg.name}"
+ optionalString (sCfgSubset != { }) ", ${mkBrewfileLineOptionsListString sCfgSubset}" + optionalString (sCfgSubset != { }) ", ${mkBrewfileLineOptionsListString sCfgSubset}"
# We need to handle the `restart_service` option seperately since it can be either bool # We need to handle the `restart_service` option seperately since it can be either a bool
# or the string value "changed". # or `:changed` in the Brewfile.
+ optionalString (sCfg ? restart_service) ( + optionalString (sCfg ? restart_service) (
", restart_service: " + ( ", restart_service: " + (
if isBool config.restart_service then sCfg.restart_service if isBool config.restart_service then sCfg.restart_service
@ -468,11 +478,16 @@ let
args = mkOption { args = mkOption {
type = types.nullOr (types.submodule caskArgsOptions); type = types.nullOr (types.submodule caskArgsOptions);
default = null; default = null;
visible = "shallow"; # so that options from `homebrew.caskArgs` aren't repeated.
description = ''
Arguments passed to <command>brew install --cask</command> when installing this cask. See
${mkDocOptionLink "homebrew.caskArgs"} for the available options.
'';
}; };
greedy = mkNullOrBoolOption { greedy = mkNullOrBoolOption {
description = '' description = ''
Whether to always upgrade auto-updated or unversioned cask to the latest version even if Whether to always upgrade this cask regardless of whether it's unversioned or it updates
it's already installed. itself.
''; '';
}; };
@ -502,11 +517,29 @@ in
options.homebrew = { options.homebrew = {
enable = mkEnableOption '' enable = mkEnableOption ''
configuring your Brewfile, and installing/updating the formulae therein via <command>nix-darwin</command> to manage installing/updating/upgrading Homebrew taps, formulae,
the <command>brew bundle</command> command, using <command>nix-darwin</command>. 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 Note that enabling this option does not install Homebrew, see the Homebrew
<link xlink:href="https://brew.sh">website</link> for installation instructions <link xlink:href="https://brew.sh">website</link> 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
<command>nix-darwin</command> passes to the <command>brew bundle</command> 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 <command>darwin-rebuild switch</command> (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 { brewPrefix = mkOption {
@ -558,7 +591,7 @@ in
] ]
''; '';
description = '' description = ''
Homebrew formula repositories to tap. List of Homebrew formula repositories to tap.
Taps defined as strings, e.g., <literal>"user/repo"</literal>, are a shorthand for: Taps defined as strings, e.g., <literal>"user/repo"</literal>, are a shorthand for:
@ -575,7 +608,10 @@ in
require_sha = true; require_sha = true;
} }
''; '';
description = "Arguments to apply to all <option>homebrew.casks</option>."; description = ''
Arguments passed to <command>brew install --cask</command> for all casks listed in
${mkDocOptionLink "homebrew.casks"}.
'';
}; };
brews = mkOption { brews = mkOption {
@ -604,9 +640,9 @@ in
] ]
''; '';
description = '' description = ''
Homebrew brews to install. List of Homebrew formulae to install.
Brews defined as strings, e.g., <literal>"imagemagick"</literal>, are a shorthand for: Formulae defined as strings, e.g., <literal>"imagemagick"</literal>, are a shorthand for:
<code>{ name = "imagemagick"; }</code> <code>{ name = "imagemagick"; }</code>
''; '';
@ -635,7 +671,7 @@ in
] ]
''; '';
description = '' description = ''
Homebrew casks to install. List of Homebrew casks to install.
Casks defined as strings, e.g., <literal>"google-chrome"</literal>, are a shorthand for: Casks defined as strings, e.g., <literal>"google-chrome"</literal>, are a shorthand for:
@ -656,12 +692,12 @@ in
Applications to install from Mac App Store using <command>mas</command>. Applications to install from Mac App Store using <command>mas</command>.
When this option is used, <literal>"mas"</literal> is automatically added to When this option is used, <literal>"mas"</literal> is automatically added to
<option>homebrew.brews</option>. ${mkDocOptionLink "homebrew.brews"}.
Note that you need to be signed into the Mac App Store for <command>mas</command> to Note that you need to be signed into the Mac App Store for <command>mas</command> to
successfully install and upgrade applications, and that unfortunately apps removed from this successfully install and upgrade applications, and that unfortunately apps removed from this
option will not be uninstalled automatically even if option will not be uninstalled automatically even if
<option>homebrew.onActivation.cleanup</option> is set to <literal>"uninstall"</literal> ${mkDocOptionLink "homebrew.onActivation.cleanup"} is set to <literal>"uninstall"</literal>
or <literal>"zap"</literal> (this is currently a limitation of Homebrew Bundle). or <literal>"zap"</literal> (this is currently a limitation of Homebrew Bundle).
For more information on <command>mas</command> see: For more information on <command>mas</command> see:
@ -674,10 +710,10 @@ in
default = [ ]; default = [ ];
example = [ "whalebrew/wget" ]; example = [ "whalebrew/wget" ];
description = '' description = ''
Docker images to install using <command>whalebrew</command>. List of Docker images to install using <command>whalebrew</command>.
When this option is used, <literal>"whalebrew"</literal> is automatically added to When this option is used, <literal>"whalebrew"</literal> is automatically added to
<option>homebrew.brews</option>. ${mkDocOptionLink "homebrew.brews"}.
For more information on <command>whalebrew</command> see: For more information on <command>whalebrew</command> see:
<link xlink:href="https://github.com/whalebrew/whalebrew">github.com/whalebrew/whalebrew</link>. <link xlink:href="https://github.com/whalebrew/whalebrew">github.com/whalebrew/whalebrew</link>.
@ -691,7 +727,7 @@ in
# 'brew cask install' only if '/usr/libexec/java_home --failfast' fails # 'brew cask install' only if '/usr/libexec/java_home --failfast' fails
cask "java" unless system "/usr/libexec/java_home --failfast" 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 { brewfile = mkInternalOption {
@ -711,7 +747,7 @@ in
]; ];
warnings = [ 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 = homebrew.brews =