doc: add note about brew doctor #18070

1. 
   givanse commented at 5:14 am on February 5, 2020: contributor

   A trivial documentation update.

   When I was following the build steps for mac, I had some errors installing the dependencies. After searching on the Internet, and correcting the errors, I found that brew doctor had all the answers I needed. Could have skipped the Internet searches all together.

2. fanquake added the label Docs on Feb 5, 2020
3. givanse renamed this:
   [doc] add note about `brew doctor`
   doc: add note about `brew doctor`
   on Feb 5, 2020
4. 
   fanquake commented at 5:22 am on February 5, 2020: member

   I’m not sure this needs to be in our documentation, as it’s general to brew.
5. 
   laanwj commented at 1:03 pm on February 5, 2020: member

   Thanks for contributing, but in addition to what @fanquake says I think this is not specific enough for documentation “some issues” “some ideas”. You might want to add what kind of issues, and what kind of suggestions.
6. 
   givanse commented at 4:21 pm on February 5, 2020: contributor

   A specific problem I had, that seems general enough, was that I was missing a couple of folders in my system. The original error I got was:

   0==> Pouring python-3.7.6_1.catalina.bottle.tar.gz
   1Error: An unexpected error occurred during the `brew link` step
   2The formula built, but is not symlinked into /usr/local
   3Permission denied @ dir_s_mkdir - /usr/local/Frameworks
   4Error: Permission denied @ dir_s_mkdir - /usr/local/Frameworks
   

   In hindsight, it does show an issue with trying to create one of the folders. I didn’t catch that initially.

   The fix is:

   0sudo mkdir -p /usr/local/Frameworks /usr/local/sbin
   1sudo chown -R $(whoami) /usr/local/Frameworks /usr/local/sbin
   

   It seems like anyone who has never installed some of the dependencies before will run into this hiccup. Would it be worth to preemptively ask everyone to:

   0sudo mkdir ...
   1sudo chown ...
   2brew install ...
   

   ?

7. 
   dongcarl commented at 4:40 pm on February 5, 2020: member

   I understand that the initial setup of Homebrew can be confusing to some… Here’s an alternative idea: link to Homebrew’s troubleshooting page, which will be more updated on the latest best practices.
8. doc: link to homebrew's troubleshooting page 63ce882760
9. givanse force-pushed on Feb 6, 2020
10. fanquake approved
11. 
    fanquake commented at 12:23 pm on February 20, 2020: member

    ACK 63ce882760e1ceb4114c716851aedaf911ebb93b - a link to the troubleshooting page seems fine. I wouldn’t really want our README to have anything more specific than that.
12. fanquake merged this on Feb 20, 2020
13. fanquake closed this on Feb 20, 2020

    ---

14. sidhujag referenced this in commit c801245505 on Feb 22, 2020
15. givanse deleted the branch on Sep 6, 2020
16. sidhujag referenced this in commit 18742ee916 on Nov 10, 2020
17. DrahtBot locked this on Feb 15, 2022

Contributors
givanse fanquake laanwj dongcarl

Labels
Docs