randomdsdevel / brew Goto Github PK

(Notes:

1. This issue may well work better as one that's explicitly meant only for my personal use and hence scoped locally only to this repository fork of mine, as opposed to one meant for upstreaming. Consider doing whatever refactoring ends up being needed to change this issue's text accordingly.
2. Either way, this issue's format and style are based on that/those from what may well be an earlier version of upstream's issue template for feature requests. Consider updating this issue's format and style to update and bring it in line with upstream's current format and style.)

Main Issue Body (Feature Request)

Please replace this section with:

• A detailed description of your proposed feature:

       When troubleshooting an issue with Homebrew or one of its various and sundry available formulas, the tool's users may occasionally wish to understand how it's behaving during execution given any particular invocation. Some useful techniques to do this are those of step-into debugging. Users should be able to tell Homebrew to execute itself within the context of a suitable Ruby debugging tool.
       An oft-recommended tool for doing such debugging in Ruby code was pry-byebug. 'byebug,' the tool that pry-byebug extended Pry with capabilities from, has, however, long since become unmaintained. A (fairly straightforward) replacement likely exists, but I haven't yet done enough research to find out yet.

• The motivation for the feature:

       Originally, I yearned for this functionality while debugging a particular formula (vim, when installed --with-client-server when its python dependency is installed --with-tcl-tk; I'd reference the associated issue here, but that would spam it with an unneeded in-thread GitHub notification.) It occurred to me while hacking my way around doing this without the feature proposed here that the functionality in question could prove useful not only in my current situation, but also in an untold future number of debugging scenarios involving Homebrew itself or one of the formulas directing its actions; people troubleshooting problems of any of this sort in the past would likely also have loved to have access to such tooling then, too.

• How the feature would be relevant to at least 90% of Homebrew users (if it's not: do not open a feature request:)

       Any effort to ease understanding, and thus maintainability, of a software project should find a warm welcome among its maintainers and contributors. The feature proposed/requested here would go a non-trivial length of the way towards enabling Homebrew internals and formula developers to better understand the package manager's behavior when it fails to match their expectations.

  (N. b.: This text could likely be improved substantially, but I'm leaving it as is for now.)

• What alternatives to the feature you have considered:

       Alternatively, the debugging functionality proposed here could instead not be implemented. Homebrew internals and formula developers would then continue to temporarily insert ad-hoc code for tracing execution into brew's implementation as they do now. This approach, however, brings along with it at least the following few problematic pain points:

  • Anybody wishing to debug a 'require' statement to see why it's not finding something will need to step over, not into, its implementation's uses of 'RUBYGEMS_ACTIVATION_MONITOR;' trying to introspect them quickly leads to deadlock and a crashed Pry session.

  • Homebrew's internal implementation easily spawns multiple processes, each with their own separate entry point within the project's source code. Pry needs a separate in-code invocation for each of these entry points; otherwise, entering each new one of these beyond the one through which the tool was first brought to bear either allows execution past them to continue unhindered by its introspection capabilities or causes the user's Pry session to hang while attempting to do that. Examples of such entry points include, relative to Homebrew's repository root:

    • FormulaInstaller#build (currently starting on line 718 of 'Library/Homebrew/formula_installer.rb' as of this writing.) This uses:

      • 'Utils.safe_fork,' regardless.

      • 'Sandbox.exec' if using the build sandbox, as is the default. (Disable-able using brew's '--no-sandbox' argument or 'HOMEBREW_NO_SANDBOX' environment variable as a workaround.) (Note that this is especially problematic, as the sandbox used for this operation has no provisions in place for Pry to run without running up against its restrictions.)

        CAUTION!

             Upstream has begun considering deprecating and obsoleting/removing both --no-sandbox' argument and its 'HOMEBREW_NO_SANDBOX' environment variable. (Note: I need to go back and find where this has been discussed.) This will make it impossible, or at least extremely difficult, to debug any potential issues with the sandbox, but upstream considers its build and process sandboxing functionality stable enough that it won't need any further debugging regardless of how true that turns out to be in the future.

  I'll document more examples of such trouble as I remember or run into them.

Other alternatives may well exist but have not yet been considered for addition to this issue documentation.

Future Extensions

     The proposed functionality could, in future, be extended to allow users to specify a particular section in Homebrew's code from whence to start tracing brew's execution, thereby avoiding any overhead incurred by stepping through the preceding code manually. This or any other such further improvement would, however, likely involve modifying `breathe program's source to include additional complexity beyond what would be necessary to implement what I've initially proposed here and is thus not put forth for consideration at the current time.

     (Note that I didn't submit this issue upstream because I've already been asked to create a pull request for this instead.)

     Per this comment by Mike McQuaid in upstream issue Homebrew#16725:

I think it'd be worth trying to be more consistent here and use this as an opportunity to drop some older macOS versions support entirely.

upstream may consider dropping support for OS X v10.11.x 'El Capitan' in the near future. This is pretty much entirely on me for getting myself stuck in development purgatory regarding my local development hardware environment over multiple years, but:

• My last known partly good Mac development environment is the ailing family loaner mid-2007 Aluminum Intel iMac that I still haven't restored my personal external boot drive for it from my last Time Machine backup of it.
• My stalled attempt at creating an HP ZBook 17 G6 Hackintosh to migrate to is also still stuck in its own development purgatory while I continue to wrestle with its replacement graphics card, which I still need to get modded to restore its OEM-removed EEPROM chip and a couple missing surrounding resistors but have yet to do so. (…Ugh, low vision and a lack of timely local and/or skilled help.)

Also:

• I still have several outstanding package build issues, mostly only documented locally, that remain unresolved even after all this time (non-trivially due to the machine still being down.)
• Portage-Brew (initial wish list documentation still here) also still remains stuck in its own development purgatory and hence isn't anywhere near ready yet.

     @gromgit currently maintains a fork of Homebrew Core for macOS Mojave v10.14.x, but I have no idea if he'd be willing to:

• do the same for El Capiran or
• also maintain patches against upstream 'brew' itself for El Capitan support if/as needed.

     (Aside: …If I could find someone to offload some of this work off onto who'd be willing to take it on, I'd definitely be open to taking them up on that offer. No potential interest has yet been raised, however, either locally or online. Also, package manager and build system code, especially for system package managers and systems programming languages, can be…disheartening/overwhelming, particularly for less-experienced developers like me. Avoiding it this time around could deprive me of a development learning experience, though. Additionally, I've already had some non-trivial thoughts on how it'd be nice to have some of the code structured if I were indeed to be the one to put the refactoring work in on it, even though this was only starting from brew's entry point and not having gotten very far past that at all, and the thought/prospect of code ownership remains…non-trivially tempting despite the requisite investment of time that I currently still lack.)

Potential Temporary Stopgap Path/Progress Route Forward

     Once I – finally! – have the old machine back up and running again:

1. Dump or manually document what Homebrew packages I currently have installed for explicit end-user use.

        Dumping them using an automated method could prove difficult or impossible, however, as:

   • I installed, upgraded, or re-installed some formulas' formula dependencies manually, because I (originally) did so either:

     • with options, back when those were still a thing, or
     • to single-step through the formula build dependency graph while troubleshooting formula build issues as they arose.

   This left some packages marked as installed on request when they should've been installed as dependencies. 'brew leaves --installed-on-request' and 'brew bundle dump' therefore won't report a proper formula list back to me. (There isn't a 'brew bundle dump --leaves' for help with this scenario yet, either, at least not as far as I know/am aware.) Homebrew has:

   • no equivalent to Gentoo Portage emerge's '--oneshot,' which I've only discovered/encountered much more recently after studying to play around with/use Gentoo inside Windows Subsystem for Linux 2.
   • no easy way to switch an installed package from being marked as having been installed on request to being marked as having been installed as a dependency. I could edit keg tabs, I suppose, but that's error-prone, and I could easily miss something.

2. Switch to another macOS package manager like:

   • MacPorts or
   • Gentoo Prefix,

   at least temporarily, referring back to the list of packages compiled previously.

        Homebrew's formula package definition syntax is by far the nicest I've seen and easiest to work with as a contributor, though, so I'll miss it dearly.