Doc - review workstation set up instructions (macos specific)

[insuhpak]

Workstation set up specific feedback in this ticket.

Workstation Setup

* for "Installation instructions: openssl, readline, sqlite3, xz, zlib", maybe include the "brew update" command before homebrew usage

* minor errors popped up but resolvable by following the homebrew instructions:

    ==> Installing python@3.9
    ==> Pouring python@3.9--3.9.17.monterey.bottle.1.tar.gz
    Error: The `brew link` step did not complete successfully
    The formula built, but is not symlinked into /usr/local
    Could not symlink bin/2to3-3.9
    Target /usr/local/bin/2to3-3.9
    already exists. You may want to remove it:
      rm '/usr/local/bin/2to3-3.9'

    To force the link and overwrite all conflicting files:
      brew link --overwrite python@3.9

    To list all files that would be deleted:
      brew link --overwrite --dry-run python@3.9

    [...]

    ==> Pouring python@3.11--3.11.4.monterey.bottle.1.tar.gz
    Error: The `brew link` step did not complete successfully
    The formula built, but is not symlinked into /usr/local
    Could not symlink bin/2to3
    Target /usr/local/bin/2to3
    already exists. You may want to remove it:
      rm '/usr/local/bin/2to3'

    To force the link and overwrite all conflicting files:
      brew link --overwrite python@3.11

    To list all files that would be deleted:
      brew link --overwrite --dry-run python@3.11

Install Python using pyenv

* In instructions on running the install through VSCode, add a brief instruction to create new file/window and select View > Terminal

* Updating $PATH: add an "echo $PATH" statement to verify

* pyenv versions command returns the following (assuming it's ok; it's actually helpful to see the .pyenv directory path)
    * system (set by /Users/psbauman/.pyenv/version)
      3.9.13

    * I did switch to 3.9.13

* we typically use .bash_profile for PATH, so I added the eval "$(pyenv init --path)" there

* you can load .bashrc into session without closing window with:
> . ~/.bashrc

[insuhpak]

I am going through and evaluating the workstation setup documentation from a macos perspective since I am on mac now. These notes are from installation on a brand new mac (nothing has been installed).

Adding additional notes/edits to this ticket:

• Sakshi set up her mac workstation a couple weeks ago and has issues installing pyenv via Homebrew due to needing admin access. I was able to replicate this issue:

  ikpak@BAP-ikpak ~ % /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" 
  ==> Checking for `sudo` access (which may request your password)...
  Sorry, user ikpak may not run sudo on BAP-ikpak.
  Need sudo access on macOS (e.g. the user ikpak needs to be an Administrator)!

  Also, I think current Homebrew installation instructions are bash-specific, not for zsh. (I am running zsh since it is macos default.)

Perhaps, for dbt workstation setup we should tell users to use bash. Since windows can only use Git Bash that is offered through vscode.

• If users cannot install Homebrew, then they can install pyenv manually from the github repo. We should add pyenv manual installation instructions.

Note, users still need to install xcode.

ikpak@BAP-ikpak .pyenv % git clone https://github.com/pyenv/pyenv.git ~/.pyenv
xcode-select: note: no developer tools were found at '/Applications/Xcode.app', requesting install. Choose an option in the dialog to download the command line developer tools.

Users will now be able to install pyenv, however they cannot install python completely. Users need xz (i.e. the missing lzma lib).

ikpak@BAP-ikpak ~ % pyenv install 3.9.13
Downloading openssl-1.1.1n.tar.gz...
-> https://www.openssl.org/source/openssl-1.1.1n.tar.gz
Installing openssl-1.1.1n...
Installed openssl-1.1.1n to /Users/ikpak/.pyenv/versions/3.9.13
Downloading readline-8.1.tar.gz...
-> https://ftpmirror.gnu.org/readline/readline-8.1.tar.gz
Installing readline-8.1...
Installed readline-8.1 to /Users/ikpak/.pyenv/versions/3.9.13
Downloading Python-3.9.13.tar.xz...
-> https://www.python.org/ftp/python/3.9.13/Python-3.9.13.tar.xz
Installing Python-3.9.13...
python-build: use zlib from xcode sdk
Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/Users/ikpak/.pyenv/versions/3.9.13/lib/python3.9/lzma.py", line 27, in <module>
    from _lzma import *
ModuleNotFoundError: No module named '_lzma'
WARNING: The Python lzma extension was not compiled. Missing the lzma lib?
Installed Python-3.9.13 to /Users/ikpak/.pyenv/versions/3.9.13

Users can install this using pip. <-- this doesn't work. Not going to resolve this error until a specific issue arises.

**Update: It does not seem like users need to install the module _lzma. After python 3.3 all installations include the module lzma, so I am not 100% sure why this error is showing. There are discussions about this issue online. I also confirmed that python scripts run and dbt runs as it should.

• Mac instructions to activate venv is missing 'source'

[insuhpak]

@tgraham-ucsc BTW, officially switched to mac. I will be updating the documentation with the previous feedback and anything new I encounter myself.

[tgraham-ucsc]

@insuhpak welcome!! 🍎 😄 🍏

The one source I found that finally got me to onboard with python environments is Installing pyenv on macOS for Zsh using Homebrew

Are you using bash or zsh ? I thought Mac changed their default to zsh a while back

[insuhpak]

@tgraham-ucsc I am using zsh and yes it is the default!

I am trying to go a different route than Homebrew only because users need an admin account to install Homebrew. And I want to see if it is possible to successfully complete the setup without Homebrew. It would be ideal if users can setup without needing someone with admin access.

But Homebrew does make it simple.

[insuhpak]

Additional details regarding Paul's comment on .bash-profile.

Should we be recommending .bashrc, .zshrc, .bash-profile, .zprofile, .envs?? others??

Some resources:

• https://shreevatsa.wordpress.com/2008/03/30/zshbash-startup-files-loading-order-bashrc-zshrc-etc/
• https://www.reddit.com/r/zsh/comments/e882c4/what_is_the_difference_between_zshrc_and_zprofile/
• https://www.reddit.com/r/bash/comments/11osjrn/what_exactly_is_the_difference_between_an/#:~:text=Non%2Dinteractive%20basically%20means%20invoking,actual%20user%20typing%20commands%20interactively.

[insuhpak]

This issue will be included in issue #48