Add warning when user is running in ARM translation mode (#1560)

esimkowitz · web-flow · commit 0925af530091 · 2024-12-18T19:44:50.000-08:00
Adds warning and docs to let users know when they're running in ARM
translation mode. Also lets them configure to always dismiss if they
don't care.

&lt;!-- This is an auto-generated comment: release notes by coderabbit.ai
--&gt;
## Summary by CodeRabbit

- **New Features**
- Added a configuration option to dismiss architecture warnings during
application startup.
- Introduced new FAQs addressing ARM64 translation warnings and
instructions for joining beta builds.
- Added platform-specific requirements for macOS, Windows, and Linux in
the getting started documentation.

- **Bug Fixes**
- Enhanced build command flexibility by allowing dynamic command-line
arguments during the build process.

- **Documentation**
- Updated configuration documentation to include the new dismiss
architecture warning key.
- Minor formatting adjustments in FAQs and getting started
documentation.
	- Clarified platform compatibility details in the README.

- **Chores**
- Added a new constant for the dismiss architecture warning
configuration key.
- Introduced a new field for managing architecture warning settings in
the application configuration.
&lt;!-- end of auto-generated comment: release notes by coderabbit.ai --&gt;
diff --git a/README.md b/README.md
@@ -41,12 +41,18 @@ You can also install Wave Terminal directly from: [www.waveterm.dev/download](ht
 
 ### Minimum requirements
 
-Wave Terminal and WSH run on the following platforms:
+Wave Terminal runs on the following platforms:
 
 - macOS 11 or later (arm64, x64)
 - Windows 10 1809 or later (x64)
 - Linux based on glibc-2.28 or later (Debian 10, RHEL 8, Ubuntu 20.04, etc.) (arm64, x64)
 
+The WSH helper runs on the following platforms:
+
+- macOS 11 or later (arm64, x64)
+- Windows 10 or later (arm64, x64)
+- Linux Kernel 2.6.32 or later (x64), Linux Kernel 3.1 or later (arm64)
+
 ## Links
 
 - Homepage &mdash; https://www.waveterm.dev
diff --git a/Taskfile.yml b/Taskfile.yml
@@ -96,7 +96,7 @@ tasks:
         cmds:
             - cmd: '{{.RMRF}} "make"'
               ignore_error: true
-            - yarn build:prod && yarn electron-builder -c electron-builder.config.cjs -p never
+            - yarn build:prod && yarn electron-builder -c electron-builder.config.cjs -p never {{.CLI_ARGS}}
         deps:
             - yarn
             - docsite:build:embedded
diff --git a/docs/docs/config.mdx b/docs/docs/config.mdx
@@ -26,6 +26,7 @@ wsh editconfig
 | Key Name                             | Type     | Function                                                                                                                                                                                                                                                      |
 | ------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | app:globalhotkey                     | string   | A systemwide keybinding to open your most recent wave window. This is a set of key names separated by `:`. For more info, see [Customizable Systemwide Global Hotkey](#customizable-systemwide-global-hotkey)                                                 |
+| app:dismissarchitecturewarning       | bool     | Disable warnings on app start when you are using a non-native architecture for Wave. For more info, see [Why does Wave warn me about ARM64 translation when it launches?](./faq#why-does-wave-warn-me-about-arm64-translation-when-it-launches).              |
 | ai:preset                            | string   | the default AI preset to use                                                                                                                                                                                                                                  |
 | ai:baseurl                           | string   | Set the AI Base Url (must be OpenAI compatible)                                                                                                                                                                                                               |
 | ai:apitoken                          | string   | your AI api token                                                                                                                                                                                                                                             |
diff --git a/docs/docs/faq.mdx b/docs/docs/faq.mdx
@@ -28,9 +28,32 @@ the location of the Git Bash "bash.exe" binary. By default it is located at "C:\
 Just remember in JSON, backslashes need to be escaped. So add this to your [settings.json](./config) file:
 
 ```json
-    "term:localshellpath": "C:\\Program Files\\Git\\bin\\bash.exe"
+"term:localshellpath": "C:\\Program Files\\Git\\bin\\bash.exe"
 ```
 
 ### Can I use WSH outside of Wave?
 
 `wsh` is an internal CLI for extending control over Wave to the command line, you can learn more about it [here](./wsh). To prevent misuse by other applications, `wsh` requires an access token provided by Wave to work and will not function outside of the app.
+
+## Why does Wave warn me about ARM64 translation when it launches?
+
+macOS and Windows both have compatibility layers that allow x64 applications to run on ARM computers. This helps more apps run on these systems while developers work to add native ARM support to their applications. However, it comes with significant performance tradeoffs.
+
+To get the best experience using Wave, it is recommended that you uninstall Wave and reinstall the version that is natively compiled for your computer. You can find the right version by consulting our [Installation Instructions](./gettingstarted#installation).
+
+You can disable this warning by setting `app:dismissarchitecturewarning=true` in [your configurations](./config.mdx).
+
+## How do I join the beta builds of Wave?
+
+Wave publishes to two channels, `latest` and `beta`. If you've installed the app for macOS, Windows, or Linux via DEB or RPM, you can set the following configurations in your `settings.json` (see [Configuration](./config) for more info):
+
+```json
+"autoupdate:enabled": true,
+"autoupdate:channel": "beta"
+```
+
+If you've installed via Snap, you can use the following command:
+
+```sh
+sudo snap install waveterm --classic --beta
+```
diff --git a/docs/docs/gettingstarted.mdx b/docs/docs/gettingstarted.mdx
@@ -14,6 +14,35 @@ Wave Terminal is a modern terminal that includes graphical capabilities like web
 <PlatformProvider>
   <PlatformSelectorButton />
 
+### Platform requirements
+
+<PlatformItem platforms={["mac"]}>
+
+- Supported architectures: Apple Silicon, x64
+- Supported OS version: macOS 11 Big Sur or later
+
+</PlatformItem>
+
+<PlatformItem platforms={["windows"]}>
+
+- Supported architectures: x64
+- Supported OS version: Windows 10 1809 or later, Windows 11
+
+:::note
+
+ARM64 is planned, but is currently blocked by upstream dependencies (see [Windows ARM Support](https://github.com/wavetermdev/waveterm/issues/928)).
+
+:::
+
+</PlatformItem>
+
+<PlatformItem platforms={["linux"]}>
+
+- Supported architectures: x64, ARM64
+- Supported OS version: must have glibc-2.28 or later (Debian >=10, RHEL >=8, Ubuntu >=20.04, etc.)
+
+</PlatformItem>
+
 ### Package managers
 
 <PlatformItem platforms={["mac"]}>
diff --git a/emain/emain.ts b/emain/emain.ts
@@ -47,6 +47,7 @@ import { getLaunchSettings } from "./launchsettings";
 import { log } from "./log";
 import { makeAppMenu } from "./menu";
 import {
+    checkIfRunningUnderARM64Translation,
     getElectronAppBasePath,
     getElectronAppUnpackedBasePath,
     getWaveConfigDir,
@@ -588,6 +589,7 @@ async function appMain() {
     await electronApp.whenReady();
     configureAuthKeyRequestInjection(electron.session.defaultSession);
     const fullConfig = await services.FileService.GetFullConfig();
+    checkIfRunningUnderARM64Translation(fullConfig);
     ensureHotSpareTab(fullConfig);
     await relaunchBrowserWindows();
     await initDocsite();
diff --git a/emain/platform.ts b/emain/platform.ts
@@ -1,7 +1,8 @@
 // Copyright 2024, Command Line Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-import { app, ipcMain } from "electron";
+import { fireAndForget } from "@/util/util";
+import { app, dialog, ipcMain, shell } from "electron";
 import envPaths from "env-paths";
 import { existsSync, mkdirSync } from "fs";
 import os from "os";
@@ -40,6 +41,32 @@ const WaveConfigHomeVarName = "WAVETERM_CONFIG_HOME";
 const WaveDataHomeVarName = "WAVETERM_DATA_HOME";
 const WaveHomeVarName = "WAVETERM_HOME";
 
+export function checkIfRunningUnderARM64Translation(fullConfig: FullConfigType) {
+    if (!fullConfig.settings["app:dismissarchitecturewarning"] && app.runningUnderARM64Translation) {
+        console.log("Running under ARM64 translation, alerting user");
+        const dialogOpts: Electron.MessageBoxOptions = {
+            type: "warning",
+            buttons: ["Dismiss", "Learn More"],
+            title: "Wave has detected a performance issue",
+            message: `Wave is running in ARM64 translation mode which may impact performance.\n\nRecommendation: Download the native ARM64 version from our website for optimal performance.`,
+        };
+
+        const choice = dialog.showMessageBoxSync(null, dialogOpts);
+        if (choice === 1) {
+            // Open the documentation URL
+            console.log("User chose to learn more");
+            fireAndForget(() =>
+                shell.openExternal(
+                    "https://docs.waveterm.dev/faq#why-does-wave-warn-me-about-arm64-translation-when-it-launches"
+                )
+            );
+            throw new Error("User redirected to docsite to learn more about ARM64 translation, exiting");
+        } else {
+            console.log("User dismissed the dialog");
+        }
+    }
+}
+
 /**
  * Gets the path to the old Wave home directory (defaults to `~/.waveterm`).
  * @returns The path to the directory if it exists and contains valid data for the current app, otherwise null.
diff --git a/frontend/types/gotypes.d.ts b/frontend/types/gotypes.d.ts
@@ -618,6 +618,7 @@ declare global {
     type SettingsType = {
         "app:*"?: boolean;
         "app:globalhotkey"?: string;
+        "app:dismissarchitecturewarning"?: boolean;
         "ai:*"?: boolean;
         "ai:preset"?: string;
         "ai:apitype"?: string;
diff --git a/pkg/wconfig/metaconsts.go b/pkg/wconfig/metaconsts.go
@@ -8,6 +8,7 @@ package wconfig
 const (
 	ConfigKey_AppClear                       = "app:*"
 	ConfigKey_AppGlobalHotkey                = "app:globalhotkey"
+	ConfigKey_AppDismissArchitectureWarning  = "app:dismissarchitecturewarning"
 
 	ConfigKey_AiClear                        = "ai:*"
 	ConfigKey_AiPreset                       = "ai:preset"
diff --git a/pkg/wconfig/settingsconfig.go b/pkg/wconfig/settingsconfig.go
@@ -33,8 +33,9 @@ const AnySchema = `
 `
 
 type SettingsType struct {
-	AppClear        bool   `json:"app:*,omitempty"`
-	AppGlobalHotkey string `json:"app:globalhotkey,omitempty"`
+	AppClear                      bool   `json:"app:*,omitempty"`
+	AppGlobalHotkey               string `json:"app:globalhotkey,omitempty"`
+	AppDismissArchitectureWarning bool   `json:"app:dismissarchitecturewarning,omitempty"`
 
 	AiClear         bool    `json:"ai:*,omitempty"`
 	AiPreset        string  `json:"ai:preset,omitempty"`
