chriskilding / homebrew-source Goto Github PK

Multiple shells may be installed on a machine. (For example, on macOS Zsh is the default, with legacy Bash also available.)

In addition, a brew formula can potentially install different kinds of shell function scripts, e.g. with the fish_function.install or zsh_function.install directives.

Some formulae may even use plain install to put a sourceable script in an unusual place (e.g. pyenv is installed in libexec).

We need to make sure that brew source sensibly handles sourcing shell functions when multiple shells are installed.

The question is, what does the correct behaviour look like?

• Should it only source scripts in the current shell? (I.e. if you run brew source in Zsh -> only source scripts known to be for Zsh.) Or should it add source directives for every installed shell?
• How can we determine which scripts in the formula are meant for a particular shell?

brew source could have the option shell functions in a non-persistent way, so that the user can test them without committing to make changes to their shell profile:

$ brew source --transient foo

<functions available in current shell>
<will be lost when shell is reloaded>

Once the Formula DSL allows formula authors to declare source-able shell functions, this opens the door to integrations with other brew commands...

The brew doctor command could note the existence of formulae whose shell functions have not been sourced yet, and tell you how to fix this:

$ brew doctor
The following installed formulae contain shell functions that are not sourced in your current shell profile:
foo bar baz

Run 'brew source <formula>' to fix this.

At the moment we append sourcing statements to the rc file using the source syntax, i.e.

source /path/to/functions

While the POSIX standard is the 'dot' syntax:

. /path/to/functions

Should we use the dot syntax instead?

Allow source to handle multiple formulae at a time with:

brew source <formula1> <formula2> ...

In a new setup, a user may not have a shell profile e.g. ~/.zshrc yet.

brew source should handle this situation and create the file for the user.

Allow the user to automatically remove a formula's source statements (that we added) from their shell profile:

brew unsource <formula>

Potentially this could be hooked onto brew uninstall as an option as well. This would allow formulae to automatically clean up after themselves.

Currently Brew formulae do not have a way to declare that they contain shell functions that need sourcing.

For this Brew extension to work, we must add a way to do this to the Formula DSL.

(Once solved, we will have a functional first version of the extension.)

Possible approaches

Append source option to one of the install directives

class Foo < Formula

    def install
        zsh_function.install "foo", { source: true }
        zsh_function.install "bar", { source: true }
    end
end

Variations on the syntax are possible, for example:

zsh_function.install "foo", [:source]

zsh_function.install "foo", options: [:source]

Declare source-able functions in a separate attribute

Downside: requires duplication of the shell function script's name. This is partially alleviated by using path helper functions e.g. zsh_function but it is still a duplication.

class Foo < Formula

    source_shell_functions zsh_function("foo"), zsh_function("bar")

    def install
        zsh_function.install "foo"
        zsh_function.install "bar"
    end
end