C++ 프로젝트 구조와 파일 배치¶
프로젝트 내부는 기능·책임별로, 여러 프로젝트는 역할별로 정리한다. 관련 파일을 함께 찾고 수정하기 위한 개인 기준이다. 아래 필수·권장·선택을 구분해 적용한다.
관련 문서: 네임스페이스 · 헤더·include · 프로젝트별 적용 사례 · 원본과 생성물 (초안) · 변경 검증 (초안)
실제 경로·빌드 단위·IDE 표시¶
| 구조 | 역할 | 관리 대상 |
|---|---|---|
| 디렉터리 | 실제 파일 배치 | 폴더·파일, include·빌드 입력 경로 |
| 프로젝트 | 실행 파일·라이브러리 등의 빌드 단위 | .vcxproj, 프로젝트 참조·설정 |
| 프로젝트 내부 필터 | 파일의 논리적 표시 | .vcxproj.filters |
| 솔루션 폴더 | 프로젝트의 표시용 묶음 | 솔루션 표시 계층 |
필터 이동은 실제 파일 이동이 아니며, 솔루션 폴더와 표시 순서는 빌드 의존성을 정하지 않는다. 파일 이동 시에는 실제 경로·빌드 입력·필터를 함께 맞춘다(필수).
프로젝트 내부 파일 배치¶
| 항목 | 규칙 | 강도·예외 |
|---|---|---|
| 기본 배치 | 프로젝트 바로 아래에 주제별 폴더를 두고 관련 .h·.cpp를 함께 배치 |
권장. 앱·엔진 라이브러리 공통. 작은 프로젝트는 평면 배치 허용 |
| 분류 | 실제 책임이 있는 폴더만 추가하고 헤더 전용 타입·템플릿도 담당 기능에 배치 | 권장. Common·Utils는 공유 책임을 설명할 수 있을 때만 사용 |
| include 기준 | 탐색 기준 경로와 허용 의존성을 명시 | 필수. 폴더 분리만으로 내부 헤더 의존성이 차단되지는 않음 |
| 외부·생성 코드 | 자체 코드와 구분하고 공급·생성 구조 유지 | 권장 |
폴더 깊이·파일 수에 고정 상한을 두지 않는다. 함께 수정하는 책임을 기준으로 나누며, 빈 계층을 미리 만들지 않는다.
폴더·파일 이름¶
직접 관리하는 폴더는 가능한 한 PascalCase를 권장한다. 소문자 이름은 도구·외부 원본·기존 경로 호환성을 유지할 이유가 있을 때 예외로 허용하고, 단수·복수는 역할의 의미로 정한다. 이름의 일관성과 기존 연동을 고려해 사용자가 채택한 개인 규칙이다.
적용 범위는 개인 C++ 저장소의 루트와 직접 관리하는 하위 폴더다. 개발자별 상위 보관 경로는 제외한다. 문서 루트 아래의 Markdown 경로는 기존 문서 경로 규칙을 따르며, 식별자·네임스페이스·파일 이름·원본 에셋 이름의 규칙은 확장하지 않는다.
| 대상 | 규칙 | 강도·예외 |
|---|---|---|
| 제품·프로젝트 루트 | 제품 식별 이름을 PascalCase로 표기: ExampleEngine/ |
권장. 기존 저장소·제품 표기는 유지 가능 |
| 직접 관리하는 역할·기능 폴더 | 코드·자원·문서·출력 구분 없이 가능한 한 PascalCase 사용 |
권장. 도구·외부 원본·기존 경로 호환성은 아래 예외 기준 적용 |
| 관례적 소문자 이름 | 익숙한 이름이어도 새로 정할 수 있으면 PascalCase 우선 검토 |
권장. 소문자를 유지할 이유·적용 범위를 프로젝트에 기록 |
| 도구 관리 이름 | 도구가 인식하거나 생성·관리하는 정확한 표기 유지 | 필수. 예: .git/. 변경 시 도구의 지원 방식과 프로젝트 제약 확인 |
| 외부 원본 | 공급자 이름·내부 구조 유지: ThirdParty/imgui/ |
권장. 자체 연동 코드·빌드 설정은 직접 관리하는 폴더 기준 적용 |
| 기존 프로젝트 | 바꾸는 범위부터 적용하고 예외·후속 조건 기록 | 권장. 이름 정리만을 위한 일괄 이동은 요구하지 않음 |
역할별 권장 이름과 소문자 예외¶
| 역할 | 새로 정할 때의 권장 이름 | 예외로 유지할 수 있는 기존 이름 |
|---|---|---|
| 별도로 분리한 소스 코드 루트 | Source/ |
src/ |
| 별도로 제공하는 공개 헤더 루트 | Include/ |
include/ |
| 실행 파일·라이브러리 등의 최종 빌드 산출물 | Bin/ |
bin/ |
| 오브젝트 파일을 포함한 중간 빌드 산출물 | Obj/ |
obj/ |
| 프로젝트 문서 루트 | Documentation/ |
docs/ |
표의 이름은 개인 권장 예시이며 C++ 표준의 요구가 아니다. 폴더 도입 여부는 선택이며 빈 계층을 미리 만들지 않는다. 같은 프로젝트에서는 역할별로 이름을 하나 정하고, Source/와 src/, Documentation/과 docs/처럼 같은 역할의 별칭을 혼용하지 않는 것을 권장한다.
소문자 예외는 도구가 이름을 인식·생성·관리하거나, 공급자 구조를 유지하거나, 기존 빌드·패키징·문서 링크와의 호환성을 보존할 때 허용한다. 구체적인 도구·설정·외부 계약 또는 기존 참조 경로를 근거로 기록하며, 단순히 많이 쓰인다는 이유만으로 소문자 예외를 추가하지 않는다. 도구 기본값을 바꿀 수 있어도 연동을 유지할 필요가 있으면 예외로 기록할 수 있다. 기존 프로젝트의 일괄 이름 변경은 요구하지 않는다.
include는 약칭이 아니므로 “관례적 이름”으로 부른다. 대소문자 방식과 약칭의 풀어 쓰기는 별개이며, 일반 약어의 변환 규칙 전체를 이 표로 확정하지 않는다. Build/는 직접 작성한 빌드 설정, Bin/·Obj/는 생성물이라는 역할 차이를 유지한다.
단수·복수 기준¶
| 폴더가 나타내는 의미 | 표기 | 예시 |
|---|---|---|
| 하나의 제품·모듈·시스템·기능 영역 | 단수 또는 기능명 | Engine/, Sandbox/, Platform/, Rendering/, Build/ |
| 셀 수 있는 대상의 모음·관련 기능 | 복수 | Assets/, Models/, Shaders/, Tests/, Tools/, Samples/, Libraries/ |
| 불가산·집합적 개념 | 자연스러운 용어 그대로 | Content/, Memory/, Math/ |
의미에 맞는 표기를 권장하며 파일·하위 폴더의 현재 개수로 단수·복수를 바꾸지 않는다. Engine/Assets/처럼 자산을 다루는 코드 영역도 복수형으로 표현할 수 있다. Content/Models/는 콘텐츠라는 영역 안의 모델 모음이다. Documentation은 불가산 명사이므로 s를 붙이지 않는다. ThirdParty/는 외부 코드의 분류 이름으로 유지한다.
소스·헤더 이름¶
| 대상 | 표기 | 강도·예외 |
|---|---|---|
| 소스·헤더 | 주된 타입·역할을 나타내는 PascalCase: MemoryPool.h/.cpp, RenderTypes.h |
권장. 대응 헤더·구현은 같은 기본 이름, 주된 타입 하나를 구현하면 타입 이름에 맞춤 |
| PCH | pch.h/.cpp 등 도구·프로젝트의 기존 이름 유지 가능 |
선택. 폴더 이름의 권장을 파일에 확대하지 않음 |
일반 약어의 대소문자 변환은 여전히 미정이며 DX12·D3D12·Win32의 기존 표기는 유지한다. Markdown 경로의 kebab-case, 외부 에셋·공급자 원본 이름은 위 표의 대상에서 제외한다. include 경로의 대소문자는 실제 경로와 맞춘다. 폴더 명명의 비교 근거를 참고하며 실제 이름을 바꾸면 파일 이동 시 검증을 적용한다.
기본 배치 예시¶
Demo/
├─ Demo.vcxproj
├─ Demo.vcxproj.filters
├─ Main.cpp
├─ App/
│ ├─ DemoApp.h
│ └─ DemoApp.cpp
└─ Rendering/
├─ Renderer.h
└─ Renderer.cpp
Demo/를 include 기준으로 정하면 "App/DemoApp.h"로 사용한다. 헤더 작성·include 순서·독립성은 헤더 규칙을 따른다. PCH의 위치·첫 include·생성 설정은 프로젝트에서 결정한다.
Source를 선택하는 경우¶
코드와 설정·문서·에셋을 구분할 필요가 있거나 도구가 요구하면 별도 소스 루트를 선택한다. 새로 정할 때는 Source/를 권장하고, 그 안에서도 Source/Rendering/Renderer.h/.cpp처럼 주제별로 함께 배치하고 include 기준을 코드 루트에 맞춘다. 공개 헤더 분리와 소스 루트 도입은 각각 판단한다. 기존 src/는 위 명명 예외 기준에 따라 유지할 수 있다.
공개 헤더를 Include로 분리할 때¶
공개 헤더는 다른 앱·모듈에 제공하는 API 헤더다. 소스의 인터넷 공개 여부와 무관하며, Include/는 접근 차단 기능이 아니다. 기존 include/는 위 명명 예외 기준에 따라 유지할 수 있다.
| 상황 | 판단 |
|---|---|
| 다른 저장소·팀에 전달하거나 설치·패키징 | 분리 권장 |
| 소비자의 내부 구현 의존을 줄이거나 서로 다른 주기로 변경·릴리스 | 분리 권장 |
| 한 사람이 함께 수정하고 제공할 헤더 집합을 따로 관리할 필요가 없음 | 분리 생략 가능 |
라이브러리 형식(.lib·.dll), 사용처·테스트 수 증가, 소스 공개만으로 분리하지 않는다.
Core/
├─ Core.vcxproj
├─ Include/Example/Core/Memory/
│ └─ Allocator.h # 제공할 API
└─ Memory/
├─ Allocator.cpp
└─ AllocationPage.h # 내부 보조 타입
- 권장:
Include/<제품>/<모듈>/접두어로 소속을 구분하고 내부 헤더는 구현 옆에 유지한다. 공개·내부 트리를 완전히 맞출 필요는 없다. - 필수: 공개 헤더 사용에 필요한 템플릿·인라인 구현·의존성도 제공한다. 모든
.h를 옮기거나 선언만 제공하는 규칙은 아니다. - 권장: 소비자에게 공개 include 기준을 제공하고 내부 경로는 통상적인 탐색 경로에서 제외한다. 내부 테스트는 범위·이유를 기록한 예외를 허용한다.
위 예시의 소비자는 Core/Include/를 기준으로 "Example/Core/Memory/Allocator.h"를 사용한다. 제공하지 않은 내부 경로·PCH 없이 사용할 수 있어야 한다. 폴더 분리만으로 API 호환성이 보장되지는 않으며, 분리하지 않아도 사용 가능한 헤더를 문서로 지정할 수 있다.
중앙 Include·Source 배치를 유지하는 경우¶
Engine/Include/<모듈>/, Engine/Source/<모듈>/, Engine/<모듈>/<모듈>.vcxproj 중앙 배치도 선택 가능하다. 모듈을 독립 관리할 필요가 커지면 모듈별 배치를 우선 검토한다(권장). 중앙 배치나 별도 프로젝트 설정 디렉터리를 사용하면 프로젝트별 소스 범위·대응 경로·허용 의존성을 기록하고 중복 빌드를 확인한다(필수).
솔루션의 프로젝트 구성¶
역할과 관리 주체를 기준으로 분류한다. 필요한 역할만 추가하고 자체 라이브러리와 외부 원본은 구분한다(권장). 아래 이름과 파일 목록은 예시다.
| 위치 예시 | 용도 | 강도·예외 |
|---|---|---|
Engine/ |
자체 엔진·모듈 | 권장. 제품 목적에 따라 Libraries/ 등 선택 |
Apps/·Sandbox/ |
실행·통합 앱 | 권장. 대표 앱은 루트의 별도 폴더로 유지 가능 |
Samples/ |
기능 사용·학습·시각적 데모 | 권장. 학습 순서 번호는 선택 |
Tests/ |
성공·실패를 판정하는 회귀 검증 | 권장. 타깃별 코드와 공유 지원 코드를 구분. 기존 소규모 배치 허용 |
Tools/ |
개발 지원·에셋 변환 | 권장. 도구 전용 의존성은 도구에 연결 |
ThirdParty/ |
직접 보관하는 외부 원본·배포 파일 | 권장. SDK·패키지는 버전·복원 설정으로 관리 가능 |
Build/ |
직접 작성한 공통·외부 연동 빌드 설정 | 선택. 기존 프로젝트 옆 설정 유지 가능 |
Assets/·Shaders/ |
원본 자원·셰이더 | 선택. 공유·앱별 소속에 맞춰 배치 |
Bin/·Obj/ |
출력·중간 산출물 | 이름은 권장. 프로젝트·구성·플랫폼 간 충돌 방지는 필수이며 하위 경로 형식은 선택 |
솔루션 디렉터리 예시¶
Example/
├─ Example.slnx
├─ Engine/ExampleEngine.vcxproj
├─ Sandbox/Sandbox.vcxproj
├─ Samples/LightingDemo/LightingDemo.vcxproj
├─ Tools/AssetConverter/AssetConverter.vcxproj
├─ Tests/EngineTests/EngineTests.vcxproj
├─ ThirdParty/
├─ Build/
├─ Assets/
├─ Shaders/
├─ Bin/
└─ Obj/
각 실행 프로젝트는 자기 진입점·앱 상태를 소유한다. 공유 라이브러리 원본은 한곳에서 관리하고 앱마다 복사하지 않는다(권장). .sln·.slnx 형식은 프로젝트에서 선택한다.
빌드 프로젝트 분리 기준¶
- 권장: 파일 탐색 문제는 기능 폴더·필터부터 정리한다. 독립 실행·재사용 라이브러리·플랫폼·빌드 설정 등 빌드 경계가 필요할 때 프로젝트 분리를 검토한다.
- 필수: 분리 시 공개 API·의존성 방향·링크 대상·컴파일 설정·테스트 방식을 정하고, 같은 구현의 의도하지 않은 중복 빌드를 확인한다.
- 권장: 앱·샘플·도구·테스트가 엔진을 사용하고, 엔진이 그 구현을 역참조하지 않도록 한다. 테스트 예외와 라이브러리 간 의존성은 프로젝트에서 결정한다.
테스트가 원본 .cpp를 직접 빌드하는 방식도 허용한다. 복사 없이 같은 파일을 참조하고 경로·설정 변경의 영향을 확인한다.
독립 모듈 배치 예시¶
분리한 모듈도 Engine/Core/Core.vcxproj와 Engine/Core/Memory/Allocator.h/.cpp처럼 설정·코드를 같은 모듈 디렉터리에 모으는 것을 권장한다. 생성 프로젝트·공급자 구조는 예외이며, 생성 결과의 위치를 수동으로 바꾸지 않는다.
모듈 책임과 공개 범위¶
| 대상 | 기준 | 강도 |
|---|---|---|
| DX12 | 소비자 계약에 필요한 타입은 공개 가능. 내부 장치·자원 코드는 DX12/에 배치 권장. 정리만을 위한 추상화·PImpl 도입은 불필요 |
공개 선택 |
| ECS | 외부 Component·System 계약과 내부 저장소·실행 보조 구현을 구분 | 권장 |
| 개발 UI | UI 없는 소비자가 필요하면 선택 기능·별도 모듈 검토. 프로젝트 분리는 빌드 경계로 판단 | 권장 |
써드파티 원본과 연동 코드¶
| 대상 | 규칙 | 강도 |
|---|---|---|
| 원본 | 라이브러리별 공급자 구조·라이선스 유지. 앱 필터에 포함해도 별도 ThirdParty 분류 권장 |
권장 |
| 자체 연동 코드 | 사용하는 프로젝트의 기능 폴더에 배치 | 권장 |
| 자체 빌드 설정 | 원본과 구분해 프로젝트 옆·Build/ThirdParty/ 등에 배치. 공급자 빌드 요구 준수 |
권장 |
| 로컬 수정 | 이유·변경 범위·재적용 방법 기록. 불필요한 전체 포맷 변경 방지 | 필수. 패치·브랜치 등 방식은 선택 |
| 빌드 정책 | 자체 포맷·PCH·경고 정책을 일괄 강제하지 않고 ABI·런타임 호환 조건 확인 | 필수 |
| 의존성 | 필요한 타깃에만 include·링크·컴파일 정의 설정. 공개 API의 의존성은 소비자 설정·준비 방법도 제공 | 권장 |
공급 형태에 맞춰 연결하며 모든 의존성을 .vcxproj로 감싸지 않는다.
- 헤더 전용: include·버전·준비 정보로 관리.
- 소스 빌드: 재사용·설정 격리가 필요하면 라이브러리 타깃을 만들며, 공급자 지침에 따른 소스 직접 포함도 허용.
- 사전 빌드 LIB·DLL: 헤더·링크 입력·런타임 배치·지원 구성의 호환성 관리.
- SDK·패키지: 버전·복원 설정·사용 타깃 관리. 전체 원본 복사나 솔루션 표시 의무 없음.
출처·버전·라이선스·취득·재생성 방법은 프로젝트에 기록한다(권장). 공급·로컬 수정 방식은 프로젝트별로 결정한다.
Visual Studio 솔루션 탐색기¶
MSBuild 기반 C++ 프로젝트에 적용한다. C#·CMake 폴더 보기에는 그대로 적용하지 않는다.
프로젝트 내부 필터¶
| 항목 | 규칙 | 강도·예외 |
|---|---|---|
| 기능 분류 | 실제 디렉터리와 같은 이름·계층, 같은 기능의 헤더·구현을 같은 필터에 표시 | 권장 |
| 표시 차이 | Source/ 생략·공개 API 분류 등 실제 경로와 다르면 대응 기준 기록 |
권장. 기능 이름·소속은 유지 |
| 생성 프로젝트 | 프로젝트·필터 생성 원본에서 관리 | 필수. 생성 결과를 반복 수동 수정하지 않음 |
직접 관리하는 .vcxproj.filters는 공유 입력으로 취급한다. 공개 헤더 분리 시 API 경계가 표시에서도 드러나게 구성하며 References·External Dependencies 같은 IDE 전용 노드는 재배치 대상에서 제외한다.
솔루션 폴더와 프로젝트 참조¶
솔루션 폴더는 탐색에 도움이 될 때 선택하고 역할별 실제 디렉터리와 대응시키는 것을 권장한다. 예를 들어 탐색기의 Apps > Sandbox는 실제 Sandbox/에 대응할 수 있다. ThirdParty에는 실제 외부 빌드 프로젝트만 둔다.
소비자의 실제 프로젝트 참조·헤더 경로·컴파일 설정·런타임 배치를 확인한다(필수). 솔루션의 표시만으로 연결이 설정되지는 않는다.
파일 이동 시 검증¶
다음은 실제 재배치 시 필수 확인 사항이다.
- 파일 소속·공개 범위·include 기준과 같은 원본을 사용하는 프로젝트를 확인한다.
- 실제 경로·프로젝트 입력·필터를 맞추고 누락·중복 등록을 확인한다.
- include·PCH·공유 설정·셰이더·에셋 복사·스크립트 경로와 출력·런타임 계약을 확인한다.
- Visual Studio 로드·파일 표시, 헤더 독립성, 영향받는 지원 구성의 빌드·테스트·필요한 실행을 검증한다. 공개 헤더는 제공 설정만으로 내부 경로·PCH에 숨은 의존성 없이 사용할 수 있는지 확인한다.
- 선택한 구조·예외·실제 적용 결과와 수행하지 못한 검증을 프로젝트에 기록한다.
프로젝트별 결정 사항¶
다음은 공통 규칙의 미결정 항목이 아니다. 필요할 때 선택·이유·예외를 프로젝트 문서에 기록한다.
| 항목 | 결정할 내용 |
|---|---|
| 코드 루트 | Source/ 도입 여부·시점과 기존 소문자 경로 유지 예외 |
| 공개 헤더 | Include/ 도입 여부, 제공 파일·의존성·제품 접두어와 기존 경로 유지 예외 |
| API 범위 | DX12·ECS·개발 UI의 공개·선택 기능 |
| 빌드 단위 | 분리 대상·시점, 의존성·테스트 방식 |
| 실제 트리·IDE | 역할·기능 이름, 앱 위치, 경로·필터 대응 |
| 써드파티 | 공급·버전·도입 대상·로컬 수정 방식 |
근거와 공식 동작¶
배치·분리·PascalCase는 사용자 선택에 따른 개인 규칙이다. 공식 자료는 도구 동작과 비교 근거이며 프로젝트의 도구·언어 버전을 고정하지 않는다. C의 별도 규칙은 이 문서에서 정하지 않는다.
Microsoft 확인일: 2026-10-14~15. C++ 문서 뷰 msvc-170, SolutionFolder 뷰 visualstudiosdk-2022.
- vcxproj.filters — Creating a custom filters file: 필터의 논리적·중첩 분류. 기능별 동시 표시는 개인 선택.
- .vcxproj — ItemGroup elements: 빌드 입력 관리. IDE 관리 프로젝트의 편집 권고를 참고하며 직접 XML 편집을 의무화하지 않음.
- SolutionFolder — Remarks: 프로젝트 표시용 컨테이너.
- Consuming libraries — Consuming static libraries: 프로젝트 참조와 외부 LIB·DLL 소비. include 경로는 이 위키의 헤더 기준을 사용.
- Google — File Names: 소문자·
.cc·.h권고와 달리 기존 개인 표기에 맞춰 PascalCase·.h·.cpp채택. 확인일: 2026-10-16, 고정 버전 없는 C++20 대상 웹 문서.
폴더 명명의 비교 근거¶
확인일: 2026-10-28. 공식 문서는 도구 동작·기본값의 근거이며 위 권장 이름이나 단수·복수 기준을 일괄 권고하지 않는다. 직접 관리하는 폴더의 PascalCase 우선 권장은 사용자가 선택한 방향이며 소문자 기본값은 호환성에 따라 유지할 수 있는 예외로 구분한다. 설치·배포 경로는 해당 도구·소비자 계약을 우선 확인한다.
- Microsoft — Change the build output directory, C++:
OutDir·IntDir로 출력·중간 경로 설정.bin/·obj/라는 이름의 강제 근거가 아니다. 문서 뷰vs-2022, Visual Studio 2022 이상 대상. - CMake — install, TARGETS: 실행 파일·헤더의 기본 설치 경로에
bin·include사용. 소스 저장소 배치와 설치 배치는 구분한다. 확인 문서 버전: 3.28.6. - MkDocs — docs_dir: 문서 원본 경로의 기본값은
docs이며 설정으로 변경 가능. 고정 버전 없는 웹 문서. - Git — gitrepository-layout, DESCRIPTION: 작업 트리의
.git관리 구조. 도구가 관리하는 이름과 임의로 정하는 이름을 구분하는 근거. 버전을 고정하지 않은 웹 매뉴얼.
변경 기록¶
-
2026-10-28: 사용자 선택으로 폴더 명명 규칙을 채택했다. 직접 관리하는 폴더는 가능한 한 PascalCase를 권장하고
Source/·Include/·Bin/·Obj/·Documentation/을 역할별 권장 이름으로 제시했다. 소문자 이름은 도구·외부 원본·기존 경로 호환성을 위한 조건부 예외로 구분했으며 의미에 따른 단수·복수 기준을 정리했다. 기존 규칙에 통합하고 배치 예시를 맞췄으며 PCH 이름·일반 약어의 미결정 범위와 실제 엔진 경로·설정은 유지했다. -
2026-10-16: 공통 규칙 채택, 프로젝트별 결정 구분과
project-structure.md이동을 반영했다. 후속 요청으로 반복 설명·배치 트리를 줄이고 핵심 표·대표 예시·검증 항목으로 압축했다. 채택 강도·예외·네임스페이스의 별도 관리와 실제 프로젝트 미적용 상태는 유지했다. - 2026-10-15: 주제별 동시 배치와 조건부 공개 헤더 분리 초안을 보강했다.
- 2026-10-14: 소스 배치·솔루션 탐색기 초안을 작성했다.