[macOS] GCC환경에서 SDL2 설치 방법: 'SDL2/SDL.h' not found 에러 해결법

macOS에서 C/C++로 게임 개발이나 그래픽 프로그래밍을 시작할 때 가장 먼저 찾는 라이브러리가 SDL2입니다.

 

오늘은 GCC를 활용할 때, Homebrew를 이용한 SDL2 설치부터, 컴파일 에러를 완벽하게 해결한 과정을 정리해 보겠습니다.

1. SDL2 설치 (Homebrew)

가장 먼저 macOS의 패키지 관리자인 Homebrew를 이용해 SDL2를 설치합니다. 터미널에서 아래 명령어를 입력하세요.

brew install sdl2

2. 문제 발생: 헤더 파일을 찾을 수 없음

간단한 main.c 코드를 작성하고 일반적인 방식으로 컴파일을 시도했습니다.

 

# 시도했던 명령어
gcc main.c -o main $(sdl2-config --cflags --libs)

 

에러 메시지:

 

main.c:1:10: fatal error: 'SDL2/SDL.h' file not found
    1 | #include <SDL2/SDL.h>
      |          ^~~~~~~~~~~~

3. 해결 방법: 명시적 경로 지정

컴파일러에게 SDL2 헤더가 들어있는 부모 폴더(include)를 직접 알려주어 해결했습니다.

최종 성공 명령어:

gcc main.c -o main -I/opt/homebrew/include $(sdl2-config --libs)

• -I/opt/homebrew/include: 컴파일러에게 헤더 파일을 찾을 추가 경로를 지정합니다. 이렇게 하면 #include <SDL2/SDL.h> 구문을 정상적으로 인식합니다.
• $(sdl2-config --libs): 실행에 필요한 SDL2 라이브러리들을 자동으로 링크해 줍니다.

4. 결과 확인

컴파일 후 생성된 실행 파일을 돌려보면 SDL2가 정상적으로 실행되는 것을 확인할 수 있습니다.

 

./main

 

해결 방법에 대한 간단한 설명은 끝났습니다. 하지만 어떤 이유와 어떤 과정으로 해결했는지 관심이 있으시다면 아래의 글을 더 봐주시길 바랍니다.

5. 원인 분석

처음에 시도했던 명령어는 왜 작동하지 않았을까?

main.c:1:10: fatal error: 'SDL2/SDL.h' file not found
    1 | #include <SDL2/SDL.h>
      |          ^~~~~~~~~~~~

 

에러 메세지를 다시 확인해보면 핵심 문제는 헤더파일을 찾지 못한 것이다. 헤더파일에 대한 경로가 잘못되었다는 것이고 해결 방법은 그저 올바른 헤더파일 경로를 지정해주는 것이다.

# 시도했던 명령어
gcc main.c -o main $(sdl2-config --cflags --libs)

처음에 시도했던 명령어의 $(sdl2-config --cflags --libs) 부분에 대해서 살펴보려 한다. 명령어 구조를 간단히 정리하면 아래와 같다.

sdl2-config	SDL2를 설치하면 자동으로 함께 설치되는 CLI 유틸리티
--cflags	헤더 경로
--libs	라이브러리 경로

sdl2-config --cflags --libs

먼저 터미널에 sdl2-config --cflags --libs를 입력해보면 위아래와 같이 경로가 출력되는 것을 확인할 수 있다.

-I/opt/homebrew/include/SDL2 -D_THREAD_SAFE
-L/opt/homebrew/lib -lSDL2

헤더파일 경로와 라이브러리 경로가 출력되는 것을 확인할 수 있지만 해당 경로로는 SDL2 헤더 파일을 찾을 수 없었다.

문제는 헤더파일 경로 마지막에 /SDL2 폴더까지 경로 지정되어 있는 것이다.

 

때문에 소스 코드에서 #include <SDL2/SDL.h>라고 쓰면, 실제로는 .../include/SDL2/SDL2/SDL.h를 찾으려 하기 때문에 경로가 꼬이게 된다.

 

-I/opt/homebrew/include/SDL2/SDL2/SDL.h	헤더 파일을 찾을 수 없음
-I/opt/homebrew/include/SDL2/SDL.h	헤더 파일을 찾을 수 있음

따라서 sdl2-config가 제공하는 경로에서 /SDL2를 제외한 -I/opt/homebrew/include 경로로 강제로 적용해서 헤더 파일을 찾을 수 있었던 것이다.

gcc main.c -o main -I/opt/homebrew/include $(sdl2-config --libs)