> ## Documentation Index > Fetch the complete documentation index at: https://docs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # GDKX 헤더 및 라이브러리 디렉터리 구조 > GDKX 헤더 및 라이브러리의 새 디렉터리 레이아웃을 설명합니다. > [!NOTE] > > 이 문서에서 설명하는 디렉터리 구조는 2025년 10월 GDK에서 도입된 **간소화된(크로스 플랫폼) 레이아웃**입니다. > > 2026년 10월 GDK부터는 간소화된 레이아웃이 기본적으로 설치됩니다. 레거시 레이아웃은 추가 마이그레이션 시간이 필요한 팀을 위해 사용되지 않는 선택적 호환성 경로로 계속 제공됩니다. > > 레거시 레이아웃은 2027년 4월 GDK 릴리스부터 더 이상 지원되지 않으며 설치 프로그램에서 제거됩니다. 현재 버전의 Microsoft Game Development Kit (GDK)에서 레이아웃은 코드 공유를 중심으로 최적화되었으며 특정 플랫폼에 초점을 맞추었습니다. 이 레이아웃의 빌드 통합은 MSBuild 사용자 지정 플랫폼에 복잡성을 숨기는 방식에 크게 의존했습니다. 새 레이아웃에서는 통합을 간소화하고, 점점 늘어나는 대상 플랫폼 목록을 지원하며, 기본 MSBuild 플랫폼과 Microsoft 이외의 빌드 시스템 모두에 대한 지원을 개선하는 데 중점을 둡니다. ## 이전 헤더 및 라이브러리 레이아웃 Microsoft GDK의 기존 파일 레이아웃은 다음과 같이 요약됩니다. ```text theme={null} 251000\ GRDK\ ExtensionLibraries\ Xbox.Services.API.C\ ExtensionLibrary.props DesignTime\CommonConfiguration\Neutral\ Include\ Lib\ Redist\ ... GameKit\ Include\ Lib\ amd64\ ``` ```text theme={null} GXDK\ gameKit\ Include\ XboxOne\ Scarlett\ Lib\ amd64\ XboxOne\ Scarlett\ ToolKit\ Include\ XboxOne\ Scarlett\ Lib\ amd64\ XboxOne\ Scarlett\ ``` **Gaming.Desktop.x64**, **Gaming.Xbox.Scarlett.x64**, **Gaming.Xbox.XboxOne.x64** 사용자 지정 MSBuild 플랫폼은 이 모든 콘텐츠를 다양한 방식으로 결합하는 include/lib 경로를 빌드하는 논리를 구현합니다. CMake 또는 사용자 지정 make 솔루션을 사용한 경우 이 논리를 해당 솔루션에서도 구현해야 했습니다. 자세한 예제는 [CMakeExample](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeExample)의 2025년 4월 버전을 참조하세요. 2025년 10월 및 2026년 4월 GDK 릴리스에는 간소화된 레이아웃과 레거시 레이아웃이 모두 포함되어 있습니다. 2026년 10월 GDK부터 설치 프로그램은 기본적으로 간소화된 레이아웃만 설치합니다. 레거시 레이아웃은 여전히 선택적 설치로 선택할 수 있지만 사용되지 않으며 더 이상 권장되는 개발 경로가 아닙니다. 레거시 레이아웃은 2027년 4월 GDK 릴리스부터 더 이상 지원되지 않으며 설치 프로그램에서 제거됩니다. ## 새 헤더 및 라이브러리 레이아웃 2025년 10월 GDK 릴리스에서는 헤더와 라이브러리에 대한 대체 레이아웃을 제공하여 플랫폼 통합을 훨씬 더 쉽게 만들고 시간이 지남에 따라 추가 플랫폼을 수용할 수 있도록 합니다. ```text theme={null} 251000\ windows\ bin\ arm64 x64\ include\ lib\ arm64 x64\ redist xbox\ bin\ gen8\ gen9\ devpctools\ gen8\ gen9\ x64\ x64\ build\ include\ lib\ redist\ source\ ``` ## MSBuild 사용자 지정 플랫폼에서 새 레이아웃 사용 기존 **Gaming.\*.x64** MSBuild 플랫폼은 기본적으로 이전 레이아웃을 사용하지만, **GDKCrossPlatform** 속성을 설정하여 새 레이아웃을 옵트인할 수 있습니다. ```xml theme={null} ... true ``` 이렇게 하면 이전 레이아웃에서 사용하던 다양하고 복잡한 경로 대신 적절한 include/lib 경로가 프로젝트에 추가됩니다. 이 새로운 간소화된 통합에서는 확장 라이브러리 메커니즘이 더 이상 사용되지 않습니다. 기본적으로 모든 콘텐츠를 빌드 시 include/lib 경로에서 사용할 수 있습니다. 그런 다음 프로젝트는 사용하는 추가 라이브러리에 연결해야 합니다. 이전 GDK 프로젝트 템플릿을 기반으로 빌드된 프로젝트에는 다음과 같은 문이 포함되어 있어야 합니다. ```xml theme={null} uuid.lib;$(Console_Libs);%(XboxExtensionsDependencies);%(AdditionalDependencies) ``` 새 레이아웃의 경우 **Console\_Libs** 속성에 필수 핵심 라이브러리가 나열됩니다. | 플랫폼 | 핵심 라이브러리 | | - | - | | Gaming.\*.x64 | xgameruntime.lib d3d12.lib dxguid.lib dxgi.lib gameinput.lib | | Gaming.Xbox.Scarlett.x64 | xgameruntime.lib xgameplatform.lib d3d12\_xs.lib xg\_xs.lib pixevt.lib xmem.lib | | Gaming.Xbox.XboxOne.x64 | xgameruntime.lib xgameplatform.lib d3d12\_x.lib xg\_x.lib pixevt.lib xmem.lib | 확장 라이브러리는 각각 '옵트인' 방식이므로 프로젝트에서 사용하는 확장 라이브러리를 **AdditionalDependencies**에 추가해야 합니다. | 플랫폼 | 핵심 라이브러리 | | - | - | | Xbox.LibHttpClient | libHttpClient.lib | | Xbox.XCurl.API | XCurl.lib | | Xbox.Game.Chat.2.Cpp.API | GameChat2.lib | | Xbox.Services.API.C (Debug) | Appnotify.lib winhttp.lib crypt32.lib Microsoft.Xbox.Services.142.C.Debug.lib | | Xbox.Services.API.C (Release) | Appnotify.lib winhttp.lib crypt32.lib Microsoft.Xbox.Services.142.C.lib | | PlayFab.Party.Cpp | Party.lib | | PlayFab.PartyXboxLive.Cpp | PartyXboxLive.lib | | PlayFab.Services.C | PlayFabCore.lib PlayFabGameSave.lib PlayFabServices.lib | | PlayFab.Multiplayer.Cpp | PlayFabMultiplayer.lib | 또한 프로젝트는 사용하는 추가 DLL을 레이아웃에 복사해야 합니다. 이 작업은 많은 DLL 라이브러리 통합에서 일반적으로 사용되는 사용자 지정 빌드 단계를 통해 수행하거나, vcxproj를 편집하거나 props 파일을 추가하여 **ReferenceCopyLocalPaths** 항목 그룹 목록을 사용하여 수행할 수 있습니다. 아래 MSBuild에는 가능한 모든 DLL이 나열되어 있지만 개별 프로젝트에는 이 중 일부만 필요합니다. ```xml theme={null} $(GameDKCoreLatest) $(GameDKXboxLatest) ``` > [!NOTE] > > `GameDKLatest`는 Microsoft GDK with XBOX Extensions에서만 설정됩니다. 따라서 두 버전의 Microsoft GDK를 나란히 설치하는 것을 완벽하게 지원하는 새 환경 변수를 도입했습니다. `GameDKCoreLatest`는 Microsoft GDK에서 설정됩니다. `GameDKXboxLatest`는 Microsoft GDK with XBOX Extensions에서 설정됩니다. ### Directory.Build.props 사용 새 레이아웃을 사용하여 기존 GDK Gaming.\*.x64 프로젝트를 빠르게 검증하는 방법으로, 소스 트리의 Directory.Build.props라는 파일에 다음 내용을 넣습니다. 이렇게 하면 새 레이아웃이 옵트인되며, 프로젝트에서 사용하지 않더라도 대부분 또는 모든 확장 라이브러리가 포함됩니다. > [!NOTE] > > **GDKCrossPlatform**을 true로 설정하여 빌드하는 경우 MSBuild 규칙은 **GDKExtLibNames** 속성을 사용하지 않습니다. 이 속성은 이전 MSBuild 규칙으로 빌드할 때 이미 존재하므로, 이 props 파일에서는 레이아웃에 일부 추가 DLL을 옵트인하는 방법으로 사용됩니다. ```xml theme={null} true $(GameDKCoreLatest) $(GameDKXboxLatest) Appnotify.lib;winhttp.lib;crypt32.lib;libHttpClient.lib;XCurl.lib;GameChat2.lib;PlayFabCore.lib;PlayFabServices.lib;PlayFabMultiplayer.lib;Party.lib;PartyXboxLive.lib;PlayFabGameSave.lib Microsoft.Xbox.Services.142.C.Debug.lib;$(AllExtensionLibs) Microsoft.Xbox.Services.142.C.lib;$(AllExtensionLibs) $(AllExtensionLibs);%(AdditionalDependencies) $(AllExtensionLibs);%(XboxExtensionsDependencies) ``` ## MSBuild x64 플랫폼에서 새 레이아웃 사용 **Gaming.Desktop.x64** 플랫폼을 사용하는 대신 기본 **x64** 플랫폼을 사용하여 PC용으로 빌드할 수 있습니다. 이전 레이아웃에서는 [Microsoft Game Development Kit (GDK)에서 x64 플랫폼 사용](https://docs.xbox.com/ko/tools/tools-pc/visualstudio/gr-vs-templates.md#using-the-x64-platform-with-the-microsoft-game-development-kit-gdk)에 자세히 설명된 대로 확장 라이브러리에 대한 `` 문을 추가해야 했습니다. 새 레이아웃에서는 통합 지침이 간소화되었습니다. ```xml theme={null} $(GameDKCoreLatest) $(GameDKXboxLatest) ``` ```xml theme={null} $(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath) $(GDKCrossPlatformPath)windows\Include;$(IncludePath); $(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath) ``` ```xml theme={null} $(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath) $(GDKCrossPlatformPath)windows\Include;$(IncludePath); $(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath) ``` 필요한 모든 확장 라이브러리를 원래 목록과 함께 **AdditionalDependencies**에 추가합니다. ```xml theme={null} xgameruntime.lib;gameinput.lib;d3d12.lib;dxgi.lib;dxguid.lib;uuid.lib;kernel32.lib;user32.lib;%(AdditionalDependencies) ``` 옵트인 확장 라이브러리 DLL은 위와 같이 사용자 지정 빌드 작업을 사용하거나 최종 레이아웃에 **ReferenceCopyLocalPaths** 항목 그룹을 사용하여 바이너리 디렉터리에 복사해야 합니다. **PreprocessorDefinitions** 및 이미지 자산이 포함된 .mgc 파일 처리에 대한 나머지 지침은 변경되지 않습니다. ## CMake에서 새 레이아웃 사용 CMake에서 Microsoft Visual Studio 생성기를 사용하고 **Gaming.\*.x64** 사용자 지정 MSBuild 플랫폼을 사용하는 경우 다음 코드를 사용하여 새 레이아웃을 활성화합니다. ```text theme={null} set_property(TARGET ${PROJECT_NAME} PROPERTY VS_GLOBAL_GDKCrossPlatform "true") ``` [CMakeGDKExample](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeGDKExample)에서 `VS_GLOBAL_GDKExtLibNames` 사용을 제거하고 다음 코드(CMake 3.21 이상 가정)로 바꾸어 사용된 확장 DLL을 레이아웃에 복사합니다. ```text theme={null} add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD COMMAND ${CMAKE_COMMAND} -E $>,copy,true> $ $ COMMAND_EXPAND_LISTS ) ``` ## 사용자 지정 빌드 시스템에서 새 레이아웃 사용 GDK를 사용하여 Windows x64용으로 빌드하려면 다음이 필요합니다. ```cmd theme={null} set INCLUDE=%GameDKXboxLatest%windows\include;%INCLUDE% set LIB=%GameDKXboxLatest%windows\lib\x64;%LIB% set PATH=%GameDK%bin;%GameDKXboxLatest%windows\bin\x64;%PATH% ``` XBOX Series X|S(*Gaming.Xbox.Scarlett.x64*라고도 함)용으로 빌드하려면 다음이 필요합니다. ```cmd theme={null} set INCLUDE=%GameDKXboxLatest%xbox\include\gen9;%GameDKXboxLatest%xbox\include;%INCLUDE% set LIB=%GameDKXboxLatest%xbox\lib\gen9;%GameDKXboxLatest%xbox\lib\x64;%LIB% set PATH=%GameDK%bin;%GameDKXboxLatest%xbox\bin\gen9;%GameDKXboxLatest%xbox\bin\x64;%PATH% ``` XBOX One(*Gaming.Xbox.XboxOne.x64*라고도 함)용으로 빌드하려면 다음이 필요합니다. ```cmd theme={null} set INCLUDE=%GameDKXboxLatest%xbox\include\gen8;%GameDKXboxLatest%xbox\include;%INCLUDE% set LIB=%GameDKXboxLatest%xbox\lib\gen8;%GameDKXboxLatest%xbox\lib\x64;%LIB% set PATH=%GameDK%bin;%GameDKXboxLatest%xbox\bin\gen8;%GameDKXboxLatest%xbox\bin\x64;%PATH% ``` ## PC 콘텐츠 도구에 새 레이아웃 사용 콘솔 개발의 경우 일부 종류의 콘텐츠 '쿠킹'은 XTF API, XMA2 인코딩 라이브러리 및/또는 사용자 지정 Direct3D 12.X 도구를 사용하여 개발 PC에서 수행됩니다. 이 콘텐츠에 액세스하려면 특정 빌드 설정이 필요합니다. XBOX One과 XBOX Series X|S를 모두 대상으로 하는 PC 도구를 빌드하려면 다음이 필요합니다. ```cmd theme={null} set INCLUDE=%GameDKXboxLatest%xbox\include\devpctools;%GameDK%\toolKit\include;%INCLUDE% set LIB=%GameDKXboxLatest%xbox\lib\devpctools\x64;%GameDK%\toolKit\lib\amd64;%LIB% set PATH=%GameDK%bin;%PATH% ``` XBOX Series X|S 그래픽을 대상으로 하는 PC 도구를 빌드하려면 다음이 필요합니다. ```cmd theme={null} set INCLUDE=%GameDKXboxLatest%xbox\include\devpctools\gen9;%GameDKXboxLatest%xbox\include\devpctools;%GameDK%\toolKit\include;%INCLUDE% set LIB=%GameDKXboxLatest%xbox\lib\devpctools\gen9;%GameDKXboxLatest%xbox\lib\devpctools\x64;%GameDK%\toolKit\lib\amd64;%LIB% set PATH=%GameDKXboxLatest%xbox\devpctools\bin\gen9;%GameDK%bin;%PATH% ``` XBOX One 그래픽을 대상으로 하는 PC 도구를 빌드하려면 다음이 필요합니다. ```cmd theme={null} set INCLUDE=%GameDKXboxLatest%xbox\include\devpctools\gen8;%GameDKXboxLatest%xbox\include\devpctools;%GameDK%\toolKit\include;%INCLUDE% set LIB=%GameDKXboxLatest%xbox\lib\devpctools\gen8;%GameDKXboxLatest%xbox\lib\devpctools\x64;%GameDK%\toolKit\lib\amd64;%LIB% set PATH=%GameDKXboxLatest%xbox\devpctools\bin\gen8;%GameDK%bin;%PATH% ``` ## 설치된 파일에서 빌드 에디션 읽기 새 레이아웃에는 `grdk.ini` 또는 `gxdk.ini` 파일이 포함되어 있지 않습니다. 파일을 구문 분석하여 에디션 정보를 찾으려면 `grdk.h` 또는 `gxdk.h`를 사용합니다. 다음은 이전 GDK 릴리스에서도 작동하는 PowerShell 예제입니다. ```powershell theme={null} $result = Get-ChildItem -Path $env:GameDKXboxLatest -Filter "gxdk.h" -Recurse if ($result.Count -eq 0) { $result = Get-ChildItem -Path $env:GXDKLatest -Filter "gxdk.h" -Recurse } if ($result.Count -eq 0) { Write-Error "##[error]Failed to find gxdk.h in either GameDKXboxLatest or GXDKLatest" -ErrorAction Stop } $content = Get-Content -Path $result[0].FullName if (-not ([string]$content -match '#define\s+_GXDK_EDITION\s+([0-9][0-9][0-9][0-9][0-9][0-9])')) { Write-Error "##[error]Failed to find edition define" -ErrorAction Stop } $xbld_edition = $Matches[1] if (-not ([string]$content -match '#define\s+_GXDKVER_PRODUCTBUILDVER_FULL\s+([0-9]+\.[0-9]+\.([0-9]+)\.[0-9]+)')) { Write-Error "##[error]Failed to find full version define" -ErrorAction Stop } $xbld_full_productbuild = $Matches[1] $xbld_build = $Matches[2] if (-not ([string]$content -match '#define\s+_GXDK_MM_NUM\s+([0-9]{1,2})')) { Write-Error "##[error]Failed to find month define" -ErrorAction Stop } $month = $Matches[1] if (-not ([string]$content -match '#define\s+_GXDK_FULLYY\s+([0-9]{4})')) { Write-Error "##[error]Failed to find full year define" -ErrorAction Stop } $year = $Matches[1] Write-Output ("_xbld_name={0} {1} GXDK" -f (Get-Culture).DateTimeFormat.GetMonthName([int]$month), $year) Write-Output ("_xbld_edition={0}" -f $xbld_edition) Write-Output ("_xbld_full_productbuild={0}" -f $xbld_full_productbuild) Write-Output ("_xbld_build={0}" -f $xbld_build) ``` ## 설치 없이 빌드(BWOI) 이전 레이아웃에서 원래 `\flatDeployment` 아래에 있던 MSBuild 사용자 지정 빌드 플랫폼 파일은 이제 단축된 경로로 `\xbox\build` 아래에 있습니다. 예를 들어 VS 2022용 BWOI MSBuild 규칙 폴더를 설정하려면 다음 명령을 사용합니다. ```cmd theme={null} rd /q /s c:\temp\msbuildgdk md c:\temp\msbuildgdk xcopy "%VSInstallDir%\MSBuild\Microsoft\VC" /s c:\temp\msbuildgdk xcopy "%GameDKXboxLatest%\xbox\build\VS2022\gen8" c:\temp\msbuildgdk /s xcopy "%GameDKXboxLatest%\xbox\build\VS2022\gen9" c:\temp\msbuildgdk /s xcopy "%GameDKXboxLatest%\xbox\build\VS2022\pc" c:\temp\msbuildgdk /s ``` 그런 다음 BWOI에 사용되는 Directory.Build.props에서 이 결합된 폴더를 가리키도록 속성을 설정합니다. ```xml theme={null} c:\temp\msbuildgdk\v170\ c:\temp\msbuildgdk\v160\ ``` ## Related topics - [GDK 헤더 및 라이브러리 디렉터리 구조](https://docs.xbox.com/ko/build/gdk-and-engines/guides/gdk-directory-structure.md) - [Linux getting started](https://docs.xbox.com/ko/services/playfab/multiplayer/networking/linux-specific-requirements.md) - [Android 시작하기](https://docs.xbox.com/ko/services/playfab/multiplayer/networking/android-specific-requirements.md) - [PC용 Unreal 개발: 시작하기(이전 버전)](https://docs.xbox.com/ko/build/gdk-and-engines/unreal/unreal-legacy.md) - [XSAPI C 개요](https://docs.xbox.com/ko/services/xbox-services/fundamentals/xbox-services-api/live-xsapi-flat-c.md)