diff --git a/README.md b/README.md index 4a3e3d6dbe..f7b3e4b762 100644 --- a/README.md +++ b/README.md @@ -10,12 +10,13 @@ Spin up sites in seconds, sync with WordPress.com or Pressable, or import any Wo ## Get started -WordPress Studio is free to use for Mac and Windows. Simply download the app to start building and testing — no dependencies required. +WordPress Studio is free to use for Mac, Windows, and Linux. Simply download the app to start building and testing — no dependencies required. [Download WordPress Studio](https://developer.wordpress.com/studio/) for: - macOS (Intel or Apple Silicon) -- Windows +- Windows (x64 or ARM64) +- Linux (x64 or ARM64) ## Highlights diff --git a/docs/code-contributions.md b/docs/code-contributions.md index 9b68913c85..bc655592e7 100644 --- a/docs/code-contributions.md +++ b/docs/code-contributions.md @@ -196,7 +196,7 @@ Then open `chrome://inspect` in a Chromium-based browser and click "inspect" nex ## Building Installers Once all required dependencies are installed, you can build installers for the app. -Installers can currently be built on Mac (Intel or Apple Silicon), Windows, and experimentally for Linux using the following commands: +Installers can be built on Mac (Intel or Apple Silicon), Windows (x64 or ARM64), and Linux (x64 or ARM64) using the following commands: ```bash npm install @@ -205,24 +205,7 @@ npm run make After the build process completes, you can find the executables in the `out/` directory. -### Linux - -Linux support is currently in an experimental phase. While official packages are not yet available, you can build Studio from source: - -```bash -npm install -npm run package -``` - -After building, the executable will be located at `apps/studio/out/Studio-linux-x64/studio`. - -**Important considerations:** - -- The auto-update feature is not currently supported on Linux builds. -- For Wayland systems, you may need to use additional flags when running the application. -- Some features may not work as expected due to platform-specific implementations. - -For detailed instructions including how to create a desktop launcher, handle Wayland compatibility, and troubleshoot common issues, see the [**Linux Guide**](./linux.md). +Linux has additional source-build steps and platform-specific troubleshooting — see the [Linux notes](./linux.md). ## Localization diff --git a/docs/linux.md b/docs/linux.md index 5ca715deb1..280a03b095 100644 --- a/docs/linux.md +++ b/docs/linux.md @@ -1,146 +1,74 @@ -# Linux Guide +# Linux -Studio for Linux is currently in an experimental phase. While official packages are not yet available, you can easily build and run Studio from source on most Linux distributions. - -## Current Limitations - -Linux support comes with certain limitations: -- For systems using Wayland, you may need to set the `--enable-features=UseOzonePlatform --ozone-platform=wayland` flag when running the application. -- Some features may not work as expected on Linux due to platform-specific implementations. -- The auto-update feature is not currently supported on Linux builds. -- These instructions should work for most Linux distributions, but you may need to adjust them based on your specific setup or distribution. +Linux-specific build steps and troubleshooting for contributors. See also [code-contributions.md](./code-contributions.md) for general setup. ## Building from Source -### Prerequisites - -Ensure you have the following dependencies installed: - -- [Node.js](https://nodejs.org/) - required JavaScript runtime environment -- [Python](https://www.python.org/) - required for building native dependencies -- [setuptools](https://pypi.org/project/setuptools/) - required for building native dependencies - -Many contributors use [`nvm`](https://github.com/nvm-sh/nvm) to manage Node.js installations. - -### Build Steps - -1. **Clone the repository:** - ```bash - git clone https://github.com/Automattic/studio.git - cd studio - ``` - -2. **Install dependencies:** - ```bash - nvm use - npm install - ``` - -3. **Build the application:** - ```bash - npm run package - ``` - - This will create an `out/` folder inside `apps/studio/`. +To build a runnable app bundle from a clone: -4. **Locate the executable:** - - Navigate to the `apps/studio/out/Studio-linux-x64/` folder. Inside, you'll find a `studio` executable. - -5. **Run Studio:** - ```bash - cd apps/studio/out/Studio-linux-x64 - ./studio - ``` - -## Creating a Desktop Shortcut (Optional) - -For easier access, you can create a desktop entry file that will add Studio to your application launcher. +```bash +npm install +npm run package +``` -### Steps +The executable will be at `apps/studio/out/Studio-linux-/studio`. To produce a `.deb` package instead, run `npm run make` (auto-detects the host arch); output lands in `apps/studio/out/make/deb//`. To make arch specific build, use `npm run make:linux-x64` or `npm run make:linux-arm64 -1. **Create a desktop file:** - ```bash - nano ~/.local/share/applications/studio.desktop - ``` +## Creating a Desktop Shortcut -2. **Add the following content:** - ```ini - [Desktop Entry] - Name=Studio by WordPress.com - Icon=/assets/studio-app-icon.png - Comment=Local WordPress development environment - Exec=/apps/studio/out/Studio-linux-x64/studio %U - Type=Application - Terminal=false - MimeType=x-scheme-handler/wp-studio; - Categories=Development; - ``` +`.deb` installs register a desktop entry automatically. For source builds you can create one manually: -3. **Replace placeholders:** - - Replace `` with the actual absolute path to your cloned repository - - For example: `/home/username/projects/studio` +```bash +nano ~/.local/share/applications/studio.desktop +``` -4. **Make the desktop file executable (if needed):** - ```bash - chmod +x ~/.local/share/applications/studio.desktop - ``` +Add the following, replacing `` with the actual path to your clone and `` with `x64` or `arm64` to match your build: -5. **Refresh your application menu:** - - Depending on your desktop environment, you may need to log out and back in, or run: - ```bash - update-desktop-database ~/.local/share/applications - ``` +```ini +[Desktop Entry] +Name=Studio by WordPress.com +Icon=/apps/studio/assets/studio-app-icon.png +Comment=Local WordPress development environment +Exec=/apps/studio/out/Studio-linux-/studio %U +Type=Application +Terminal=false +MimeType=x-scheme-handler/wp-studio; +Categories=Development; +``` -6. **Register Studio handler for `wp-studio://` links:** - ```bash - xdg-mime default studio.desktop x-scheme-handler/wp-studio - ``` - Without this, browsers will still show "Open With… / No Apps Available" when WordPress.com OAuth redirects back to `wp-studio://`. +After creating the file, refresh the application menu so the entry appears: -Studio should now appear in your application launcher and can handle `wp-studio://` protocol URLs. +```bash +update-desktop-database ~/.local/share/applications +``` -## Running with Wayland +## Registering the `wp-studio://` URL handler -If you're using Wayland instead of X11, run Studio with additional flags: +When working on OAuth/login flows from a source build, register the binary as the `wp-studio://` handler so browser callbacks reach your dev build: ```bash -./studio --enable-features=UseOzonePlatform --ozone-platform=wayland +xdg-mime default studio.desktop x-scheme-handler/wp-studio ``` -You can add these flags to the `Exec` line in your desktop file if you created one: - -```ini -Exec=/apps/studio/out/Studio-linux-x64/studio --enable-features=UseOzonePlatform --ozone-platform=wayland %U -``` +This depends on the `.desktop` file from the previous section. Without it, browsers will show "Open With… / No Apps Available" when WordPress.com OAuth redirects back, or hand the callback off to an installed `.deb` build (masking the bug you're trying to debug). ## Troubleshooting -### Permission Issues - -If you encounter permission issues when running the executable, make sure it has execute permissions: +If `./studio` fails with a permission error, ensure it has execute permissions: ```bash -chmod +x apps/studio/out/Studio-linux-x64/studio +chmod +x apps/studio/out/Studio-linux-/studio ``` -### `npm start` fails with a Chrome sandbox error (Ubuntu 24.04+) - -On distributions that restrict unprivileged user namespaces via AppArmor (notably Ubuntu 24.04+), `npm start` may abort with `FATAL: ... The SUID sandbox helper binary was found, but is not configured correctly`. Electron falls back to its SUID sandbox because AppArmor blocks the user-namespace sandbox by default. - -Allow the user-namespace sandbox persistently: +On Ubuntu 24.04+ and other distributions that restrict unprivileged user namespaces via AppArmor, `npm start` may abort with `FATAL: ... The SUID sandbox helper binary was found, but is not configured correctly`. Electron falls back to its SUID sandbox because AppArmor blocks the user-namespace sandbox by default. Allow it persistently: ```bash echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/60-apparmor-namespace.conf sudo sysctl --system ``` -The setting survives reboots and `npm install` runs, so you only need to do this once per machine. - -### Missing Dependencies +The setting survives reboots and `npm install` runs, so you only need to do this once per machine. This only affects `npm start` during development; installed `.deb` packages ship a properly-configured SUID sandbox binary and are unaffected. -If you encounter errors about missing libraries, you may need to install additional system dependencies. Common packages include: +If you encounter errors about missing libraries on a source build (`.deb` installs declare their dependencies automatically), install the common system packages: ```bash # Debian/Ubuntu @@ -152,26 +80,3 @@ sudo dnf install gtk3 libnotify nss libXScrnSaver libXtst xdg-utils at-spi2-core # Arch sudo pacman -S gtk3 libnotify nss libxss libxtst xdg-utils at-spi2-core util-linux libsecret ``` - -## Updating Studio - -Since auto-updates are not supported on Linux builds, you'll need to manually update: - -1. Pull the latest changes from the repository: - ```bash - cd - git pull - ``` - -2. Reinstall dependencies and rebuild: - ```bash - npm install - npm run package - ``` - -The executable in `apps/studio/out/Studio-linux-x64/` will be updated with the new version. - -## Contributing - -If you encounter Linux-specific issues or have suggestions for improving Linux support, please [open an issue](https://github.com/Automattic/studio/issues) or submit a pull request. Your feedback helps improve Studio for all Linux users! -