Pake/docs/faq.md

# Frequently Asked Questions (FAQ)

<h4 align="right"><strong>English</strong> | <a href="faq_CN.md">简体中文</a></h4>

Common issues and solutions when using Pake.

## Build Issues

### Linux: AppImage Build Fails with "failed to run linuxdeploy"

**Problem:**
When building AppImage on Linux (Debian, Ubuntu, Arch, etc.), you may encounter errors like:

```txt
Error: failed to run linuxdeploy
Error: strip: Unable to recognise the format of the input file
```

**Solution 1: Use NO_STRIP (Recommended)**

Simply add `NO_STRIP=true` before your build command:

```bash
NO_STRIP=true pake https://example.com --name MyApp --targets appimage
```

This bypasses the library stripping process that often causes issues on certain Linux distributions.

**Solution 2: Install System Dependencies**

If NO_STRIP doesn't work, ensure you have all required system dependencies:

```bash
sudo apt update
sudo apt install -y \
  libdbus-1-dev \
  libsoup-3.0-dev \
  libjavascriptcoregtk-4.1-dev \
  libwebkit2gtk-4.1-dev \
  build-essential \
  curl wget file \
  libxdo-dev \
  libssl-dev \
  libgtk-3-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  gnome-video-effects \
  libglib2.0-dev \
  libgirepository1.0-dev \
  pkg-config
```

Then try building again with `NO_STRIP=true`.

**Solution 3: Use DEB Format Instead**

DEB packages are more stable on Debian-based systems:

```bash
pake https://example.com --name MyApp --targets deb
```

**Solution 4: Use Docker**

Build in a clean environment without installing dependencies:

```bash
docker run --rm -v $(pwd)/output:/app/output \
  ghcr.io/tw93/pake:latest \
  pake https://example.com --name MyApp --targets appimage
```

**Why This Happens:**

This is a known issue with Tauri's linuxdeploy tool, which can fail when:

- System libraries have incompatible formats for stripping
- Building on newer distributions (Arch, Debian Trixie, etc.)
- Missing WebKit2GTK or GTK development libraries

The `NO_STRIP=true` environment variable is the official workaround recommended by the Tauri community.

---

### Linux: "cargo: command not found" After Installing Rust

**Problem:**
You installed Rust but Pake still reports "cargo: command not found".

**Solution:**

Pake CLI automatically reloads the Rust environment, but if issues persist:

```bash
# Reload environment in current terminal
source ~/.cargo/env

# Or restart your terminal
```

Then try building again.

---

### macOS: Build Fails with Module Compilation Errors

**Problem:**
On macOS 26 Beta or newer, you may see errors related to `CoreFoundation` or `_Builtin_float` modules.

**Solution:**

Create a configuration file to use compatible SDK:

```bash
cat > src-tauri/.cargo/config.toml << 'EOF'
[env]
MACOSX_DEPLOYMENT_TARGET = "15.0"
SDKROOT = "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk"
EOF
```

This file is already in `.gitignore` and won't be committed.

---

### Windows: Missing Visual Studio Build Tools

**Problem:**
Build fails with errors about missing MSVC or Windows SDK.

**Solution:**

Install Visual Studio Build Tools:

1. Download [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022)
2. During installation, select "Desktop development with C++"
3. For ARM64 support: Also select "MSVC v143 - VS 2022 C++ ARM64 build tools" under Individual Components

---

## Runtime Issues

### App Window is Too Small/Large

**Solution:**

Specify custom dimensions when building:

```bash
pake https://example.com --width 1200 --height 800
```

See [CLI Usage Guide](cli-usage.md#window-options) for all window options.

---

### App Icon Not Showing Correctly

**Problem:**
Custom icon doesn't appear or shows default icon.

**Solution:**

Ensure you're using the correct icon format for your platform:

- **macOS**: `.icns` format
- **Windows**: `.ico` format
- **Linux**: `.png` format

```bash
# macOS
pake https://example.com --icon ./icon.icns

# Windows
pake https://example.com --icon ./icon.ico

# Linux
pake https://example.com --icon ./icon.png
```

Pake can automatically convert icons, but providing the correct format is more reliable.

---

### Website Features Not Working (Login, Upload, etc.)

**Problem:**
Some website features don't work in the Pake app.

**Solution:**

This is usually due to web compatibility issues. Try:

1. **Set custom User Agent:**

   ```bash
   pake https://example.com --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
   ```

2. **Inject custom JavaScript:**

   ```bash
   pake https://example.com --inject ./fix.js
   ```

3. **Check if the site requires specific permissions** that may not be available in WebView

---

## Installation Issues

### Permission Denied When Installing Globally

**Problem:**
`npm install -g pake-cli` fails with permission errors.

**Solution:**

Use one of these approaches:

```bash
# Option 1: Use npx (no installation needed)
npx pake-cli https://example.com

# Option 2: Fix npm permissions
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g pake-cli

# Option 3: Use pnpm (recommended)
pnpm install -g pake-cli
```

---

## Getting Help

If your issue isn't covered here:

1. Check the [CLI Usage Guide](cli-usage.md) for detailed parameter documentation
2. See [Advanced Usage](advanced-usage.md) for prerequisites and system setup
3. Search [existing GitHub issues](https://github.com/tw93/Pake/issues)
4. [Open a new issue](https://github.com/tw93/Pake/issues/new) with:
   - Your OS and version
   - Node.js and Rust versions (`node --version`, `rustc --version`)
   - Complete error message
   - Build command you used