빌드 스위치
이 문서는 MewUI 기능을 켜고 끄는 MSBuild 속성, 각 속성이 설정하는 런타임 스위치, 그리고 트림·NativeAOT 게시에 미치는 영향을 정리한다.
1. 동작 방식
섹션 제목: “1. 동작 방식”모든 스위치는 앱 프로젝트의 MSBuild 속성이다. 빌드 로직은 Aprillz.MewUI.Core 패키지에 들어 있으므로 어떤 MewUI 패키지 조합에서도 동작한다.
<PropertyGroup> <MewUIWin32TextEngine>Gdi</MewUIWin32TextEngine></PropertyGroup>명령줄로도 전달할 수 있다: dotnet publish -p:MewUIWin32TextEngine=Gdi.
빌드 시 각 속성은 runtimeconfig.json에 AppContext 스위치로 기록되고, MewUI는 시작할 때 그 스위치를 한 번 읽는다. 대부분의 스위치는 트리머에도 전달되므로, 트림·NativeAOT 게시에서는 선택하지 않은 쪽의 코드가 비활성화되는 데 그치지 않고 출력에서 제거된다.
| 속성 | 값 | 기본값 | 런타임 스위치 | 끄면 트림으로 제거 |
|---|---|---|---|---|
MewUIBackend |
Direct2D, Gdi, MewVG |
모든 백엔드 | 없음 (게시 필터) | 해당 없음 |
MewUIWin32TextEngine |
DirectWrite, Gdi |
DirectWrite |
Aprillz.MewUI.Win32.DirectWriteText.Enabled |
예, 선택하지 않은 경로 |
MewUIManagedFileDialogs |
true, false |
true |
Aprillz.MewUI.ManagedFileDialogs.Enabled |
예 |
MewUIDevTools |
true, false |
Debug는 true, Release는 false |
Aprillz.MewUI.DevTools.Enabled |
예 |
MewUIHotReload |
true, false |
true |
Aprillz.MewUI.HotReload.Enabled |
아니오 |
MewUIEnvironmentDebugLogging |
true, false |
Debug는 true, Release는 false |
Aprillz.MewUI.EnvironmentDebugLogging.Enabled |
예 |
MewUITouch |
true, false |
true |
Aprillz.MewUI.Touch.Enabled |
예 |
MewUIAutomation |
true, false |
false |
Aprillz.MewUI.Automation.Enabled |
예 |
런타임 스위치가 아니라 MSBuild 속성을 설정한다. runtimeconfig.json을 직접 고치거나 AppContext.SetSwitch로 바꾼 값은 트리머에 전달되지 않으므로, 트림 게시에서는 그 스위치가 요구하는 코드가 이미 제거되어 있을 수 있다.
2. MewUIBackend
섹션 제목: “2. MewUIBackend”메타패키지를 참조하는 앱을 게시할 때 렌더링 백엔드 하나만 남긴다. 값과 예시는 설치 및 패키지 구성을 참고한다.
3. MewUIWin32TextEngine
섹션 제목: “3. MewUIWin32TextEngine”Windows에서는 모든 백엔드가 DirectWrite로 텍스트를 배치하고 래스터화한다. Gdi와 MewVG 백엔드는 이 속성을 Gdi로 지정하면 GDI 텍스트를 쓴다. Direct2D 백엔드는 항상 DirectWrite를 쓰므로 이 속성을 보지 않으며, Linux와 macOS에는 영향이 없다.
<PropertyGroup> <MewUIWin32TextEngine>Gdi</MewUIWin32TextEngine></PropertyGroup>| 값 | 글꼴 매칭 | 컬러 글리프 |
|---|---|---|
DirectWrite (기본값) |
타이포그래픽 패밀리 이름. 한 패밀리의 모든 굵기를 쓸 수 있다 | 있음 (컬러 이모지) |
Gdi (Gdi, MewVG 백엔드만) |
레거시 패밀리 이름 | 없음 |
그 밖의 값을 주면 빌드가 오류로 실패한다.
Gdi로 NativeAOT 게시하면 DirectWrite 텍스트 경로가 빠져 실행 파일이 조금 작아진다. 텍스트를 그리지 않는 앱은 어느 쪽이든 크기가 같다.
4. MewUIManagedFileDialogs
섹션 제목: “4. MewUIManagedFileDialogs”MewUI에는 매니지드 파일·폴더 대화상자가 들어 있고, PreferNative가 false이거나 네이티브 대화상자를 쓸 수 없을 때 사용된다. 네이티브 대화상자만 쓰는 앱은 이 속성을 false로 두어 트림·NativeAOT 게시에서 매니지드 대화상자를 제거할 수 있다.
매니지드 대화상자를 끄면 네이티브 대화상자의 실패는 대체 없이 호출자에게 예외로 전달되고, PreferNative = false 요청은 NotSupportedException을 던진다.
5. MewUIDevTools
섹션 제목: “5. MewUIDevTools”요소 인스펙터, 비주얼 트리 창, 프레임 통계 오버레이, 프로파일러를 켠다. DevTools를 참고한다.
이 도구들은 트림·NativeAOT 게시에 포함되지 않는다. 속성 패널이 리플렉션으로 멤버를 나열하는데 트림이 이를 깨뜨리기 때문이다. MewUIDevTools를 true로 둔 채 그런 앱을 게시하면 도구 없이 게시되고 빌드 경고가 나온다. 같은 앱이라도 dotnet run에서는 도구가 동작한다.
6. MewUIHotReload
섹션 제목: “6. MewUIHotReload”Hot Reload는 선언 없이 dotnet watch나 IDE의 Hot Reload 세션에서 동작한다. 끄려면 속성을 false로 둔다. Hot Reload를 참고한다.
7. MewUIEnvironmentDebugLogging
섹션 제목: “7. MewUIEnvironmentDebugLogging”실행 시 환경 변수로 켜는 진단 로그를 사용할 수 있게 한다. Release에서는 이 속성을 true로 두지 않는 한 로깅 코드가 포함되지 않는다.
앱을 시작하기 전에 변수를 1 또는 true로 설정한다. 로그는 표준 출력과 디버거 출력으로 나간다.
| 변수 | 로그 내용 |
|---|---|
MEWUI_GRAPHICS_DEBUG |
그래픽 컨텍스트 상태 |
MEWUI_IME_DEBUG |
모든 플랫폼의 입력기 동작 |
MEWUI_X11_DEBUG |
X11 오류 |
MEWUI_XI2_DEBUG |
XInput2 이벤트 |
MEWUI_ICON_DEBUG |
Linux 셸 아이콘 조회 |
MEWUI_MACOS_DEBUG |
macOS 창 클래스 등록 |
MEWUI_INTEROP_DEBUG |
macOS 네이티브 인터롭 |
8. MewUITouch
섹션 제목: “8. MewUITouch”Windows, Linux(X11), 브라우저에서 MewUI는 터치 입력을 직접 해석하고, Windows와 브라우저에서는 펜 입력도 직접 해석한다. 탭하면 클릭된다. 손가락을 몇 픽셀 이상 끌면 그 아래 콘텐츠가 스크롤되고, 움직이던 중에 손가락을 떼면 콘텐츠가 잠시 더 미끄러진다. 손가락을 반 초 동안 가만히 누르고 있으면 우클릭이 되어 컨텍스트 메뉴가 열린다. 처음 닿은 손가락만 동작하고 두 번째 손가락은 무시된다. 펜은 마우스처럼 호버, 클릭, 드래그한다. X11에서는 드롭다운 같은 팝업이 열려 있는 동안 터치가 마우스 입력으로 들어오므로, 손가락으로 항목을 탭하고 스크롤 막대를 끌 수는 있지만 목록을 끌어 스크롤할 수는 없다.
속성을 false로 두면 트림·NativeAOT 게시에서 이 기능이 제거되어 Windows에서 약 21 KB가 줄어든다. 이때 터치와 펜은 운영체제나 X 서버가 마우스 입력으로 바꿔 보내는 대로 들어온다. 탭은 여전히 클릭되지만 끌기는 스크롤 대신 선택이나 드래그가 되고, Windows에서는 우클릭을 시스템의 길게 누르기가 맡는다.
9. MewUIAutomation
섹션 제목: “9. MewUIAutomation”속성을 true로 두면 오토메이션 트리가 만들어진다. 표준 컨트롤마다 오토메이션 피어가 생겨 역할(버튼, 편집 상자, 목록, 목록 항목, 메뉴 항목 등), 이름, 상태, 지원하는 동작을 알려 준다. 동작은 실행, 토글, 값 설정, 선택, 펼치기와 접기, 스크롤이다. 코드는 UIElement.GetAutomationPeer()로 트리를 읽고 GetChildren()과 GetParent()로 탐색하며, 동작은 GetProvider<T>()로 얻는다(예: GetProvider<IInvokeProvider>()). 동작은 사용자 입력과 같은 경로로 실행되므로 클릭이나 키 입력처럼 바인딩에 값을 반영하고 명령을 실행한다.
컨트롤의 이름은 AutomationProperties.Name을 설정했으면 그 값이고, 아니면 AutomationProperties.LabeledBy가 가리키는 요소의 텍스트, 그것도 없으면 컨트롤 자신의 텍스트다. 버튼은 내용, 텍스트 상자는 플레이스홀더, 탭은 헤더, 메뉴 항목은 액세스 키 표시를 뺀 텍스트를 쓴다. 패널과 테두리는 트리에 나타나지 않고 그 자식이 그 자리에 보인다. AutomationProperties.AccessibilityView를 Raw로 두면 요소가 트리에서 빠진다. 드롭다운 목록이나 메뉴처럼 창에 열린 팝업은 창의 자식이다.
키보드 포커스는 키보드가 실제로 다루는 부분에 있다고 알린다. 포커스를 가진 목록, 트리, 그리드에서는 선택된 항목이, 열린 메뉴에서는 강조된 항목이 포커스를 가진다. 메뉴와 툴팁이 열리고 닫히는 것도 알린다. 편집 상자는 스크린리더가 글자, 단어, 줄 단위로 텍스트를 읽고 캐럿과 선택을 따라갈 수 있게 한다.
이 트리는 운영체제의 접근성 인터페이스로 내보내져 스크린리더와 오토메이션 도구가 창의 컨트롤을 읽고 조작한다. Windows는 UI 오토메이션(내레이터, Accessibility Insights, FlaUI), macOS는 NSAccessibility(VoiceOver, Accessibility Inspector), Linux(X11, 프레임버퍼)는 AT-SPI2(Orca, Accerciser)다. Windows에서는 클라이언트가 창의 트리를 처음 요청하기 전에는 아무것도 준비하지 않는다. Linux에서는 세션의 접근성이 켜져 있을 때, 시작할 때든 나중에 스크린리더가 켜질 때든, 접근성 버스에 애플리케이션을 등록한다. 드롭다운 목록이나 메뉴처럼 자체 팝업 창에 뜨는 팝업은 그 팝업 창의 트리에 있다. 브라우저 플랫폼은 트리를 내보내지 않는다.
기본값 false에서는 GetAutomationPeer()가 null을 돌려주고, 트림·NativeAOT 게시에서 오토메이션 코드가 빠진다.