개발 스택 가이드 · C++

Modern C++ 개발.

production 지향 C++26-first 환경입니다. 프로젝트 소유 modules, 명시적 error contract, RAII, target 기반 CMake, Ninja, 플랫폼 네이티브 toolchain을 사용합니다. 필요한 compiler 또는 standard library가 선택한 C++26 기능을 아직 지원하지 않는 경우 C++23을 호환 경로로 사용합니다.

Primary C++26 Compatibility C++23 개발 CMake 3.30+ · Ninja 1.11+ Targets Desktop · Mobile · Web

엔지니어링 baseline.

Area	Default	Rule
Language	`C++26`	현재 언어 경로를 우선하고, 실제 toolchain 지원 때문에 필요한 경우에만 C++23을 사용하세요.
Project boundaries	C++ modules	New project-owned production boundaries use `.cppm` modules by default.
Standard library	Minimal headers	Use normal standard headers in the global module fragment; do not depend on experimental `import std;`.
오류	`std::expected`	복구 가능한 실패는 sentinel value 뒤에 숨기지 말고 API contract의 일부로 만드세요.
Console output	`std::print` / `std::println`	새 iostream 삽입 체인보다 현대적인 formatted output을 우선하세요.
Build model	Target-based CMake	compile features, sources, definitions, dependencies를 해당 소유 target에 연결해 두세요.
Generator	Ninja	compiler, configuration, target마다 별도 build tree를 사용하세요.

headers가 아니라 modules부터 시작하세요.

프로젝트 소유 경계는 책임을 직접 표현해야 합니다. declarations는 module interface에서 export하고, 비단순 implementation은 implementation unit에 두며, platform/third-party code는 명시적 adapter 경계에 격리하세요.

C++ module interfacesrc/greeting/greeting.cppm

module;

#include <expected>
#include <string>
#include <string_view>

export module genyleap.greeting;

export namespace genyleap::greeting {

enum class GreetingError {
    EmptyName
};

[[nodiscard]] auto makeGreeting(std::string_view name)
    -> std::expected<std::string, GreetingError>;

}

C++ implementation unitsrc/greeting/greeting.cpp

module;

#include <expected>
#include <format>
#include <string>
#include <string_view>

module genyleap.greeting;

namespace genyleap::greeting {

auto makeGreeting(std::string_view name)
    -> std::expected<std::string, GreetingError>
{
    if (name.empty()) {
        return std::unexpected {GreetingError::EmptyName};
    }

    return std::format("Hello, {}.", name);
}

}

Composition rootsrc/main.cpp

#include <print>

import genyleap.greeting;

int main()
{
    const auto greeting = genyleap::greeting::makeGreeting("Genyleap");

    if (!greeting) {
        std::println("Unable to create greeting.");
        return 1;
    }

    std::println("{}", *greeting);
    return 0;
}

module scanning을 사용하는 target 기반 CMake.

언어 표준, module file set, dependency graph를 target에 유지하세요. 고전 header 아키텍처를 흉내 내기 위해 global compiler flags나 project-wide include directory로 돌아가지 마세요.

CMakeCMakeLists.txt

cmake_minimum_required(VERSION 3.30)

project(GenyleapHello
    VERSION 0.1.0
    LANGUAGES CXX
)

add_library(genyleap_greeting)

target_compile_features(genyleap_greeting
    PUBLIC
        cxx_std_26
)

target_sources(genyleap_greeting
    PUBLIC
        FILE_SET CXX_MODULES
        FILES
            src/greeting/greeting.cppm
    PRIVATE
        src/greeting/greeting.cpp
)

set_property(
    TARGET genyleap_greeting
    PROPERTY CXX_SCAN_FOR_MODULES ON
)

add_executable(genyleap_hello
    src/main.cpp
)

target_link_libraries(genyleap_hello
    PRIVATE
        genyleap_greeting
)

target_compile_features(genyleap_hello
    PRIVATE
        cxx_std_26
)

ShellConfigure · build · test

cmake -S . -B build/dev -G Ninja \
  -DCMAKE_BUILD_TYPE=Debug

cmake --build build/dev --parallel

ctest --test-dir build/dev \
  --output-on-failure \
  --no-tests=error

플랫폼 toolchain.

C++ 아키텍처는 이식성을 유지하고 compiler, SDK, linker, packaging, runtime은 명시적 플랫폼 경계로 둡니다. compiler 또는 target SDK를 바꾼 뒤 기존 configure된 CMake tree를 재사용하지 마세요.

Desktop · Apple

macOS.

Apple SDK와 플랫폼 도구를 위해 전체 Xcode를 설치하세요. Apple Clang이 기본 native compiler이며 더 새로운 compiler feature나 diagnostics가 필요하면 upstream LLVM을 함께 사용할 수 있습니다.

ShellInstall and verify

sudo xcode-select --switch /Applications/Xcode.app
sudo xcodebuild -license accept

brew install cmake ninja llvm

xcrun clang++ --version
cmake --version
ninja --version
xcrun --show-sdk-path

Apple Clang을 전역으로 대체하지 마세요.

Select upstream LLVM per build when needed; Apple SDK integration and upstream language experimentation are separate concerns.

Desktop · Server

Linux.

portability가 중요하면 GCC와 Clang을 모두 준비하세요. compiler마다 별도 build directory를 configure하고 버전 번호만으로 추정하지 말고 실제 CMake/compiler/generator 조합으로 module support를 검증하세요.

ShellUbuntu / Debian baseline

sudo apt update
sudo apt install -y \
  build-essential \
  clang \
  lld \
  cmake \
  ninja-build \
  gdb

ShellSeparate compiler builds

cmake -S . -B build/gcc -G Ninja \
  -DCMAKE_CXX_COMPILER=g++

cmake -S . -B build/clang -G Ninja \
  -DCMAKE_CXX_COMPILER=clang++

Desktop · Windows

Windows.

Use Visual Studio Build Tools with the C++ workload for the Windows SDK and MSVC ABI. Add LLVM when you want clang-cl diagnostics while retaining MSVC-compatible platform integration.

PowerShellInstall toolchains

winget install --id Microsoft.VisualStudio.2022.BuildTools `
  --override "--wait --passive --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

winget install --id Kitware.CMake
winget install --id Ninja-build.Ninja
winget install --id LLVM.LLVM

Developer PowerShell을 사용하세요.

CMake를 configure하기 전에 MSVC compiler, linker, Windows SDK 환경을 초기화해야 합니다.

Mobile · Android

Android.

Use the Android NDK's Clang toolchain and CMake toolchain file rather than treating Android as a normal Linux desktop build. For projects that also use the current Qt baseline, the compatibility manifest currently resolves NDK r27c (27.2.12479018).

CMakeNative Android shape

cmake -S . -B build/android-arm64 -G Ninja \
  -DCMAKE_TOOLCHAIN_FILE="$ANDROID_NDK/build/cmake/android.toolchain.cmake" \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-28

cmake --build build/android-arm64 --parallel

Android 전용 JNI, lifecycle, storage, permission code를 adapter 뒤에 두어 domain/application modules가 일반 C++로 유지되도록 하세요.

Mobile · Apple

iOS.

Use Xcode 16 or newer for the current Qt compatibility profile, and treat Apple frameworks, entitlements, signing and bundle resources as platform boundaries. Device and simulator builds are distinct targets even when they share application modules.

ShellInspect active Apple SDKs

xcodebuild -version
xcrun --sdk iphoneos --show-sdk-path
xcrun --sdk iphonesimulator --show-sdk-path
xcrun --sdk iphoneos clang++ --version

Web · wasm32

WebAssembly.

Use Emscripten when the target runtime is the browser. For the current Qt compatibility profile, Emscripten 5.0.5 is pinned automatically from upstream Qt documentation; a standalone C++/WASM project may intentionally choose a newer SDK after its own verification.

POSIX shellPin an emsdk toolchain

git clone https://github.com/emscripten-core/emsdk.git
cd emsdk

./emsdk install 5.0.5./emsdk activate 5.0.5
source ./emsdk_env.sh
em++ --version

PowerShellWindows activation

git clone https://github.com/emscripten-core/emsdk.git
Set-Location emsdk

.\emsdk.bat install 5.0.5.\emsdk.bat activate 5.0.5
.\emsdk_env.ps1
em++ --version

browser threading, SIMD, filesystem access, network behavior는 단순 compiler switch가 아니라 runtime 제약입니다. target capability로 모델링하고 실제 배포할 browser configuration에서 검증하세요.

Diagnostics는 개발 환경의 일부입니다.

compile-time correctness는 한 계층에 불과합니다. 재현하기 어려운 장애가 나타난 뒤 추가하지 말고 sanitizer와 static-analysis build를 처음부터 준비하세요.

도구	용도	Recommendation
`ASan`	Memory safety failures	Debug and CI where supported
`UBSan`	Undefined behavior	Pair with ASan in a dedicated diagnostic build
`TSan`	Data races	Separate build because instrumentation changes runtime behavior
`clang-tidy`	Static analysis and modernization	Editor plus CI on changed production surfaces

CMakeTarget-local sanitizer example

if(CMAKE_CXX_COMPILER_ID MATCHES "Clang|GNU")
    target_compile_options(genyleap_greeting PRIVATE
        -fsanitize=address,undefined
        -fno-omit-frame-pointer
    )

    target_link_options(genyleap_greeting PRIVATE
        -fsanitize=address,undefined
    )
endif()

Native libraries

Boost is part of the native foundation.

Use the C++ standard library first when it cleanly provides the required facility, then use Boost for capabilities that remain stronger or broader there. Keep Boost dependencies target-local, architecture-specific when compiled, and visible through modern CMake imported targets.

Open the current Boost guide

사용자-facing 앱에서는 Qt를 의도적으로 선택하세요.

새로운 Genyleap 스타일 GUI 앱의 기본 interface stack은 module 기반 C++ application/domain code 위의 Qt Quick, QML, Qt Quick Controls입니다. UI는 adapter이며 중복된 business logic을 소유하지 않습니다.

Open the current Qt guide Modern C++ engineering contract ↗