From b32b9d05b8e518e269e0596d5c7c8349e25e5fe1 Mon Sep 17 00:00:00 2001 From: Francois Date: Tue, 18 Feb 2025 15:25:46 +0200 Subject: [PATCH 1/4] docs(flutter-setup): update setup steps to match the official guide Flutter documentation recommends downloading via VSCode or via the SDK Archive (tar/zip files) rather than cloning the git repository --- docs/FIREBASE_SETUP.md | 6 +++-- docs/FLUTTER_VERSION.md | 6 ++++- docs/INSTALL_FLUTTER.md | 19 +++++---------- docs/MULTIPLE_FLUTTER_VERSIONS.md | 40 ++++++++++++++++++++++++------- 4 files changed, 47 insertions(+), 24 deletions(-) diff --git a/docs/FIREBASE_SETUP.md b/docs/FIREBASE_SETUP.md index c7ce656342..8b8459acd3 100644 --- a/docs/FIREBASE_SETUP.md +++ b/docs/FIREBASE_SETUP.md @@ -1,6 +1,7 @@ # Firebase setup (local builds) To generate the configuration files for Firebase, follow the steps below: + - Create a Firebase account and add a new project. - Add a new web app to the project. @@ -8,8 +9,9 @@ To generate the configuration files for Firebase, follow the steps below: - Install flutterfire CLI: `dart pub global activate flutterfire_cli` - Login to Firebase: `firebase login` - Generate config files: `flutterfire configure` -- Disable github tracking of config files: -``` +- Disable github tracking of config files: + +```bash git update-index --assume-unchanged android/app/google-services.json git update-index --assume-unchanged ios/firebase_app_id_file.json git update-index --assume-unchanged macos/firebase_app_id_file.json diff --git a/docs/FLUTTER_VERSION.md b/docs/FLUTTER_VERSION.md index d2b300cd60..fd0dac7745 100644 --- a/docs/FLUTTER_VERSION.md +++ b/docs/FLUTTER_VERSION.md @@ -8,10 +8,14 @@ This project aims to keep the Flutter version up-to-date with the latest stable ## Pin Flutter version -``` +It is possible to pin the Flutter version to a specific version by checking out the corresponding tag. For example, to pin the Flutter version to 3.29.0, run the following commands: + +```bash cd ~/flutter git checkout 3.29.0 flutter doctor ``` +This is no longer recommended as it does not allow for sufficient isolation when working with multiple versions of Flutter, and there are known issues with this approach when running `flutter pub get` with Flutter 3.29.0. + See also: [Multiple flutter versions](MULTIPLE_FLUTTER_VERSIONS.md) diff --git a/docs/INSTALL_FLUTTER.md b/docs/INSTALL_FLUTTER.md index 498d3efc03..a4e3060f65 100644 --- a/docs/INSTALL_FLUTTER.md +++ b/docs/INSTALL_FLUTTER.md @@ -6,18 +6,13 @@ on [FLUTTER_VERSION.md](FLUTTER_VERSION.md). While it should be possible to go a few bugfixes versions over that version without issues, it's generally intended to use that exact version. -There are two main ways to get an older copy of Flutter. +To install the Flutter SDK, you can use the [Flutter extension for VS Code](https://marketplace.visualstudio.com/items?itemName=Dart-Code.flutter) (recommended), or download and install the Flutter bundle yourself from the [SDK Archive](https://docs.flutter.dev/release/archive), or use the [Flutter Version Manager (FVM)](https://fvm.app/documentation/getting-started/installation). The [official guide](https://docs.flutter.dev/get-started/install/linux/web) goes into further detail. -The first way is by cloning the official repository and then pinning to an older version. +## Use VS Code to install -1. Clone Flutter with +The recommended approach is to install the [Flutter extension for VSCode](https://marketplace.visualstudio.com/items?itemName=Dart-Code.flutter) (or the [Flutter extension for Android Studio/IntelliJ](https://plugins.jetbrains.com/plugin/9212-flutter)) and installing the Flutter SDK via the extension to simplify the process. - ```bash - cd ~ - git clone https://github.com/flutter/flutter.git - ``` - -2. [Pin Flutter version](FLUTTER_VERSION.md#pin-flutter-version) +## Download and install The second way is via downloading the desired version from the SDK Archives. Here are [Windows](https://docs.flutter.dev/release/archive?tab=windows), [Mac](https://docs.flutter.dev/release/archive?tab=macos) @@ -26,8 +21,6 @@ Remember to extract the file into a convenient place, such as `~/flutter`. Choose the option that is more convenient for you at the time. -If you opt for the SDK Archive, you easily change to use the [Pin Flutter version](FLUTTER_VERSION.md#pin-flutter-version) later if you prefer. - Add the flutter binaries subfolder `flutter/bin` to your system PATH. This process differs for each OS: For macOS: @@ -55,9 +48,9 @@ You might need to logout and re-login (or source the shell configuration file, i On macOS and Linux it should also be possible to confirm it's been added to the PATH correctly by running `which flutter`. -## Alternative: FVM +## Use Flutter Version Manager (FVM) -The recommended method of handling multiple Flutter versions is to use [FVM](https://fvm.app/documentation/getting-started/installation). +The recommended method of handling multiple Flutter versions is to use [FVM](https://fvm.app/documentation/getting-started/installation). To install FVM and use the stable version of the Flutter SDK in the current directory, run the following commands: ```bash curl -fsSL https://fvm.app/install.sh | bash diff --git a/docs/MULTIPLE_FLUTTER_VERSIONS.md b/docs/MULTIPLE_FLUTTER_VERSIONS.md index 3f47be011b..5d5fd557ea 100644 --- a/docs/MULTIPLE_FLUTTER_VERSIONS.md +++ b/docs/MULTIPLE_FLUTTER_VERSIONS.md @@ -1,6 +1,6 @@ # Handle multiple Flutter versions -## FVM +## Flutter Version Manager (FVM) The recommended method of handling multiple Flutter versions is to use [FVM](https://fvm.app/documentation/getting-started/installation). @@ -15,22 +15,22 @@ fvm use stable ### 1. Clone new Flutter instance alongside with the existing one -``` +```bash cd ~ git clone https://github.com/flutter/flutter.git flutter_web cd ./flutter_web -git checkout 3.23.4 +git checkout 3.29.0 ``` ### pen (or create) `.zshrc` file in your home directory -``` +```bash nano ~/.zshrc ``` Add line: -``` +```bash alias flutter_web="$HOME/flutter_web/bin/flutter" ``` @@ -38,7 +38,7 @@ Save and close. ### 3. Check if newly installed Flutter version is accessible from terminal -``` +```bash cd ~ flutter_web doctor ``` @@ -55,8 +55,32 @@ flutter_web doctor ---- -## Windows TBD +## Windows + +The following steps installs [fvm](https://fvm.app/docs/getting_started/installation) as a standalone application and uses it to manage both local and global Flutter SDKs. The recommended approach is to download and install a global version of Flutter SDK and use fvm to manage local Flutter SDKs, but this approach works for most scenarios. + +### 1. Install [Chocolatey](https://chocolatey.org/install), a windows package manager, if not installed yet + +```PowerShell +Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')) +``` + +### 2. Install [fvm](https://fvm.app/docs/getting_started/installation) using Chocolatey + +```PowerShell +choco install fvm +fvm use stable +fvm flutter doctor -v +``` ---- -## Linux TBD +## Linux + +The following steps installs [fvm](https://fvm.app/docs/getting_started/installation) as a standalone application and uses it to manage both local and global Flutter SDKs. The recommended approach is to download and install a global version of Flutter SDK and use fvm to manage local Flutter SDKs, but this approach works for most scenarios. + +Install [fvm](https://fvm.app/docs/getting_started/installation) using the installation script, `install.sh`. + +```bash +curl -fsSL https://fvm.app/install.sh | bash +``` From ac044085c6307e34e6294e919493313f9d0acdc8 Mon Sep 17 00:00:00 2001 From: Francois Date: Tue, 18 Feb 2025 15:27:53 +0200 Subject: [PATCH 2/4] docs(project-setup): update the referenced IDE and tool versions --- docs/BUILD_RUN_APP.md | 18 ++++++++++++++++++ docs/PROJECT_SETUP.md | 16 +++++++++------- 2 files changed, 27 insertions(+), 7 deletions(-) diff --git a/docs/BUILD_RUN_APP.md b/docs/BUILD_RUN_APP.md index 3f4409f42c..f7db2820c2 100644 --- a/docs/BUILD_RUN_APP.md +++ b/docs/BUILD_RUN_APP.md @@ -107,6 +107,24 @@ Run `flutter config --enable-windows-desktop` to enable Windows desktop support. If you are using Windows 10, please ensure that [Microsoft WebView2 Runtime](https://developer.microsoft.com/en-us/microsoft-edge/webview2?form=MA13LH) is installed for Webview support. Windows 11 ships with it, but Windows 10 users might need to install it. +Please ensure the following pre-requisites are installed: + +- [Visual Studio](https://visualstudio.microsoft.com/vs/community/) | Community 17.13.0 (Windows only), with the `Desktop development with C++` workload installed. +- [Nuget CLI](https://www.nuget.org/downloads) is required for Windows desktop builds. Install with winget + + ```PowerShell + winget install -e --id Microsoft.NuGet + # Add a primary package source + . $profile + nuget sources add -name "NuGet.org" -source https://api.nuget.org/v3/index.json + ``` + +- Enable long paths in Windows registry. Open CMD or PowerShell as Administrator, run the following, and restart: + + ```PowerShell + Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 + ``` + Before building for Windows, run `flutter doctor` to check if all the dependencies are installed. If not, follow the instructions in the error message. ```bash diff --git a/docs/PROJECT_SETUP.md b/docs/PROJECT_SETUP.md index 9ca730bdd8..56aa5a84bd 100644 --- a/docs/PROJECT_SETUP.md +++ b/docs/PROJECT_SETUP.md @@ -15,16 +15,18 @@ Komodo Wallet is a cross-platform application, meaning it can be built for multi - [VS Code](https://code.visualstudio.com/) - install and enable `Dart` and `Flutter` extensions - enable `Dart: Use recommended settings` via the Command Pallette - - [Android Studio](https://developer.android.com/studio) - Flamingo | 2024.1.2 + - [Android Studio](https://developer.android.com/studio) - Ladybug | 2024.2.2 - install and enable `Dart` and `Flutter` plugins - SDK Manager -> SDK Tools: - - [x] Android SDK Build-Tools 35 - - [x] NDK (Side by side) 27.1 - - [x] Android command line tools (latest) - - [x] CMake 3.30.3 (latest) - - [xCode](https://developer.apple.com/xcode/) - 15.4 (macOS only) - - [Visual Studio](https://visualstudio.microsoft.com/vs/community/) - Community 17.11.3 (Windows only) + - [x] Android SDK Build-Tools - (latest) 35.0.1 + - [x] NDK (Side by side) - (latest) 28.0 + - [x] Android command line tools - (latest) 19.0.0 + - [x] CMake - (latest) 3.31.5 + - [xCode](https://developer.apple.com/xcode/) | 16.2 (macOS only) + - [Visual Studio](https://visualstudio.microsoft.com/vs/community/) | Community 17.13.0 (Windows only) - `Desktop development with C++` workload required + - [Nuget CLI](https://www.nuget.org/downloads) required for Windows desktop builds + - [Enable long paths in Windows registry](BUILD_RUN_APP.md#windows-desktop) 3. Run `flutter doctor` and make sure all checks (except version) pass 4. [Clone project repository](CLONE_REPOSITORY.md) From 85590a7c67c69b4d3f698dfeab7e11421a0daad4 Mon Sep 17 00:00:00 2001 From: Francois Date: Tue, 18 Feb 2025 15:38:25 +0200 Subject: [PATCH 3/4] docs: address coderabbitai nitpick comments --- docs/BUILD_RUN_APP.md | 2 +- docs/INSTALL_FLUTTER.md | 2 +- docs/MULTIPLE_FLUTTER_VERSIONS.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/BUILD_RUN_APP.md b/docs/BUILD_RUN_APP.md index f7db2820c2..bd309b9ce1 100644 --- a/docs/BUILD_RUN_APP.md +++ b/docs/BUILD_RUN_APP.md @@ -107,7 +107,7 @@ Run `flutter config --enable-windows-desktop` to enable Windows desktop support. If you are using Windows 10, please ensure that [Microsoft WebView2 Runtime](https://developer.microsoft.com/en-us/microsoft-edge/webview2?form=MA13LH) is installed for Webview support. Windows 11 ships with it, but Windows 10 users might need to install it. -Please ensure the following pre-requisites are installed: +Please ensure the following prerequisites are installed: - [Visual Studio](https://visualstudio.microsoft.com/vs/community/) | Community 17.13.0 (Windows only), with the `Desktop development with C++` workload installed. - [Nuget CLI](https://www.nuget.org/downloads) is required for Windows desktop builds. Install with winget diff --git a/docs/INSTALL_FLUTTER.md b/docs/INSTALL_FLUTTER.md index a4e3060f65..e4df79ea90 100644 --- a/docs/INSTALL_FLUTTER.md +++ b/docs/INSTALL_FLUTTER.md @@ -37,7 +37,7 @@ For Linux: export PATH="$PATH:$HOME/flutter/bin" ``` -For Windows, follow the instructions below (from [flutter.dev](https://docs.flutter.dev/get-started/install/windows#update-your-path)):: +For Windows, follow the instructions below (from [flutter.dev](https://docs.flutter.dev/get-started/install/windows#update-your-path)): - From the Start search bar, enter `env` and select **Edit environment variables for your account**. - Under **User variables** check if there is an entry called **Path**: diff --git a/docs/MULTIPLE_FLUTTER_VERSIONS.md b/docs/MULTIPLE_FLUTTER_VERSIONS.md index 5d5fd557ea..63a62929aa 100644 --- a/docs/MULTIPLE_FLUTTER_VERSIONS.md +++ b/docs/MULTIPLE_FLUTTER_VERSIONS.md @@ -22,7 +22,7 @@ cd ./flutter_web git checkout 3.29.0 ``` -### pen (or create) `.zshrc` file in your home directory +### Open (or create) `.zshrc` file in your home directory ```bash nano ~/.zshrc @@ -36,7 +36,7 @@ alias flutter_web="$HOME/flutter_web/bin/flutter" Save and close. -### 3. Check if newly installed Flutter version is accessible from terminal +### 3. Check if the newly installed Flutter version is accessible from terminal ```bash cd ~ From b525646d89763830074ba4482f3d564d837b8e96 Mon Sep 17 00:00:00 2001 From: Francois Date: Fri, 21 Feb 2025 12:20:54 +0200 Subject: [PATCH 4/4] docs(fvm): remove unix-specific instructions, and reduce duplication --- docs/INSTALL_FLUTTER.md | 9 +---- docs/MULTIPLE_FLUTTER_VERSIONS.md | 67 +++++-------------------------- 2 files changed, 11 insertions(+), 65 deletions(-) diff --git a/docs/INSTALL_FLUTTER.md b/docs/INSTALL_FLUTTER.md index e4df79ea90..ef89c19632 100644 --- a/docs/INSTALL_FLUTTER.md +++ b/docs/INSTALL_FLUTTER.md @@ -50,11 +50,4 @@ On macOS and Linux it should also be possible to confirm it's been added to the ## Use Flutter Version Manager (FVM) -The recommended method of handling multiple Flutter versions is to use [FVM](https://fvm.app/documentation/getting-started/installation). To install FVM and use the stable version of the Flutter SDK in the current directory, run the following commands: - -```bash -curl -fsSL https://fvm.app/install.sh | bash - -# Configure the Flutter version to use in the current directory (e.g. ~/komodo-wallet) -fvm use stable -``` +Should you need to install and manage multiple versions of the Flutter SDK, it is recommended to use [FVM](https://fvm.app/documentation/getting-started/installation). See [MULTIPLE_FLUTTER_VERSIONS.md](MULTIPLE_FLUTTER_VERSIONS.md) for more details. diff --git a/docs/MULTIPLE_FLUTTER_VERSIONS.md b/docs/MULTIPLE_FLUTTER_VERSIONS.md index 63a62929aa..7eacf60600 100644 --- a/docs/MULTIPLE_FLUTTER_VERSIONS.md +++ b/docs/MULTIPLE_FLUTTER_VERSIONS.md @@ -1,8 +1,13 @@ -# Handle multiple Flutter versions +# Flutter Version Manager (FVM) -## Flutter Version Manager (FVM) +Should you need to install and manage multiple versions of the Flutter SDK, it is recommended to use [FVM](https://fvm.app/documentation/getting-started/installation). See [MULTIPLE_FLUTTER_VERSIONS.md](MULTIPLE_FLUTTER_VERSIONS.md) for more details. [FVM](https://fvm.app/documentation/getting-started/installation). See the overview from the [FVM documentation](https://fvm.app/documentation/getting-started) for more information: +> FVM helps with the need for consistent app builds by referencing the Flutter SDK version used on a per-project basis. It also allows you to have multiple Flutter versions installed to quickly validate and test upcoming Flutter releases with your apps without waiting for Flutter installation every time. -The recommended method of handling multiple Flutter versions is to use [FVM](https://fvm.app/documentation/getting-started/installation). +## macOS and Linux + +The following steps install [FVM](https://fvm.app/documentation/getting-started/installation) as a standalone application and use it to manage both local and global Flutter SDKs. The approach recommended by the FVM maintainers is to download and install a global version of Flutter SDK and use FVM to manage local Flutter SDKs, but this approach works for most use-cases. + +Install [FVM](https://fvm.app/documentation/getting-started/installation) using the installation script, `install.sh`. ```bash curl -fsSL https://fvm.app/install.sh | bash @@ -11,53 +16,11 @@ curl -fsSL https://fvm.app/install.sh | bash fvm use stable ``` -## macOS - -### 1. Clone new Flutter instance alongside with the existing one - -```bash -cd ~ -git clone https://github.com/flutter/flutter.git flutter_web -cd ./flutter_web -git checkout 3.29.0 -``` - -### Open (or create) `.zshrc` file in your home directory - -```bash -nano ~/.zshrc -``` - -Add line: - -```bash -alias flutter_web="$HOME/flutter_web/bin/flutter" -``` - -Save and close. - -### 3. Check if the newly installed Flutter version is accessible from terminal - -```bash -cd ~ -flutter_web doctor -``` - -### 4. Add new Flutter version to VSCode - -- Settings (⌘,) -> Extensions -> Dart -> SDK -> Flutter Sdk Paths -> Add Item -> `~/flutter_web` -- ⌘⇧P -> Developer: Reload window -- ⌘⇧P -> Flutter: Change SDK - -### 5. Add to Android Studio - -- Settings (⌘,) -> Languages & Frameworks -> Flutter -> SDK -> Flutter SDK Path -> `~/flutter_web` - ---- ## Windows -The following steps installs [fvm](https://fvm.app/docs/getting_started/installation) as a standalone application and uses it to manage both local and global Flutter SDKs. The recommended approach is to download and install a global version of Flutter SDK and use fvm to manage local Flutter SDKs, but this approach works for most scenarios. +The following steps install [FVM](https://fvm.app/documentation/getting-started/installation) as a standalone application and use it to manage both local and global Flutter SDKs. The approach recommended by the FVM maintainers is to download and install a global version of Flutter SDK and use FVM to manage local Flutter SDKs, but this approach works for most use-cases. ### 1. Install [Chocolatey](https://chocolatey.org/install), a windows package manager, if not installed yet @@ -65,7 +28,7 @@ The following steps installs [fvm](https://fvm.app/docs/getting_started/installa Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')) ``` -### 2. Install [fvm](https://fvm.app/docs/getting_started/installation) using Chocolatey +### 2. Install [FVM](https://fvm.app/documentation/getting-started/installation) using Chocolatey ```PowerShell choco install fvm @@ -74,13 +37,3 @@ fvm flutter doctor -v ``` ---- - -## Linux - -The following steps installs [fvm](https://fvm.app/docs/getting_started/installation) as a standalone application and uses it to manage both local and global Flutter SDKs. The recommended approach is to download and install a global version of Flutter SDK and use fvm to manage local Flutter SDKs, but this approach works for most scenarios. - -Install [fvm](https://fvm.app/docs/getting_started/installation) using the installation script, `install.sh`. - -```bash -curl -fsSL https://fvm.app/install.sh | bash -```