[ Vulkan 연구 ] HLSL to SPIR-V : 2. DXC 빌드

주의 : 초심자 튜토리얼은 아닙니다. 그러므로, 실제 API 호출 용례를 알고자 한다면, 샘플이나 튜토리얼을 찾아서 확인해 보세요.

주의 : 완전히 이해하고 작성한 글이 아니므로 잘못된 내용이 포함되어 있을 수 있습니다.

주의 : 이상하면 참고자료를 확인하세요.

---

DirectX Shader Compiler( DXC ) 는 High-Level Shader Language( HLSL ) 와 DirectX Intermdiate Language( DXIL ) 관련 컴파일러 및 툴체인을 포함하고 있는 프로젝트입니다.

예전에는 DXSDK 와 Windows 10 SDK 에 "fxc.exe" 라는 실행파일을 배포했었는데, 이제 따로 DXC 라는 이름으로 컴파일러를 배포하고 있더군요. [  DXC 프로젝트 위키 ] 를 보면 다중 플랫폼에 대응하고 개발자들의 열정페이를 촉진하기 위해서 만들어진 것 같습니다.

어쨌든 개발자의 요청 때문인지 HLSL 을 표준 셰이더 언어처럼 만들고자 하는 MS 의 야심때문인지는 모르겠지만, 2018 년 초부터 [ SPIR-V CodeGen ] 이라는 툴을 지원하기 시작했습니다. 따로 툴이 존재하는 것은 아니고 "dxc.exe" 의 파라미터를 통해서 실행됩니다.

\path\to\dxc.exe -spirv -T <target-prfile> -E <entry-point> <hlsl-src-file> -Fo <spirv-bin-file>

이 "dxc.exe" 는 Windows 10 SDK 에 포함되어 있습니다.

즉 배포한 프로그램이 설치된 OS 에는 이 바이너리가 없을 수도 있습니다.

만약 개발자 머신에서만 dxc 를 사용하고, 배포된 프로그램에서는 dxc 가 필요하지 않다면 상관이 없습니다만, 배포된 프로그램에서도 이를 사용해 컴파일을 할 필요가 있다면 같이 배포해 줘야 합니다.

게다가 이 바이너리가 Windows SDK 와 함께 배포되므로 버그 수정과 같은 최신 변경사항에는 대응할 수 없습니다. 디버깅도 불가능하죠. 그러므로 직접 빌드해서 사용하는 것이 여러모로 좋다고 생각합니다.

아래에서는 Visual Studio 2017 을 사용해서 프로젝트를 빌드하는 과정에 대해서 살펴 보도록 하겠습니다. 다른 환경을 사용해서 빌드할 수도 있는데, 그것에 대해 궁금한 점이 있다면 [ 2 ] 를 참조하시기 바랍니다.

GitHub 클론

GitHub 나 GitHub Desktop 에 대한 기본 이해는 있다고 가정하고 진행하겠습니다.

먼저 [ 프로젝트 사이트 ] 로 가서 주소를 복사합니다.

바로 "Open in Desktop" 을 해도 되지만 가끔 실패하는 경우가 있어서 저는 그냥 GitHub Desktop 을 열어서 클론을 했습니다.

파이썬 설치

[ 파이썬 3.x ] 이상을 설치해야 합니다. 중요한 건 반드시 Path 에 파이썬 경로가 포함되어야 한다는 겁니다. 아래 그림에 빨간색 네모로 표시했습니다. 잊지 말아 주세요.

HLSL console 만들기

뭔지는 모르겠지만 HCT 라는 유틸이 있습니다. 제 생각에는 [ Hardware Certification Tool ] 의 머리글자인 것 같습니다.

어쨌든 "$(GitProjectRoot)/utils/hct/hctshortcut.js" 를 윈도우즈 탐색기에서 더블클릭해서 실행하면 바탕화면에 "HLSL console" 이라는 바로가기가 만들어집니다.

이것의 정체를 까 보면 다음과 같습니다.

C:\Windows\System32\cmd.exe /k C:\GIt\DirectXShaderCompiler\utils\hct\hctstart.cmd C:\GIt\DirectXShaderCompiler C:\GIt\hlsl.bin

hctstart 라는 커맨드를 실행하는데, 소스가 있는 폴더인 "DirectXShaderCompiler" 와 "hlsl.bin" 라는 폴더를 인자로 넣습니다.

실행해 보면 "HLSL_SRC_DIR" 과 "HLSL_BLD_DIR" 로 설정됨을 알 수 있습니다.

TAEF 설치

이제 TAEF 라는 것을 설치해야 합니다.

[ Test Authoring and Execution Framework( TAEF ) ] 는 MS 에서 하드웨어 관련 자동화 테스트를 하는 프레임워크인 것 같은데 이것을 설치해야 합니다. 

"$(GitProjectRoot)/utils/hct/hctgettaef.py" 를 실행해서 설치할 수가 있습니다.

아까 만든 "HLSL console" 을 실행해서 다음과 같이 입력합니다. 별다른 반응없이 종료되더군요. 이 작업은 처음 실행했을 때 1 번만 수행하면 된다고 합니다.

방법 1 : hctbuild 를 사용해 CMAKE 솔루션 생성

이제 그 상태에서 바로 "hctbuild" 명령을 실행합니다. 추가 : 이렇게 하면 단순하게 DX 만을 위한 컴파일러가 됩니다. "hctbuild -spirv" 를 입력해야 합니다. 자세한 사항은 [ 3. SPIR-V CodeGen 빌드 ] 에서 확인하시기 바랍니다.

한참을 기다리면, CMAKE 솔루션을 생성하고 빌드까지 합니다. 빌드 경로는 위의 "HLSL_BLD_DIR" 경로입니다. 이것을 고치려면 프로젝트 폴더의 "CMakeSettings.json" 에서 "buildRoot" 항목을 수정하시면 됩니다. 물론 구성별로 전부 수정해야 합니다. 

저같은 경우에는 "x86-Debug" 구성과 "x86-Release" 구성은 아예 지워버렸습니다. 필요하지 않기 때문입니다.

방법 2 : 직접 CMAKE 솔루션 생성

만약 "hctbuild" 를 사용하지 않겠다면, 직접 솔루션을 생성할 수도 있습니다( 직접 해 봤는데 추천하지는 않습니다. CMake 를 여는 데 사용했던 솔루션과 실제 CMAKE 솔루션 사이의 관계에 대한 혼동이 오기 때문입니다. ).

 Visual Studio 2017 은 CMake 에 대한 지원을 내장하고 있습니다. 그러므로 단순하게 프로젝트 폴더의 CMakeList.txt 를 읽어 들임으로써 솔루션이 생성됩니다.

이렇게 솔루션을 생성하면 "hctbuild" 를 생성한 것과 크게 다를 건 없습니다. 이 역시 "CMakeSettings.json" 의 "buildRoot" 에 프로젝트를 빌드합니다.

솔루션 열기

앞에서 언급했듯이 "buildRoot" 에 솔루션이 생성됩니다. 

"LLVM.sln" 을 더블 클릭해서 솔루션을 열 수도 있고, HLSL console 에서 "hctvs" 명령을 입력해 솔루션을 열 수도 있습니다. 일단 솔루션이 생성되고 나면 일반 Visual Studio 솔루션들과 다를 것이 없습니다.

Trouble Shooting

안타깝게도 현재 버전에서는 hctbuild 로 빌드에 성공하지 못하더군요. 솔루션을 열어서 다시 빌드해야 합니다.

86>c:\git\directxshadercompiler\tools\clang\lib\sema\semaexpr.cpp(12689): error C2220: warning treated as error - no 'object' file generated

86>c:\git\directxshadercompiler\tools\clang\lib\sema\semaexpr.cpp(12689): warning C4819: The file contains a character that cannot be represented in the current code page (949). Save the file in Unicode format to prevent data loss

코드페이지가 맞지 않아서라는데... 한글이 있는 것도 아니고 난감하네요.

"File >> Save As" 를 한 다음에 "Save" 옆의 드롭다운을 클릭해서 "Save with encoding" 을 클릭한 다음, "Advanced Save Option" 에서 "Unicode ( UTF-8 with signature) - Codepage 65001" 을 선택하시면 됩니다. 처음에 기본값으로 "without signature" 가 선택되어 있는데, 스크롤을 제일 위쪽으로 올리면 "with signature" 가 나옵니다.

빌드에 성공하면 "$(buildRoot)\$(Configuration)\bin" 에 "dxc.exe" 및 관련 dll 들이 생성되어 있는 것을 확인하실 수 있습니다.

참고 자료

[ 1 ] SPIR-V CodeGen, DirectXShaderCompiler.

[ 2 ] Building Sources, DirectXShaderCompiler.