From 70d5e7bb3df0f7d4328cd8f2534e6490feb0b8c9 Mon Sep 17 00:00:00 2001
From: Anthony Sansone <atsansone@users.noreply.github.com>
Date: Mon, 22 Jan 2024 16:44:55 -0600
Subject: [PATCH] Adds PATH for macOS (#10031)

Adds PATH instructions for macOS.
Fixes #9351
Fixes #10015
Fixes #10040
Fixes #10036

---------

Co-authored-by: John Ryan <ryjohn@google.com>
---
 _config.yml                                   |  7 +-
 src/_includes/docs/install/compiler/xcode.md  | 33 +++++----
 .../docs/install/devices/ios-simulator.md     |  5 +-
 src/_includes/docs/install/flutter-sdk.md     |  6 +-
 .../docs/install/flutter/download.md          | 21 ++++--
 src/_includes/docs/install/flutter/vscode.md  | 22 ++++--
 .../flutter-sdk/flutter-doctor-precedence.md  |  3 +
 .../docs/install/reqs/macos/apple-silicon.md  | 19 ++---
 src/_includes/docs/install/reqs/macos/base.md | 25 +++++--
 .../docs/install/reqs/macos/set-path.md       | 33 +++++++++
 .../docs/install/reqs/macos/software.md       | 69 +++++++++----------
 .../docs/install/reqs/macos/zsh-config.md     | 46 +++++++++++++
 .../docs/install/reqs/windows/base.md         |  2 +
 13 files changed, 202 insertions(+), 89 deletions(-)
 create mode 100644 src/_includes/docs/install/reqs/flutter-sdk/flutter-doctor-precedence.md
 create mode 100644 src/_includes/docs/install/reqs/macos/set-path.md
 create mode 100644 src/_includes/docs/install/reqs/macos/zsh-config.md

diff --git a/_config.yml b/_config.yml
index f8709d3c1af..6db0db5998e 100644
--- a/_config.yml
+++ b/_config.yml
@@ -64,9 +64,12 @@ appmin:
   intellij_idea: '2022.3'
   android_sdk: 19
   powershell: 5.0
+  xcode: '14'
+  ios: '16'
+  cocoapods: '1.9'
 devmin:
   windows: '64-bit version of Microsoft Windows 10'
-  macos: '10.14 (Mojave)'
+  macos: '10.15 (Catalina)'
   linux: 
     debian: 10
     ubuntu: '18.04 LTS'
@@ -207,7 +210,7 @@ alert:
     <aside class="alert alert-info" role="alert" markdown="1">
     **Bonus questions!**
   important: >-
-    <aside class="alert alert-warning" role="alert" markdown="1">
+    <aside class="alert alert-warning alert-icon" role="alert" markdown="1">
     <i class="material-icons" aria-hidden="true">error</i> **Important:**
   info: >-
     <aside class="alert alert-info" role="alert" markdown="1">
diff --git a/src/_includes/docs/install/compiler/xcode.md b/src/_includes/docs/install/compiler/xcode.md
index 7d5095ea27b..f6244f0621f 100644
--- a/src/_includes/docs/install/compiler/xcode.md
+++ b/src/_includes/docs/install/compiler/xcode.md
@@ -8,7 +8,7 @@
 
 To develop Flutter apps for {{os}}, install Xcode to compile to native bytecode.
 
-1. To configure the Xcode command-line tools to use the installed version,
+1. To configure the command-line tools to use the installed version of Xcode,
    run the following commands.
 
     ```terminal
@@ -74,31 +74,30 @@ With Xcode, you can run Flutter apps on an iOS device or on the simulator.
 ### Install CocoaPods
 
 If your apps depend on [Flutter plugins][] with native {{os}} code,
-install CocoaPods. Built using Ruby,
-CocoaPods handles the bundling of various dependencies across Flutter
-and {{os}} code.
+install [CocoaPods][cocoapods].
+This program bundles various dependencies across Flutter and {{os}} code.
 
-To [install and set up CocoaPods][cocoapods], run the following commands:
+To install and set up CocoaPods, run the following commands:
 
-1. Install Homebrew if necessary.
+1. Install `cocoapods` following the
+   [CocoaPods install guide][cocoapods].
 
    ```terminal
-   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+   $ sudo gem install cocoapods
    ```
+1. Launch your preferred text editor.
 
-1. Install `ruby` using Homebrew.
+1. Open the Zsh environmental variable file `~/.zshenv` in your text editor.
 
-   ```terminal
-   {{prompt1}} brew install ruby
-   ```
-
-1. Install `cocoapods` using Homebrew.
+1. Copy the following line and paste it at the end of your `~/.zshenv` file.
 
-   ```terminal
-   {{prompt1}} brew install cocoapods
+   ```conf
+   export PATH=$HOME/.gem/bin:$PATH
    ```
 
-Using Homebrew reduces potential issues with chipsets and install permissions.
+1. Save your `~/.zshenv` file.
+
+1. To apply this change, restart all open terminal sessions.
 
 [Flutter plugins]: {{site.url}}/packages-and-plugins/developing-packages#types
-[cocoapods]: https://formulae.brew.sh/formula/cocoapods
+[cocoapods]: https://guides.cocoapods.org/using/getting-started.html#installation
diff --git a/src/_includes/docs/install/devices/ios-simulator.md b/src/_includes/docs/install/devices/ios-simulator.md
index 02cc6739946..07b2018767f 100644
--- a/src/_includes/docs/install/devices/ios-simulator.md
+++ b/src/_includes/docs/install/devices/ios-simulator.md
@@ -7,7 +7,7 @@ follow this procedure.
 1. To start the Simulator, run the following command:
 
     ```terminal
-    open -a Simulator
+    $ open -a Simulator
     ```
 
 1. Set your Simulator to use a 64-bit device.
@@ -17,9 +17,12 @@ follow this procedure.
 
      1. Go to **Window** <span aria-label="and then">></span>
         **Devices and Simulators**.
+
         You can also press <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>2</kbd>.
+
      2. Once the **Devices and Simulators** dialog opens,
         click **Simulators**.
+
      3. Choose a **Simulator** from the left-hand list or press **+** to
         create a new simulator.
 
diff --git a/src/_includes/docs/install/flutter-sdk.md b/src/_includes/docs/install/flutter-sdk.md
index 167acb5e5a1..711e675a7e3 100644
--- a/src/_includes/docs/install/flutter-sdk.md
+++ b/src/_includes/docs/install/flutter-sdk.md
@@ -29,13 +29,13 @@ or download and install the Flutter bundle yourself.
 
 <div class="tab-pane active" id="vscode" role="tabpanel" aria-labelledby="vscode-tab" markdown="1">
 
-{% include docs/install/flutter/vscode.md os=os terminal=terminal %}
+{% include docs/install/flutter/vscode.md os=os terminal=terminal target=v-target %}
 
 </div>
 
 <div class="tab-pane" id="download" role="tabpanel" aria-labelledby="download-tab" markdown="1">
 
-{% include docs/install/flutter/download.md os=os terminal=terminal %}
+{% include docs/install/flutter/download.md os=os terminal=terminal target=v-target%}
 
 </div>
 </div>
@@ -43,4 +43,4 @@ or download and install the Flutter bundle yourself.
 
 If you have installed all prerequisites and the Flutter SDK,
 you should be able to start developing Flutter on
-{{include.os}} for {{include.target}}.
+{{os}} for {{v-target}}.
diff --git a/src/_includes/docs/install/flutter/download.md b/src/_includes/docs/install/flutter/download.md
index 37b842ed943..b879e20f224 100644
--- a/src/_includes/docs/install/flutter/download.md
+++ b/src/_includes/docs/install/flutter/download.md
@@ -5,8 +5,9 @@
 
 {% assign os = include.os %}
 {% assign osl = include.os | downcase %}
+{% assign target = include.target %}
 {% case os %}
-{% when 'Windows' -%}
+{% when "Windows" -%}
    {% assign unzip='Extract-Archive' %}
    {% assign path='C:\dev\' %}
    {% assign terminal='PowerShell' %}
@@ -39,13 +40,18 @@
    {% assign mv1 = 'mv ' | append: dirdl %}
 {% endcase -%}
 
+To install Flutter,
+download the Flutter SDK bundle from its archive,
+move the bundle to where you want it stored,
+then extract the SDK.
+
 1. Download the following installation bundle to get the latest
    {{site.sdk.channel}} release of the Flutter SDK.
 
    {% if os=='macOS' %}
 
-   | Intel | | <span class="apple-silicon">Apple Silicon</span> |
-   |-------| | ---------------|
+   | Intel Processor | | Apple Silicon |
+   |-----------------|-|---------------|
    | [(loading...)](#){:.download-latest-link-{{osl}}.btn.btn-primary} | | [(loading...)](#){:.download-latest-link-{{osl}}-arm64.apple-silicon.btn.btn-primary} |
 
    {% else %}
@@ -84,6 +90,9 @@
 
 [SDK archive]: {{site.url}}/release/archive
 
-{% if os == 'Windows' %}
-{% include docs/install/reqs/windows/set-path.md terminal=terminal %}
-{% endif %}
+{% case os %}
+{% when 'Windows' %}
+{% include docs/install/reqs/windows/set-path.md terminal=terminal target=target %}
+{% when 'macOS' %}
+{% include docs/install/reqs/macos/set-path.md terminal=terminal target=target dir=dirinstall %}
+{% endcase %}
diff --git a/src/_includes/docs/install/flutter/vscode.md b/src/_includes/docs/install/flutter/vscode.md
index 5cfe0db148d..a02f76584af 100644
--- a/src/_includes/docs/install/flutter/vscode.md
+++ b/src/_includes/docs/install/flutter/vscode.md
@@ -9,15 +9,19 @@
 ### Use VS Code to install Flutter
 {:.no_toc}
 
-#### Start Flutter install
+To install Flutter using these instructions, verify that
+you have installed [Visual Studio Code][]
+{{site.appmin.vscode}} or later and the [Flutter extension for VS Code][].
+
+#### Prompt VS Code to install Flutter
 {:.no_toc}
 
-1. Open VS Code.
+1. Launch VS Code.
 
-1. To open the Command Palette,
+1. To open the **Command Palette**,
    press <kbd>{{special}}</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>.
 
-1. In the Command Palette, type `flutter`.
+1. In the **Command Palette**, type `flutter`.
 
 1. Select **Flutter: New Project**.
 
@@ -26,10 +30,12 @@
    {:type="a"}
    1. If you have the Flutter SDK installed, click **Locate SDK**.
 
-   1. If you do not have the Flutter SDK installed, click **Download SDK**.
+   1. If you do not have the Flutter SDK installed,
+      click **Download SDK**.
 
-      This option sends you the Flutter install page if you have not installed
-      Git for Windows as directed in the [development tools prerequisites][].
+      This option sends you the Flutter install page if you have not
+      installed Git {% if os == "Windows" %}for Windows {% endif %}as directed in
+      the [development tools prerequisites][].
 
 1. When prompted **Which Flutter template?**, ignore it.
    Press <kbd>Esc</kbd>.
@@ -128,3 +134,5 @@
    1. Restart VS Code.
 
 [development tools prerequisites]: #development-tools
+[Visual Studio Code]: https://code.visualstudio.com/docs/setup/mac
+[Flutter extension for VS Code]: https://marketplace.visualstudio.com/items?itemName=Dart-Code.flutter
diff --git a/src/_includes/docs/install/reqs/flutter-sdk/flutter-doctor-precedence.md b/src/_includes/docs/install/reqs/flutter-sdk/flutter-doctor-precedence.md
new file mode 100644
index 00000000000..417170bd06e
--- /dev/null
+++ b/src/_includes/docs/install/reqs/flutter-sdk/flutter-doctor-precedence.md
@@ -0,0 +1,3 @@
+When you run the current version of `flutter doctor`,
+it might list a different version of one of these packages.
+If it does, install the version it recommends.
diff --git a/src/_includes/docs/install/reqs/macos/apple-silicon.md b/src/_includes/docs/install/reqs/macos/apple-silicon.md
index 54fb4093203..e34a6af33b9 100644
--- a/src/_includes/docs/install/reqs/macos/apple-silicon.md
+++ b/src/_includes/docs/install/reqs/macos/apple-silicon.md
@@ -1,12 +1,13 @@
-{{site.alert.important}}
-  When installing on an [Apple Silicon Mac][],
-  install the Rosetta translation environment.
-  Some components require the [Rosetta][need-rosetta].
+Some Flutter components require the 
+[Rosetta 2 translation process][need-rosetta]
+on Macs running [Apple silicon][].
+To run all Flutter components on Apple silicon,
+install [Rosetta 2][rosetta].
 
-  ```terminal
-  sudo softwareupdate --install-rosetta --agree-to-license
-  ```
-{{site.alert.end}}
+```terminal
+$ sudo softwareupdate --install-rosetta --agree-to-license
+```
 
-[Apple Silicon Mac]: https://support.apple.com/en-us/HT211814
+[Apple silicon]: https://support.apple.com/en-us/HT211814
+[rosetta]: https://support.apple.com/en-us/HT211861
 [need-rosetta]: {{site.repo.this}}/pull/7119#issuecomment-1124537969
diff --git a/src/_includes/docs/install/reqs/macos/base.md b/src/_includes/docs/install/reqs/macos/base.md
index 7e2a322bd25..633690b518c 100644
--- a/src/_includes/docs/install/reqs/macos/base.md
+++ b/src/_includes/docs/install/reqs/macos/base.md
@@ -1,10 +1,19 @@
 {% assign target = include.target %}
+{% case target %}
+{% when 'mobile-ios' %}
+{% assign v-target = "iOS" %}
+{% when 'mobile-android' %}
+{% assign v-target = "Android" %}
+{% else %}
+{% assign v-target = target %}
+{% endcase %}
 {% assign os = include.os %}
 
 ## Verify system requirements
 
 To install and run Flutter,
-your {{os}} environment must meet these requirements:
+your {{os}} environment must meet the following hardware
+and software requirements.
 
 ### Hardware requirements
 
@@ -14,7 +23,7 @@ minimal hardware requirements.
 <div class="table-wrapper" markdown="1">
 |     Requirement              |                                    Minimum                               |    Recommended      |
 |:-----------------------------|:------------------------------------------------------------------------:|:-------------------:|
-| x86_64 CPU Cores             | 4                                                                        | 8                   |
+| CPU Cores                    | 4                                                                        | 8                   |
 | Memory in GB                 | 8                                                                        | 16                  |
 | Display resolution in pixels | WXGA (1366 x 768)                                                        | FHD (1920 x 1080)   |
 | Free disk space in GB        | {% include docs/install/reqs/macos/storage.md target=target %}
@@ -22,27 +31,31 @@ minimal hardware requirements.
 
 ### Software requirements
 
-To write and compile Flutter code for {{target}},
-you must have the following version of macOS and the listed
-software packages.
+To write and compile Flutter code for {{v-target}},
+install the following packages.
 
 #### Operating system
 {:.no_toc}
 
 Flutter supports macOS {{site.devmin.macos}} or later.
+This guide presumes your Mac runs the `zsh` as your default shell.
+
+{% include docs/install/reqs/macos/zsh-config.md target=target %}
 
 {% include docs/install/reqs/macos/apple-silicon.md %}
 
 #### Development tools
 {:.no_toc}
 
-Download and install the macOS version of the following packages:
+Download and install the following packages.
 
 {% include docs/install/reqs/macos/software.md target=target %}
 
 The developers of the preceding software provide support for those products.
 To troubleshoot installation issues, consult that product's documentation.
 
+{% include /docs/install/reqs/flutter-sdk/flutter-doctor-precedence.md %}
+
 #### Text editor or integrated development environment
 {:.no_toc}
 
diff --git a/src/_includes/docs/install/reqs/macos/set-path.md b/src/_includes/docs/install/reqs/macos/set-path.md
new file mode 100644
index 00000000000..25a7eccbf61
--- /dev/null
+++ b/src/_includes/docs/install/reqs/macos/set-path.md
@@ -0,0 +1,33 @@
+{% assign terminal=include.terminal %}
+{% assign target = include.target %}
+{% assign dir = include.dir %}
+
+### Add Flutter to your `PATH`
+{:.no_toc}
+
+To run Flutter commands in {{terminal}},
+add Flutter to the `PATH` environment variable.
+This guide presumes your [Mac runs the latest default shell][zsh-mac], `zsh`.
+Zsh uses the `.zshenv` file for [environment variables][envvar].
+
+1. Launch your preferred text editor.
+
+1. If it exists, open the Zsh environmental variable file `~/.zshenv`
+   in your text editor. If it doesn't, create `~/.zshenv`.
+
+1. Copy the following line and paste it at the end of your `~/.zshenv` file.
+
+   ```conf
+   export PATH=$HOME/development/flutter/bin:$PATH
+   ```
+
+1. Save your `~/.zshenv` file.
+
+1. To apply this change, restart all open terminal sessions.
+
+If you use another shell,
+check out [this tutorial on setting your PATH][other-path].
+
+[zsh-mac]: https://support.apple.com/en-us/102360
+[envvar]: https://zsh.sourceforge.io/Intro/intro_3.html
+[other-path]: https://www.cyberciti.biz/faq/unix-linux-adding-path/
diff --git a/src/_includes/docs/install/reqs/macos/software.md b/src/_includes/docs/install/reqs/macos/software.md
index 27a5d67e654..fed27258bf2 100644
--- a/src/_includes/docs/install/reqs/macos/software.md
+++ b/src/_includes/docs/install/reqs/macos/software.md
@@ -1,47 +1,40 @@
 {% assign target = include.target %}
 
+{% assign xcode = '[Xcode][] ' | append: site.appnow.xcode | append: ' to debug and compile native Swift or ObjectiveC code.' %}
+{% assign cocoapods = '[CocoaPods][] ' | append: site.appnow.cocoapods | append: ' to compile enable Flutter plugins in your native apps.' %}
+{% capture android %}
+[Android Studio][] {{site.appmin.android_studio}} to debug and compile
+Java or Kotlin code for Android.
+Flutter requires the full version of Android Studio.
+{% endcapture %}
+{% assign chrome = "[Google Chrome][] to debug JavaScript code for web apps." %}
+{% assign git-main = '[Git][] ' | append: site.appmin.github_mac | append: ' or later to manage source code.' %}
+{% assign git-xcode = "The Xcode installation includes " %}
+{% capture git-other %}
+To check if you have `git` installed,
+type `git version` in your Terminal.
+If you need to install `git`, type `brew install git`.
+{% endcapture %}
+
 {% case target %}
-{% when 'desktop','mobile-ios' -%}
-
-* [Xcode][] {{site.appnow.xcode}} to debug and compile native Swift or ObjectiveC code.
-* [CocoaPods][] {{site.appnow.cocoapods}} to compile enable Flutter plugins in your native apps.
-* Git {{site.appmin.github_mac}} or later to manage source code.
-  This installs as part of the Xcode installation.
-  * To check if you have `git` installed, type `git version` in your Terminal.
-  * If you don't have `git` installed, use [Homebrew][].
-  * If you have `homebrew` installed, type `brew install git`.
-
-{% when 'mobile-android' -%}
-
-* [Android Studio][] {{site.appmin.android_studio}} to debug and compile
-  Java or Kotlin code for Android.
-  Flutter requires the full version of Android Studio.
-* [Git][] {{site.appmin.github_mac}} or later to manage source code.
-  * To check if you have `git` installed, type `git version` in your Terminal.
-  * If you don't have `git` installed, use [Homebrew][].
-  * If you have `homebrew` installed, type `brew install git`.
+{% when 'desktop','mobile-ios' %}
+
+* {{xcode}} {{git-xcode}} {{git-main}}
+* {{cocoapods}}
+
+{% when 'mobile-android' %}
+
+* {{android -}}
+* {{git-main}}
+  {{- git-other}}
 
 {% when 'web' -%}
 
-* [Google Chrome][] to debug JavaScript code for web apps.
-* [Git][] {{site.appmin.github_mac}} or later to manage source code.
-  * To check if you have `git` installed, type `git version` in your Terminal.
-  * If you don't have `git` installed, use [Homebrew][].
-  * If you have `homebrew` installed, type `brew install git`.
-
-{% else -%}
-
-* [Xcode][] {{site.appnow.xcode}} to debug and compile native Swift or ObjectiveC code.
-* [CocoaPods][] {{site.appnow.cocoapods}} to compile enable Flutter plugins in your native apps.
-* [Android Studio][] {{site.appmin.android_studio}} to debug and compile
-  Java or Kotlin code for Android.
-  Flutter requires the full version of Android Studio.
-* The latest version of [Google Chrome][] to debug JavaScript code for web apps.
-* Git {{site.appmin.github_mac}} or later to manage source code.
-  This installs as part of the Xcode installation.
-  To verify that you have `git` installed, type `git version` in your Terminal.
-
-{% endcase -%}
+* {{chrome -}}
+* {{git-main}}
+  {{- git-other}}
+
+{% endcase %}
 
 [Homebrew]: https://brew.sh/
 [Git]: https://formulae.brew.sh/formula/git
diff --git a/src/_includes/docs/install/reqs/macos/zsh-config.md b/src/_includes/docs/install/reqs/macos/zsh-config.md
new file mode 100644
index 00000000000..2154dd25b74
--- /dev/null
+++ b/src/_includes/docs/install/reqs/macos/zsh-config.md
@@ -0,0 +1,46 @@
+{% assign target = include.target %}
+
+<details markdown="1">
+<summary><strong>To verify your shell configuration, expand this section</strong></summary>
+
+Like most UNIX-like operating system, macOS can support multiple shells,
+like `bash`, `zsh`, and `sh`.
+As of the October 2019 release of macOS Catalina (macOS 10.15),
+Zsh or `zsh` is the default shell for macOS.
+
+#### Check and set `zsh` as default
+{:.no_toc}
+
+1. To verify `zsh` was set as the default macOS shell,
+   run the [Directory Services command line utility][dscl].
+
+    ```terminal
+    $ dscl . -read ~/ UserShell
+    ```
+
+    {{terminal}} should print the following as its response.
+
+    ```terminal
+    UserShell: /bin/zsh
+    ```
+
+    You can skip the remaining steps.
+
+1. If you need to install `zsh`,
+   follow the procedure in [this Wiki][install-zsh].
+
+1. If you need to change your default shell to `zsh`,
+   run the `chsh` command.
+
+    ```terminal
+    $ chsh -s `which zsh`
+    ```
+
+To learn more about macOS and `zsh`, check out
+[Use zsh as the default shell on your Mac][zsh-mac]
+in the macOS documentation.
+
+</details>
+
+[install-zsh]: https://github.com/ohmyzsh/ohmyzsh/wiki/Installing-ZSH
+[dscl]: https://ss64.com/mac/dscl.html
diff --git a/src/_includes/docs/install/reqs/windows/base.md b/src/_includes/docs/install/reqs/windows/base.md
index 9ec85916337..7389012eba3 100644
--- a/src/_includes/docs/install/reqs/windows/base.md
+++ b/src/_includes/docs/install/reqs/windows/base.md
@@ -45,6 +45,8 @@ Download and install the Windows version of the following packages:
 The developers of the preceding software provide support for those products.
 To troubleshoot installation issues, consult that product's documentation.
 
+{% include docs/install/reqs/flutter-sdk/flutter-doctor-precedence.md %}
+
 ## Configure a text editor or IDE
 
 You can build apps with Flutter using any text editor or