developer docs

[jmhodges]

I was trying to help debug a few things in #4145 but ran into a bunch of undocumented stuff. Or, at least, things I couldn't find by reading the Contribution guidelines and google.

Things that seem undocumented:

• HOMEBREW_DEVELOPER
• how to install the dev-cmd tools (and that brew linkage came from them)
• how bottles are created and if you should include them in the recipe when upgrading
• --env=std for building with -g for debug symbols (which actually didn't work for me)

I'm sure some of these are documented somewhere but they were not easily findable by searching for "homebrew contribution" or "homebrew developer" and googling about how to handle bottles and such.

It might be nice to have a more technical guide for being a homebrew contributor and one for getting debugging symbols out of C packages (in general) since there's a lot of CFLAGS rewriting.

[ilovezfs]

HOMEBREW_DEVELOPER

See Homebrew/brew#881.

how to install the dev-cmd tools

It's just another tap and none of them are required for most users. The main developer commands are in the brew repo already.

how bottles are created and if you should include them in the recipe when upgrading

https://github.com/Homebrew/homebrew-core/blob/master/.github/CONTRIBUTING.md

"leave the bottle as-is" is stated twice

-env=std for building with -g for debug symbols (which actually didn't work for me)

Feel free to appeal https://github.com/Homebrew/brew-evolution/pull/7.

[DomT4]

Perhaps worth a note that we borderline don't support --env=std where it isn't the default in the formula. If people choose to use it, and stuff breaks, there's not going to be a giant rush to help resolve that breakage. More or less opposed to any documentation that could deliberately or involuntarily drive more people to routinely use --env=std.

It might be nice to have a more technical guide for being a homebrew contributor

Almost nobody reads it because of its length, but the Formula Cookbook goes into a chunk of detail. It's not completely up-to-date, but it's not far off. There's also some API documentation here.

Feel free to appeal Homebrew/brew-evolution#7.

Ref: Homebrew/legacy-homebrew#42053 as well.

[ilovezfs]

Also note thatsystem "xcrun", "make" in the formula will avoid the argument refurbishment by superenv that occurs whenever you use make. So that is an alternative to --env=std if avoiding argument refurbishment is the specific goal.

[MikeMcQuaid]

HOMEBREW_DEVELOPER
how to install the dev-cmd tools (and that brew linkage came from them)

These should be at least partially addressed by Homebrew/brew#881.

[MikeMcQuaid]

(which was just merged)