diff --git a/README.md b/README.md index ff43049..9495615 100644 --- a/README.md +++ b/README.md @@ -104,6 +104,7 @@ sudo dnf install libX11-devel libXrandr-devel libXcursor-devel libXi-devel mesa- ## Documentation - [Getting Started Guide](docs/GETTING_STARTED.md) +- [FAQ - Visual Studio Integration](docs/FAQ.md) - [API Reference](docs/API.md) - [Contributing Guide](CONTRIBUTING.md) diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000..56d77a9 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,307 @@ +# Frequently Asked Questions + +## Visual Studio Integration + +### How do I add Linux support to my existing MAUI project? + +Unlike Android, iOS, and Windows which appear in Visual Studio's platform dropdown, Linux requires manual configuration since it's a community platform. + +**Step 1: Add the NuGet Package** + +```bash +dotnet add package OpenMaui.Controls.Linux --prerelease +``` + +Or in Visual Studio: Right-click project → Manage NuGet Packages → Search "OpenMaui.Controls.Linux" + +**Step 2: Create a Linux Startup Project** + +Create a new folder called `Platforms/Linux` in your project and add a `Program.cs`: + +```csharp +using OpenMaui.Platform.Linux; + +namespace MyApp.Platforms.Linux; + +public class Program +{ + public static void Main(string[] args) + { + var app = new LinuxApplication(); + app.MainPage = new MainPage(); // Your existing MainPage + app.Run(); + } +} +``` + +**Step 3: Add a Linux Build Configuration** + +Add to your `.csproj`: + +```xml + + linux-x64 + +``` + +Or create a separate `MyApp.Linux.csproj` that references your shared code. + +--- + +### Why doesn't Linux appear in Visual Studio's platform dropdown? + +Visual Studio's MAUI tooling only shows platforms officially supported by Microsoft (.NET MAUI team). Linux is a community-supported platform through OpenMaui. + +**Workarounds:** + +1. **Use a separate Linux project** - Create a dedicated `MyApp.Linux` console project +2. **Use VS Code** - Better cross-platform support with command-line builds +3. **Use JetBrains Rider** - Excellent Linux and cross-platform support +4. **Command line** - `dotnet build -r linux-x64` works from any IDE + +--- + +### How do I build for Linux from Visual Studio on Windows? + +**Option A: Command Line (Recommended)** + +Open Terminal in VS and run: +```bash +dotnet build -c Release -r linux-x64 +dotnet publish -c Release -r linux-x64 --self-contained +``` + +**Option B: Custom Build Profile** + +1. Right-click solution → Properties → Configuration Manager +2. Create a new configuration called "Linux" +3. Edit project properties to set RuntimeIdentifier for this configuration + +**Option C: WSL Integration** + +If you have WSL (Windows Subsystem for Linux) installed: +```bash +wsl dotnet build +wsl dotnet run +``` + +--- + +### How do I debug Linux apps from Windows? + +**Option 1: Remote Debugging** + +1. Install `vsdbg` on your Linux machine +2. Configure remote debugging in VS/VS Code +3. Attach to the running process + +**Option 2: WSL (Recommended for development)** + +1. Install WSL 2 with Ubuntu +2. Install .NET SDK in WSL +3. Run your app in WSL with X11 forwarding: + ```bash + export DISPLAY=:0 + dotnet run + ``` +4. Use WSLg (Windows 11) for native GUI support + +**Option 3: Virtual Machine** + +1. Set up a Linux VM (VMware, VirtualBox, Hyper-V) +2. Share your project folder +3. Build and run inside the VM + +--- + +## Project Structure + +### What's the recommended project structure for cross-platform MAUI with Linux? + +``` +MyApp/ +├── MyApp.sln +├── MyApp/ # Shared MAUI project +│ ├── MyApp.csproj +│ ├── App.xaml +│ ├── MainPage.xaml +│ ├── Platforms/ +│ │ ├── Android/ +│ │ ├── iOS/ +│ │ ├── Windows/ +│ │ └── Linux/ # Add this folder +│ │ └── Program.cs +│ └── ... +└── MyApp.Linux/ # Optional: Separate Linux project + ├── MyApp.Linux.csproj + └── Program.cs +``` + +### Should I use a separate project or add Linux to my existing project? + +**Add to existing project** if: +- You want a single codebase +- Your MAUI code is mostly XAML-based +- You're comfortable with conditional compilation + +**Use a separate project** if: +- You want cleaner separation +- You need Linux-specific features +- You want independent build/deploy cycles +- Your team includes Linux specialists + +--- + +## Build & Deploy + +### How do I create a Linux executable? + +```bash +# Self-contained (includes .NET runtime) +dotnet publish -c Release -r linux-x64 --self-contained -o ./publish + +# Framework-dependent (smaller, requires .NET on target) +dotnet publish -c Release -r linux-x64 --no-self-contained -o ./publish +``` + +For ARM64 (Raspberry Pi, etc.): +```bash +dotnet publish -c Release -r linux-arm64 --self-contained -o ./publish +``` + +### How do I create a .deb or .rpm package? + +We recommend using packaging tools: + +**For .deb (Debian/Ubuntu):** +```bash +dotnet tool install -g dotnet-deb +dotnet deb -c Release -r linux-x64 +``` + +**For .rpm (Fedora/RHEL):** +```bash +dotnet tool install -g dotnet-rpm +dotnet rpm -c Release -r linux-x64 +``` + +**For AppImage (Universal):** +Use [AppImageKit](https://appimage.org/) with your published output. + +**For Flatpak:** +Create a flatpak manifest and build with `flatpak-builder`. + +--- + +## Common Issues + +### "SkiaSharp native library not found" + +Install the required native libraries: + +**Ubuntu/Debian:** +```bash +sudo apt-get install libfontconfig1 libfreetype6 +``` + +**Fedora:** +```bash +sudo dnf install fontconfig freetype +``` + +### "Cannot open display" or "No display server" + +Ensure X11 or Wayland is running: +```bash +echo $DISPLAY # Should show :0 or similar +echo $WAYLAND_DISPLAY # For Wayland +``` + +For headless/SSH sessions: +```bash +export DISPLAY=:0 # If X11 is running +``` + +### "libX11.so not found" + +Install X11 development libraries: + +**Ubuntu/Debian:** +```bash +sudo apt-get install libx11-6 libx11-dev +``` + +### App runs but window doesn't appear + +Check if you're running under Wayland without XWayland: +```bash +# Force X11 mode +export GDK_BACKEND=x11 +./MyApp +``` + +--- + +## IDE Recommendations + +### What's the best IDE for developing MAUI apps with Linux support? + +| IDE | Linux Dev | Windows Dev | Pros | Cons | +|-----|-----------|-------------|------|------| +| **VS Code** | ⭐⭐⭐ | ⭐⭐⭐ | Cross-platform, lightweight, great C# extension | No visual XAML designer | +| **JetBrains Rider** | ⭐⭐⭐ | ⭐⭐⭐ | Excellent cross-platform, powerful refactoring | Paid license | +| **Visual Studio** | ⭐ | ⭐⭐⭐ | Best MAUI tooling on Windows | No native Linux support | +| **Visual Studio Mac** | ⭐⭐ | N/A | Good MAUI support | macOS only | + +**Our recommendation:** +- **Windows developers:** Visual Studio for Android/iOS/Windows, VS Code or command line for Linux builds +- **Linux developers:** JetBrains Rider or VS Code +- **Cross-platform teams:** VS Code with standardized build scripts + +--- + +## Continuous Integration + +### How do I set up CI/CD for Linux builds? + +**GitHub Actions example:** + +```yaml +jobs: + build-linux: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-dotnet@v4 + with: + dotnet-version: '9.0.x' + + - name: Install dependencies + run: | + sudo apt-get update + sudo apt-get install -y libx11-dev libfontconfig1-dev + + - name: Build + run: dotnet build -c Release + + - name: Publish + run: dotnet publish -c Release -r linux-x64 --self-contained -o ./publish + + - name: Upload artifact + uses: actions/upload-artifact@v4 + with: + name: linux-app + path: ./publish +``` + +--- + +## Getting Help + +- **GitHub Issues:** https://github.com/open-maui/maui-linux/issues +- **Discussions:** https://github.com/open-maui/maui-linux/discussions +- **Documentation:** https://github.com/open-maui/maui-linux/tree/main/docs + +--- + +*Developed by [MarketAlly LLC](https://marketally.com) • Lead Architect: David H. Friedel Jr.*