CMake, 소스와 빌드 디렉터리를 나누는 법

CMake는 소스 트리와 빌드 트리를 나눠 설정 파일을 생성한 뒤 컴파일하는 빌드 시스템이며, 소스 폴더를 더럽히지 않고 빌드할 때 씁니다.

이 글은 cmake.org 공식 사용자 안내와 cmake(1) 매뉴얼을 2026-08-30 기준으로 정리한 일반 설명이며, 생성기와 플랫폼에 따라 세부 동작은 달라질 수 있습니다.

CMake는 무엇인가?

한 줄 답: 이 도구는 CMake 언어 파일로부터 로컬 빌드시스템을 생성하는 크로스 플랫폼 빌드 생성기입니다.

프로젝트의 최상위 소스 디렉터리에는 보통 CMakeLists.txt가 있습니다. 최상위 파일은 cmake_minimum_required()를 호출한 뒤 project()를 직접 호출해야 하며, 이를 통해 프로젝트의 소스 디렉터리와 바이너리 디렉터리 같은 기본 정보가 설정됩니다.

동작은 두 단계입니다. 먼저 이 도구가 생성기 백엔드를 통해 현재 머신에 맞는 빌드시스템을 생성하는 설정 단계를 거칩니다. 다음에는 네이티브 빌드 도구가 그 빌드시스템을 처리해 실행 파일이나 라이브러리를 만드는 빌드 단계를 수행합니다.

생성된 빌드시스템은 생성한 머신에 특화되어 다른 환경에 그대로 배포할 수 없습니다. 이후 설정 과정에서 다시 작성될 수 있으므로, 사용자가 생성된 파일을 직접 수정하기보다 읽기 전용으로 다루는 것이 안전합니다. 이 도구 자체는 컴파일러가 아니고 Make만을 위한 도구도 아니며, Yocto 이미지 빌드 절차를 설명하는 도구도 아닙니다.

소스와 빌드 디렉터리는 왜 나누나?

한 줄 답: 소스 트리를 깨끗하게 유지하고, 한 소스를 여러 툴체인으로 빌드하며, 산출물을 디렉터리 삭제로 지울 수 있기 때문입니다.

소스 트리는 프로젝트가 제공하는 소스 파일이 있는 최상위 디렉터리입니다. 반면 빌드 트리는 빌드시스템 파일과 실행 파일·라이브러리 같은 빌드 산출물을 저장하는 최상위 디렉터리입니다. 빌드 트리에는 설정 정보를 지속해서 보관하는 CMakeCache.txt가 기록되며, 이 파일은 해당 디렉터리가 빌드 트리임을 식별하는 데도 사용됩니다.

소스 디렉터리 안에 빌드 트리를 두는 in-source 빌드도 지원되지만, 공식 문서는 별도 빌드 트리를 사용하는 out-of-source 빌드를 권장합니다. 별도 디렉터리를 쓰면 다음과 같은 이점이 있습니다.

소스 디렉터리를 생성 파일과 산출물 없이 깨끗하게 유지합니다.
같은 소스를 여러 툴체인이나 설정(Debug/Release 등)으로 각각 빌드할 수 있습니다.
산출물을 정리할 때 소스 파일을 건드리지 않고 빌드 디렉터리를 삭제하기만 하면 됩니다.

생성된 빌드시스템 파일은 설정 과정에서 다시 작성될 수 있습니다. 따라서 생성기 출력물을 직접 고치는 대신 소스의 CMakeLists.txt나 설정 옵션을 바꾼 뒤 빌드 트리를 다시 설정하는 방식으로 관리해야 합니다.

설정과 빌드는 어떻게 하나?

한 줄 답: -S로 소스 루트를, -B로 빌드 루트를 지정해 생성한 뒤, cmake --build로 이식성 있게 컴파일합니다.

명령어에서 -S는 빌드할 프로젝트의 소스 루트를 가리키고, -B는 빌드시스템을 저장할 빌드 디렉터리의 루트를 가리킵니다. -B로 지정한 디렉터리가 아직 없으면 해당 명령이 자동으로 만듭니다. 현재 매뉴얼이 제시하는 기본 흐름은 다음 두 줄입니다.

cmake -S <source> -B <build>
cmake --build <build>

첫 줄은 선택된 생성기를 사용해 빌드시스템을 생성하는 설정 단계입니다. 둘째 줄은 지정한 빌드 트리를 대상으로 선택된 생성기에 연결된 네이티브 빌드 도구를 호출하는 컴파일 단계이므로, Make나 Ninja를 빌드 절차에 직접 고정하지 않아도 됩니다.

이 -S·-B 형식은 매뉴얼에서 3.13에 추가된 것으로 표시되어 있습니다. 이전 방식인 mkdir build; cd build; cmake ../src도 여전히 문서화되어 있지만, 소스와 빌드 경로를 한 명령에서 분명히 드러내는 현재 형식을 우선 사용할 수 있습니다.

필요한 대상만 만들 때는 --target을 붙이고, 병렬 처리를 사용할 때는 -j 또는 --parallel을 지정합니다. 설치 규칙이 있는 프로젝트라면 cmake --build . --target install처럼 설치 대상을 직접 호출할 수도 있습니다.

자주 쓰는 생성기·옵션은 무엇인가?

한 줄 답: -G로 생성기를 고르고, 단일 구성 생성기에서는 -DCMAKE_BUILD_TYPE으로 Debug·Release를 지정합니다.

**생성기(Generator)**는 어떤 종류의 로컬 빌드시스템을 만들지 결정합니다. 생성기를 지정하지 않으면 현재 플랫폼에 맞는 기본값을 선택하며, Unix 계열에서는 보통 Unix Makefiles가 기본 생성기입니다. Linux에서 다른 선택이 필요하면 cmake --help로 로컬에서 사용할 수 있는 생성기 목록을 확인한 뒤 -G로 이름을 지정합니다. 생성기 이름은 대소문자를 엄격히 구분합니다.

예를 들어 Ninja 생성기를 명시하고 Release 구성을 지정하는 흐름은 다음과 같습니다.

cmake -S <source> -B <build> -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build <build> --parallel

Ninja는 주요 플랫폼에서 사용할 수 있으며 성능과 효율을 중시하는 빌드 도구입니다. 주의할 점은, 생성기를 처음 선택한 뒤에는 같은 빌드 트리에서 -G만 단독으로 바꿀 수 없으므로, 다른 생성기로 전환할 때는 기존 빌드 트리를 삭제하고 처음부터 다시 설정해야 합니다.

-D는 캐시 항목을 만들거나 갱신하는 옵션입니다. Makefile·Ninja처럼 단일 구성인 빌드시스템에서는 -DCMAKE_BUILD_TYPE=Debug 또는 Release로 구성을 정하지만, 다중 구성 생성기는 이 값을 무시하고 빌드 단계에서 --config Release처럼 구성을 선택합니다.

설치 대상의 위치는 CMAKE_INSTALL_PREFIX로 정하며 Unix 계열의 기본값은 /usr/local입니다. 교차 컴파일에 필요한 정보는 CMAKE_TOOLCHAIN_FILE이 가리키는 파일로 전달할 수 있지만, 툴체인 파일 자체의 작성법은 별도의 주제입니다.

FAQ

한 줄 답: 별도 빌드 트리를 유지하고, 처음 설정할 때 생성기와 필요한 설정 값을 명확히 정하면 됩니다.

질문	답변
소스 디렉터리 안에서 바로 설정해도 됩니까?	지원되는 방식이지만 권장되지는 않습니다. 별도 빌드 트리를 사용하면 소스 트리를 깨끗하게 유지하고 산출물을 쉽게 정리할 수 있습니다.
생성기를 나중에 `-G`로 바꿀 수 있습니까?	첫 설정 이후에는 같은 빌드 트리에서 바꿀 수 없습니다. 기존 빌드 트리를 삭제한 뒤 새 생성기로 처음부터 설정해야 합니다.
`cmake --build` 대신 `make`를 직접 실행해도 됩니까?	Unix Makefiles를 선택했다면 `make`, Ninja를 선택했다면 `ninja`를 직접 실행할 수 있습니다. 다만 `cmake --build`는 선택된 네이티브 도구를 자동으로 호출하므로 생성기에 덜 종속적인 절차입니다.
`-S`와 `-B`는 필수입니까?	이전의 현재 디렉터리 방식도 여전히 문서화되어 있습니다. 다만 `-S`와 `-B`는 소스·빌드 경로를 분명히 드러내고 없는 빌드 디렉터리도 만들 수 있어 이 글에서는 이 형식을 권장합니다.

출처

한 줄 답: 본문 사실과 짧은 명령은 2026-08-30 기준으로 확인한 cmake.org 공식 문서 세 곳만 사용합니다.

공식 사용자 안내 — out-of-source 빌드의 이유, 생성기, 네이티브 빌드 도구 호출을 확인했습니다.
명령행 매뉴얼 — 소스·빌드 트리, -S·-B, cmake --build, -G, -D의 의미를 확인했습니다.
project() 명령 문서 — 최상위 CMakeLists.txt에서 project()를 직접 호출해야 하는 조건을 확인했습니다.