Homebrew formula: `option` description generation

[tzudot]

Earlier today, when I was adding an option to a formula, I had noticed that description for an option is generated by Homebrew, only if defined after depends_on. But according to brew audit --strict <formula>, an option should precede depends_on.

If I place an option before depends_on, a blank description is shown. e.g.

option "with-gsasl"
depends_on "gsasl" => :optional

$ brew info formula

==> Dependencies
Build: xz ✔, pkg-config ✔
Required: openssl ✔
Optional: gsasl ✔
==> Options
--with-gsasl

$ brew config

HOMEBREW_VERSION: 0.9.5
ORIGIN: https://github.com/Homebrew/homebrew.git
HEAD: 7550c35192c0b09f6b1477d9f81479d0e0eacc32
Last commit: 3 hours ago
HOMEBREW_PREFIX: /usr/local
HOMEBREW_CELLAR: /usr/local/Cellar
HOMEBREW_BOTTLE_DOMAIN: https://homebrew.bintray.com
CPU: quad-core 64-bit haswell
OS X: 10.10.4-x86_64
Xcode: 6.4
CLT: 6.4.0.0.1.1435007323
Clang: 6.1 build 602
X11: N/A
System Ruby: 2.0.0-p481
Perl: /usr/bin/perl
Python: /usr/local/bin/python => /usr/local/Cellar/python/2.7.10_2/Frameworks/Python.framework/Versions/2.7/bin/python2.7
Ruby: /opt/rubies/ruby-2.2.2/bin/ruby
Java: 1.7.0_75

@bfontaine any thoughts ?

[DomT4]

When you manually specify an option it overrides the generic text we insert, which is why you're seeing a blank line there.

depends_on "xyz" => :optional generates the automated wording:

--with-mp3gain
    Build with mp3gain support
--with-musepack
    Build with musepack support
--with-opus
    Build with opus support

But by creating an option you can override that:

option "with-mp3gain", "Dogs are cooler than cats"

Equals

--with-mp3gain
    Dogs are cooler than cats

Unless you want custom wording you don't need to add an option as well as the depends_on "xyz" => :optional line.

[bfontaine]

@DomT4 said everything :smile:

[tzudot]

@DomT4 thank you for explaining that in detail. I guess, I didn't make myself clear earlier.

Let me explain again,

Case 1: Homebrew generates a description for option. $ brew edit msmtp

...
depends_on "gsasl" => :optional
option "with-gsasl"
...

$ brew info msmtp

==> Options
--with-gsasl
        Build with gsasl support

But brew audit --strict formula generates an error:

==> audit problems
msmtp:
 * `option` (line 16) should be put before `depends_on` (line 13)

Case 2: Homebrew does not generate a description for option. $ brew edit msmtp

...
option "with-gsasl"
depends_on "gsasl" => :optional
...

$ brew info msmtp

==> Options
--with-gsasl

I just now checked this locally on my laptop by deliberately putting an option, without custom description, before depends_on.

[bfontaine]

@tzudot The audit error is because there’s an option after depends_on. If there are options in a formula, they must be put before any depends_on.

[DomT4]

Yeah, as @bfontaine says. Essentially, if it helps, depends_on "xyz" => :optional automatically generates the option wording, so unless you want new option wording you don't need to generate your own option at all.

[tzudot]

The point I am trying to make is, depends_on "xyz" => :optional does not automatically generate the option wording, if present after option.

Anyway, this is not mission critical. I'll try to debug this over the weekend.

[DomT4]

Yes, that's because the option overrides the automated wording. The second you add an option line which is the same as the optional dependency, we throw the automated wording out of the window. What you're seeing is entirely deliberate behaviour.