콘텐츠로 이동

설치 및 패키지 구성

이 문서는 MewUI NuGet 패키지의 구성과 설치 방법, publish 시 백엔드 선택 방법을 정리한다.


MewUI는 메타패키지(편의 번들)와 개별 패키지(세분화된 조합)로 구성된다.

Aprillz.MewUI ← 올인원 메타패키지 (모든 플랫폼 + 모든 백엔드)
├─ Aprillz.MewUI.Core ← 코어 (컨트롤, 레이아웃, 마크업, 바인딩)
├─ Aprillz.MewUI.Platform.* ← 플랫폼 호스트
│ ├─ .Platform.Win32
│ ├─ .Platform.X11
│ └─ .Platform.MacOS
└─ Aprillz.MewUI.Backend.* ← 렌더링 백엔드
├─ .Backend.Direct2D (Windows)
├─ .Backend.Gdi (Windows)
├─ .Backend.MewVG.Win32 (Windows, NanoVG/OpenGL)
├─ .Backend.MewVG.X11 (Linux, NanoVG/OpenGL)
└─ .Backend.MewVG.MacOS (macOS, NanoVG/Metal)

별도 관리 패키지 (메타패키지에 포함되지 않음):

  • Aprillz.MewUI.Svg - SVG 파싱/렌더링
  • Aprillz.MewUI.MewDock - Visual Studio 스타일 도킹
  • Aprillz.MewUI.MewCharts - 직교/파이/폴라 차트
  • Aprillz.MewUI.WebView2.Win32 - WebView2 통합 (Windows 전용)
  • Aprillz.MewUI.Skia - SkiaCanvasView. 백엔드별 GPU interop 패키지(.Skia.Interop.Direct2D, .Skia.Interop.Gdi, .Skia.Interop.MewVG.Win32, .Skia.Interop.MewVG.X11, .Skia.Interop.MewVG.MacOS)와 메타패키지 .Skia.Windows, .Skia.Linux, .Skia.MacOS, .Skia.All가 함께 있다
  • Aprillz.MewUI.Platform.Browser - 브라우저 플랫폼 호스트 (WebAssembly, net10.0 전용)
  • Aprillz.MewUI.Backend.MewVG.Browser - 브라우저 호스트용 WebGL 2 렌더링 백엔드
  • Aprillz.MewUI.Templates - 데스크톱 앱과 브라우저 앱용 dotnet new 템플릿 (2.4절)

대부분의 경우 플랫폼별 메타패키지 하나만 추가하면 된다.

대상 플랫폼 패키지 포함 내용
Windows Aprillz.MewUI.Windows Core + Win32 + Direct2D + GDI + MewVG
Linux Aprillz.MewUI.Linux Core + X11 + MewVG
macOS Aprillz.MewUI.MacOS Core + MacOS + MewVG
크로스플랫폼 Aprillz.MewUI 전 플랫폼 + 전 백엔드
터미널 창
# Windows 앱
dotnet add package Aprillz.MewUI.Windows
# 크로스플랫폼 앱
dotnet add package Aprillz.MewUI

패키지 설치만으로는 실행되지 않는다. 앱이 Application.Run 전에 플랫폼 호스트와 렌더링 백엔드를 등록해야 하며, 등록이 없으면 텍스트를 측정하는 첫 컨트롤에서 InvalidOperationException이 발생한다. macOS라면 다음과 같다.

MacOSPlatform.Register();
MewVGMacOSBackend.Register();

Windows, Linux, 브라우저의 등록 코드와 빌더 체인은 Application 수명 주기를 참고한다.

메타패키지 대신 필요한 패키지만 직접 참조할 수 있다.

<ItemGroup>
<PackageReference Include="Aprillz.MewUI.Core" Version="0.21.1" />
<PackageReference Include="Aprillz.MewUI.Platform.Win32" Version="0.21.1" />
<PackageReference Include="Aprillz.MewUI.Backend.Gdi" Version="0.21.1" />
</ItemGroup>

SVG나 WebView2가 필요하면 별도로 추가한다.

터미널 창
dotnet add package Aprillz.MewUI.Svg
dotnet add package Aprillz.MewUI.WebView2.Win32

Aprillz.MewUI.Templates로 만든 프로젝트는 패키지를 이미 참조하고 플랫폼 호스트와 백엔드를 등록한 상태로 시작한다.

터미널 창
dotnet new install Aprillz.MewUI.Templates
# Windows, Linux, macOS용 데스크톱 앱 (Aprillz.MewUI 기반, .NET 8은 -f net8.0)
dotnet new mewui -o MyApp
# WebAssembly 브라우저 앱
dotnet new mewui-browser -o MyBrowserApp

만들어진 프로젝트는 템플릿 패키지와 같은 버전의 MewUI 패키지를 참조한다.

브라우저 앱은 메타패키지 대신 Aprillz.MewUI.Platform.Browser와 Aprillz.MewUI.Backend.MewVG.Browser를 참조한다. 올인원 Aprillz.MewUI에는 이 두 패키지가 들어 있지 않다. 빌드에는 WebAssembly 빌드 도구(dotnet workload install wasm-tools)가 필요하고, 페이지 파일은 앱이 소유한다. 프로젝트 설정과 템플릿이 만드는 파일은 브라우저 부트스트랩을 참고한다.


메타패키지에는 해당 플랫폼의 모든 백엔드가 포함된다. publish 시 MewUIBackend 프로퍼티로 사용할 백엔드 하나만 선택할 수 있다. 미지정 시 모든 백엔드가 publish 출력에 포함된다.

터미널 창
# Direct2D만 포함
dotnet publish -r win-x64 -p:MewUIBackend=Direct2D
# GDI만 포함 (경량)
dotnet publish -r win-x64 -p:MewUIBackend=Gdi
# MewVG만 포함
dotnet publish -r win-x64 -p:MewUIBackend=MewVG
<PropertyGroup>
<MewUIBackend>Direct2D</MewUIBackend>
</PropertyGroup>
<!-- Properties/PublishProfiles/Win-Direct2D.pubxml -->
<Project>
<PropertyGroup>
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
<MewUIBackend>Direct2D</MewUIBackend>
</PropertyGroup>
</Project>
터미널 창
dotnet publish -p:PublishProfile=Win-Direct2D
값 유지되는 백엔드 제거되는 백엔드
Direct2D Backend.Direct2D Backend.Gdi, Backend.MewVG.Win32
Gdi Backend.Gdi Backend.Direct2D, Backend.MewVG.Win32
MewVG Backend.MewVG.* Backend.Direct2D, Backend.Gdi
(미지정) 전부 —

Linux와 macOS는 MewVG 백엔드만 포함하므로 MewUIBackend 설정이 불필요하다.


4. 크로스플랫폼 Publish (Aprillz.MewUI)

섹션 제목: “4. 크로스플랫폼 Publish (Aprillz.MewUI)”

올인원 패키지(Aprillz.MewUI)는 모든 플랫폼의 어셈블리를 포함하지만, dotnet publish -r <rid> 시 대상 플랫폼이 아닌 어셈블리는 자동으로 제외된다.

RID 유지 자동 제거
win-x64 Core, Win32, Direct2D, Gdi, MewVG.Win32 X11, MacOS, MewVG.X11, MewVG.MacOS
linux-x64 Core, X11, MewVG.X11 Win32, MacOS, Direct2D, Gdi, MewVG.Win32, MewVG.MacOS
osx-arm64 Core, MacOS, MewVG.MacOS Win32, X11, Direct2D, Gdi, MewVG.Win32, MewVG.X11

RID 필터링과 MewUIBackend 필터링은 함께 사용할 수 있다.

터미널 창
# Windows + Direct2D만 포함
dotnet publish -r win-x64 -p:MewUIBackend=Direct2D

백엔드 플랫폼 특징
Direct2D Windows GPU 가속, 고품질 텍스트 렌더링. Windows 기본 권장
GDI Windows CPU 기반, 초경량, 최소 의존성
MewVG Windows, Linux, macOS NanoVG 기반 Managed 포트. OpenGL(Win32/X11) 또는 Metal(macOS) 사용

앱 코드에서의 백엔드 등록은 Application Lifecycle을 참고한다.


.NET 10의 파일 기반 앱에서는 #:package 지시어로 패키지를 참조한다.

#:sdk Microsoft.NET.Sdk
#:property OutputType=Exe
#:property TargetFramework=net10.0
#:package Aprillz.MewUI@0.21.1
using Aprillz.MewUI;
using Aprillz.MewUI.Controls;
// ...
Application.Run(window);

  • 모든 MewUI 패키지(Core, Platform., Backend., 메타패키지)는 동일 버전으로 발행된다.
  • 메타패키지 하나만 참조하면 의존 패키지 버전이 자동으로 통일된다.
  • 개별 패키지를 직접 조합할 경우 모든 패키지의 버전을 동일하게 맞춘다.