Adds PATH for macOS (flutter#10031)

Adds PATH instructions for macOS. Fixes flutter#9351 Fixes flutter#10015 Fixes flutter#10040 Fixes flutter#10036 --------- Co-authored-by: John Ryan <ryjohn@google.com>
atsansone · Apr 5, 2024 · 70d5e7b · 70d5e7b
1 parent ef0d77f
commit 70d5e7b
Show file tree

Hide file tree

Showing 13 changed files with 202 additions and 89 deletions.
diff --git 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
@@ -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
@@ -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
@@ -29,18 +29,18 @@ 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>
 {% comment %} End: Tab panes. {% endcomment -%}
 
 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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,35 +23,39 @@ 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 %}
 </div>
 
 ### 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
@@ -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/