Cross Platform Build Targeting

cross-platform-build-targeting

Summary

Configure multi-stage Docker builds with platform-specific runtime targets to enable a Windows-only .NET Framework 4.8 GUI application (AirdPro) to execute on macOS and Linux hosts. This skill pairs application compilation in a build stage with Wine runtime environments, producing separate optimized image targets for Windows native, Linux GUI via X11, CLI-only batch processing, and development modes.

When to use

You have a Windows-only .NET Framework application that must run on non-Windows hosts (macOS or Linux), and you need reproducible, isolated execution with support for both interactive GUI and batch CLI workflows. Apply this skill when Docker multi-stage builds and Wine compatibility layers are preferable to native cross-compilation or maintaining separate codebases.

When NOT to use

• The source application is already natively compiled for Linux, macOS, or uses .NET Core/.NET 5+ (which have native cross-platform support); use native builds instead.
• The application requires hardware features (e.g., GPU acceleration, USB device passthrough) that Wine does not reliably expose.
• Performance-critical scenarios where Wine's emulation overhead (typically 10–30%) is unacceptable; consider native porting or lower-level virtualization.

Inputs

• C# source code for .NET Framework 4.8 GUI application (AirdPro)
• Dockerfile template with multi-stage build configuration
• docker-compose.yml with resource limits and volume bindings
• Build orchestration script (e.g., build-docker.sh)
• Wine prefix initialization scripts and .NET Framework 4.8 installer

Outputs

• Docker image tagged runtime-windows (Windows native container target)
• Docker image tagged runtime-linux (Linux with Wine and X11 GUI support)
• Docker image tagged runtime-cli (Linux CLI-only variant)
• Docker image tagged runtime-dev (development mode with debugging tools)
• docker-compose.yml with validated service definitions and resource constraints
• Build log confirming all targets compile without error

How to apply

Create a multi-stage Dockerfile where the build stage installs the .NET Framework SDK, compiles the C# application from source, and produces application binaries; the runtime stage downloads Ubuntu 22.04, installs Wine and Windows compatibility libraries, initializes a Wine prefix with .NET Framework 4.8 runtime, and configures environment variables (especially DISPLAY for X11 GUI support). Define separate build targets (runtime-windows, runtime-linux, runtime-cli, runtime-dev) in the Dockerfile using BuildKit conditional logic or multiple FROM statements. Enable DOCKER_BUILDKIT=1, set resource limits (8GB memory, 4 CPU cores) in docker-compose.yml, and test each target by invoking the build script (e.g., build-docker.sh) to verify compilation and runtime configuration. For GUI execution on macOS/Linux, bind XQuartz socket and set X11 permissions (xhost +local:docker) on the host. Validate by running configuration tests and confirming all targets build without error and execute expected commands.

Related tools

• Docker Desktop for Mac (Container runtime and multi-stage build orchestration on macOS hosts; version 20.10+ required) — https://www.docker.com/products/docker-desktop
• Docker Engine (Container runtime for Linux hosts; builds and executes multi-stage Docker images) — https://docs.docker.com/engine/
• Wine (Compatibility layer in runtime stage to execute Windows binaries and .NET Framework on Linux; initialized with prefix and environment configuration) — https://www.winehq.org/
• .NET Framework 4.8 (Runtime installed in Wine prefix to execute the compiled C# application (AirdPro))
• XQuartz (X11 server on macOS for forwarding GUI display from Docker container to host desktop)
• ProteoWizard (msConvert library (pwiz_bindings_cli.dll) linked by AirdPro for vendor file format conversion) — https://proteowizard.sourceforge.io/
• C# (Source language of AirdPro application; compiled in build stage)

Examples

export DOCKER_BUILDKIT=1 && docker build --target=runtime-linux -t airdpro:linux . && docker run --rm -e DISPLAY=host.docker.internal:0 -v /tmp/.X11-unix:/tmp/.X11-unix airdpro:linux wine /app/AirdPro.exe

Evaluation signals

• All four Docker image targets (runtime-windows, runtime-linux, runtime-cli, runtime-dev) build without compilation errors; docker build --target= completes successfully.
• Docker image introspection confirms Wine is installed, .NET Framework 4.8 runtime is present in the Wine prefix, and environment variables (WINEARCH, WINEPREFIX, DISPLAY) are correctly set: docker inspect <image_id> --format='{{json .Config.Env}}'
• Configuration test passes when executed: container successfully invokes the compiled application binary and reports expected version/help output.
• GUI target runs without X11/DISPLAY errors when XQuartz is configured on macOS (xhost +local:docker) and container is launched with -e DISPLAY=host.docker.internal:0 and socket binding.
• Resource limits are enforced: docker stats shows memory usage ≤ 8GB and CPU count ≤ 4 cores when running the container; no OOM kills or throttling occur during typical batch conversion workloads.

Limitations

• Wine emulation introduces performance overhead (typically 10–30%) compared to native execution; not suitable for real-time or latency-sensitive operations.
• Wine does not reliably support all Windows system calls, COM interfaces, or graphics features; complex GUI elements (e.g., WinForms with custom rendering) may render incorrectly or not at all.
• X11 forwarding for GUI requires XQuartz (macOS) or Xvfb/similar (Linux headless) to be pre-configured on the host; network X11 forwarding has security and performance implications.
• The multi-stage build significantly increases Docker image size (~2–5 GB) due to SDK, compilation artifacts, Wine, and .NET Framework runtime; initial build time can exceed 10–30 minutes.
• Wine prefix initialization is one-time; changes to .NET Framework settings or Windows registry modifications inside the container do not persist unless volumes are properly bound or the image is rebased.

Evidence

• [other] AirdPro is a C# GUI client written for .NET Framework 4.8 that requires a multi-stage Docker build configuration pairing application compilation with Wine runtime to run Windows applications in Linux containers, enabling execution on non-Windows hosts.: "C# GUI client written for .NET Framework 4.8 that requires a multi-stage Docker build configuration pairing application compilation with Wine runtime to run Windows applications in Linux containers"
• [other] Create a multi-stage Dockerfile with a build stage that downloads Ubuntu 22.04 base image, installs .NET Framework SDK, and compiles the AirdPro C# application from source.: "multi-stage Dockerfile with a build stage that downloads Ubuntu 22.04 base image, installs .NET Framework SDK, and compiles the AirdPro C# application from source"
• [other] Add Wine and required Windows compatibility libraries to the runtime stage. Install .NET Framework 4.8 runtime into the Wine environment.: "Add Wine and required Windows compatibility libraries to the runtime stage. Install .NET Framework 4.8 runtime into the Wine environment."
• [other] Define separate runtime targets for Windows native containers, Linux-based Wine execution, CLI-only variant, and development mode.: "Define separate runtime targets for Windows native containers, Linux-based Wine execution, CLI-only variant, and development mode."
• [other] Enable BuildKit optimization and configure resource limits in docker-compose.yml for memory (8GB) and CPU (4 cores).: "Enable BuildKit optimization and configure resource limits in docker-compose.yml for memory (8GB) and CPU (4 cores)."
• [other] Test the multi-stage build by invoking build-docker.sh script to verify all target stages compile without error. Validation: confirm all Docker image targets (runtime-windows, runtime-linux, runtime-cli, runtime-dev) build successfully and run configuration test passes.: "invoking build-docker.sh script to verify all target stages compile without error. Validation: confirm all Docker image targets (runtime-windows, runtime-linux, runtime-cli, runtime-dev) build"
• [methods] Download and install Docker Desktop for Mac: "Download and install Docker Desktop for Mac"
• [methods] Install XQuartz using Homebrew: "Install XQuartz using Homebrew"
• [methods] Check 'Allow connections from network clients' in Security tab: "Check 'Allow connections from network clients' in Security tab"
• [readme] AirdPro is a GUI client for conversion from vendor files to Aird files: "AirdPro is a GUI client for conversion from vendor files to Aird files"
• [readme] AirdPro is written in C# and is based on pwiz_bindings_cli.dll from the ProteoWizard project.: "written in C# and is based on pwiz_bindings_cli.dll from the ProteoWizard project"