본문으로 건너뛰기
Folly Code Review · 3/89

Folly 빌드와 fbcode 환경 — monorepo의 그림자

· Hawk · 4분 읽기
cpp folly build fbcode monorepo cmake

한 줄 요약: Folly는 Meta 내부에서는 Buck/fbcode 안에서만 빌드되도록 자라났고, OSS CMake 빌드는 그 그림자다. 외부 사용자가 마주치는 빌드 문제 대부분은 이 비대칭에서 나온다.

#동기 — fbcode가 무엇인가

fbcode는 Meta의 C++ monorepo다. 모든 라이브러리, 모든 binary가 단일 디렉터리 트리 안에 있고 단일 빌드 시스템(Buck2)이 이를 본다. fbcode 안에서는 다음 가정이 항상 참이다.

  • 모든 코드가 같은 clang 버전으로 컴파일된다.
  • 모든 라이브러리가 같은 정적 링크 ABI를 갖는다.
  • 의존성은 path로 표현되며 version은 없다.
  • jemalloc이 항상 링크된다.
  • glog/gflags가 항상 사용 가능하다.

Folly는 이 가정 위에 자라났다. 그래서 외부 빌드는 이 가정을 다시 만들거나, 만들지 못한 부분을 우회해야 한다.

#OSS 빌드 옵션

방법                | 난이도 | 권장 |
─────────────────────────────────────
getdeps.py (Meta 제공) | 낮음   | 신규 개발 |
vcpkg              | 중간   | Windows/macOS |
Conan              | 중간   | CI 통합 |
직접 CMake          | 높음   | 시스템 통합 |

#getdeps.py — 가장 안전한 길

Meta가 직접 유지하는 빌드 스크립트다. 의존성을 Folly가 검증한 버전으로 가져와 빌드한다.

Terminal window
git clone https://github.com/facebook/folly.git
cd folly
python3 build/fbcode_builder/getdeps.py install-system-deps --recursive
python3 build/fbcode_builder/getdeps.py build --no-tests folly
python3 build/fbcode_builder/getdeps.py show-inst-dir folly

장점은 조합이 검증돼 있다는 점이다. 단점은 시스템에 자체 의존성 트리(/tmp/fbcode_builder_getdeps-...)를 만들어둔다는 점이다.

#vcpkg

Terminal window
./vcpkg install folly

folly 포트는 boost-context, boost-thread, gflags, glog, double-conversion, fmt, libevent, openssl, zstd 등을 자동으로 끌어온다. 호스트 triplet에 따라 빌드 시간이 30분에서 수 시간 사이다.

#직접 CMake

cmake_minimum_required(VERSION 3.20)
project(my_app)


find_package(Boost 1.83 REQUIRED COMPONENTS context thread)
find_package(gflags REQUIRED)
find_package(glog REQUIRED)
find_package(fmt REQUIRED)
find_package(Folly REQUIRED)


add_executable(app main.cpp)
target_link_libraries(app PRIVATE Folly::folly)
target_compile_features(app PRIVATE cxx_std_20)

find_package(Folly)가 발견하는 FollyConfig.cmake는 빌드 시점의 의존성 위치를 박아둔다. CMake cache가 stale이면 헷갈리는 에러가 난다.

#흔한 빌드 함정

#1. Boost 버전 충돌

error: 'apply' is not a member of 'boost::context'

Folly가 요구하는 Boost.Context API가 시스템 Boost와 다르면 발생한다. Folly는 최소 Boost 1.74 이상을 요구하고 commit에 따라 더 높을 수 있다.

#2. jemalloc 누락

warning: jemalloc not found; using system allocator

Folly의 fbvector/fbstring은 jemalloc의 nallocx()/xallocx()를 활용한 size class 정렬에 의존한다. 빠지면 동작은 하지만 성능 이득의 절반이 사라진다.

find_package(Jemalloc)
if (JEMALLOC_FOUND)
  target_compile_definitions(folly PRIVATE FOLLY_HAVE_JEMALLOC=1)
endif()

#3. ABI mismatch

undefined symbol: folly::detail::function::createBuffer(...)

Folly 라이브러리와 application이 다른 ABI 옵션으로 빌드됐다. _GLIBCXX_USE_CXX11_ABI flag, -D_FORTIFY_SOURCE, sanitizer 플래그 등이 mismatch의 흔한 원인이다.

해법은 단순하다. 모든 의존성을 같은 toolchain으로 다시 빌드한다. 시스템 패키지 매니저의 Folly를 신뢰하지 말고 직접 빌드한다.

#4. C++ 표준 mismatch

Folly는 commit에 따라 C++17 또는 C++20 요구가 다르다. 응용도 같은 표준으로 컴파일해야 한다. 헤더에 if constexpr로 분기되는 코드가 많아 표준이 어긋나면 link error가 나기 쉽다.

#5. CMake find_package(Folly) 실패

set(Folly_DIR /opt/folly/lib/cmake/folly)
find_package(Folly REQUIRED)

#fbcode 내부 vs OSS — 같은 코드가 다르게 동작하는 부분

영역fbcode 내부OSS
folly::Singleton자동 leak detector 통합수동
folly::SymbolizedFrameMeta symbol server 사용libdwarf
folly::AsyncSocketMeta tooling 통합libevent만
folly::ssl::*Meta cert store시스템 OpenSSL
benchmark macrosMeta perf infra단독 binary

OSS 사용자가 문서에 적힌 대로 했는데 안 되는 경우 대부분 이 격차에서 나온다. 의심되면 issue tracker에서 동일 증상을 검색한다.

#권장 빌드 워크플로

Terminal window
# 1. getdeps.py로 검증된 조합 빌드
git clone https://github.com/facebook/folly.git
cd folly
git checkout v2024.11.04.00      # 특정 release 고정
python3 build/fbcode_builder/getdeps.py install-system-deps --recursive
python3 build/fbcode_builder/getdeps.py build folly


# 2. 결과물 export
INST=$(python3 build/fbcode_builder/getdeps.py show-inst-dir folly)
echo "Install: $INST"


# 3. application 빌드
cmake -B build -S . \
  -DCMAKE_PREFIX_PATH=$INST \
  -DCMAKE_BUILD_TYPE=Release
cmake --build build

CI에서는 위 과정을 Docker image로 캐싱한다. Folly 빌드 자체가 무거우므로 매 PR마다 다시 빌드하지 않는다.

#코드 리뷰 포인트

  • Folly 버전이 고정돼 있는가? main branch를 추적하면 어느 날 갑자기 빌드가 깨진다. tag(vYYYY.MM.DD.PP) 단위로 고정한다.
  • 의존성이 외부에 노출되는가? 라이브러리가 헤더에서 folly/*를 include하면 다운스트림도 같은 Folly를 빌드해야 한다.
  • jemalloc이 링크되는가? nm app | grep jemalloc으로 확인한다.

#자주 보는 안티패턴

# 1. Folly만 별도 toolchain — ABI 충돌
find_package(Folly REQUIRED)   # 시스템 패키지
add_executable(app ...)
target_compile_options(app PRIVATE -D_GLIBCXX_USE_CXX11_ABI=0)
# Folly는 ABI=1로 빌드돼 있음 — link error


# 2. main branch 추적
FetchContent_Declare(folly GIT_REPOSITORY ... GIT_TAG main)
# 어느 날 빌드가 깨짐
MyApi.h
// 3. Public header에서 folly include
#include <folly/Optional.h>
// 다운스트림이 Folly 의존성을 떠안음 — SDK 부적합

#정리

  • Folly는 fbcode/Buck 환경을 전제로 자랐다. OSS 빌드는 그 환경을 재구성해야 한다.
  • getdeps.py가 가장 검증된 길이고, vcpkg/Conan이 그다음이다.
  • ABI mismatch의 99%는 같은 toolchain으로 다시 빌드하면 해결된다.
  • 라이브러리 SDK의 public header에 Folly type을 노출하지 마라.
  • Folly 버전은 tag로 고정하고 CI에서 Docker image로 캐싱한다.

#다음 편

Part 1-04: API stability 정책에서 Folly의 “어떤 보장도 없음” 정책이 실전에 어떻게 작동하는지 본다.

#관련 항목

Folly Code Review · 4 of 89

  1. 1 Folly Code Review — Meta의 production-grade C++ 라이브러리 코드 분석
  2. 2 Folly 개요 — Meta가 production에서 검증한 utility 모음 분석
  3. 3 Folly vs Abseil 철학 비교 — performance-first vs std-compatible
  4. 4 Folly 빌드와 fbcode 환경 — monorepo의 그림자
  5. 5 Folly API stability 정책 — 어떤 보장도 없다는 솔직함
  6. 6 Folly production validation 문화 — peta-scale에서 단련된 코드
  7. 7 folly::Future 분석 — std::future의 한계를 넘는 composable async
  8. 8 folly::Promise·makeFuture — Future를 만드는 두 길
  9. 9 folly::SemiFuture vs Future — executor binding의 명시화
  10. 10 folly::Future thenValue·thenError·thenTry — continuation 체인 분석
  11. 11 folly::collect·collectAll·collectAny — fan-in 패턴 분석
  12. 12 folly::Future retry·window·via — 제어 흐름 조합자
  13. 13 folly::fibers 분석 — M:N stackful coroutine
  14. 14 folly::InlineExecutor — 호출자 thread에서 즉시 실행
  15. 15 folly::CPUThreadPoolExecutor — CPU-bound 작업의 표준 thread pool
  16. 16 folly::IOThreadPoolExecutor — libevent 기반 I/O pool
  17. 17 folly::ManualExecutor — 결정적 테스트를 위한 수동 진행
  18. 18 folly::EventBase 분석 — libevent 이벤트 루프의 핵심
  19. 19 folly::IOBuf 분석 — zero-copy buffer chain의 기본 단위
  20. 20 folly::IOBufQueue — chain의 push/pull 추상화
  21. 21 folly::io::Cursor·RWCursor — chain 위의 stream
  22. 22 folly Zero-copy 패턴 — IOBuf로 ScatterGather I/O 표현
  23. 23 folly::IOBuf shared semantics — clone·unshare·takeOwnership
  24. 24 folly::FBString 분석 — SSO + COW 구현
  25. 25 folly의 fmt::format 통합 — 모던 포맷팅 채택
  26. 26 folly::StringPiece — string_view 호환 분석
  27. 27 folly Join·Split utilities — 문자열 분해와 결합
  28. 28 folly::to·tryTo — text↔num 변환 분석
  29. 29 folly Conv Customization — 사용자 타입 지원
  30. 30 folly Conv 성능 비교 — sprintf·stringstream 대비
  31. 31 folly::F14ValueMap vs std::unordered_map
  32. 32 folly::F14NodeMap — stable pointer가 필요할 때
  33. 33 folly::F14VectorMap — cache-friendly iteration
  34. 34 folly::F14FastMap — auto-select 동작
  35. 35 folly F14 internals — SIMD probing 메커니즘
  36. 36 folly::small_vector — inline storage 분석
  37. 37 folly::FixedString — compile-time string
  38. 38 folly::AtomicHashMap — lock-free read 분석
  39. 39 folly::ConcurrentHashMap — sharded 동시 해시 맵
  40. 40 folly::EvictingCacheMap — LRU 구현 분석
  41. 41 folly::Synchronized — lock wrapper 패턴
  42. 42 folly::SharedMutex 분석
  43. 43 folly::Baton — one-shot wait 동기화
  44. 44 folly::RWSpinLock 분석
  45. 45 folly::PicoSpinLock — 1-byte spinlock
  46. 46 folly::ProducerConsumerQueue — SPSC 큐 분석
  47. 47 folly::MPMCQueue — multi-producer multi-consumer
  48. 48 folly::UnboundedQueue — 동적 크기 lock-free
  49. 49 folly::fibers::Channel — Go-like channel
  50. 50 folly::dynamic — JSON-like dynamic type 분석
  51. 51 folly JSON conversion — toJson·parseJson
  52. 52 folly dynamic ↔ struct — manual marshaling
  53. 53 folly dynamic Visitor pattern — type별 분기
  54. 54 folly::Singleton vs Meyers/static — 왜 Folly의 Singleton인가
  55. 55 folly::SingletonVault 분석 — 등록·소멸·의존성
  56. 56 folly::Singleton try_get·try_get_fast — TLS-cached 접근
  57. 57 folly::ExceptionWrapper — type-erased exception holder
  58. 58 folly::ScopeGuard·SCOPE_EXIT — RAII cleanup
  59. 59 folly::Optional vs std::optional
  60. 60 folly::Function vs std::function
  61. 61 folly::Lazy — 지연 초기화 wrapper
  62. 62 folly Meta 스타일 code review 패턴
  63. 63 folly anti-patterns — 잘못 쓰면 std보다 느림
  64. 64 folly vs std 선택 기준 분석
  65. 65 folly::coro 개요 — production C++20 코루틴 어댑터
  66. 66 folly::coro::Task — lazy single-shot 코루틴
  67. 67 folly::coro::AsyncGenerator — 비동기 스트림
  68. 68 folly coro blockingWait·collectAll — 동기 경계와 fan-in
  69. 69 folly::coro::Baton·Mutex — 코루틴-aware 동기화
  70. 70 folly::Expected — 결과 또는 오류
  71. 71 folly::Try — Future 결과 wrapper
  72. 72 folly::Try vs Expected 선택 기준
  73. 73 folly::Range — 일반 iterator pair
  74. 74 folly::Uri — URL 파서
  75. 75 folly Fingerprint64·128 — 분산 hash
  76. 76 folly SpookyHashV2 — fast non-crypto hash
  77. 77 folly::Init — main() 부트스트랩
  78. 78 folly::Indestructible — global lifetime 패턴
  79. 79 folly::MicroLock — 1-byte 락
  80. 80 folly::MicroSpinLock — 가장 좁은 spin lock
  81. 81 folly::format — legacy formatter 분석
  82. 82 folly::demangle — typeid 디망글링
  83. 83 folly::DynamicConverter — dynamic ↔ struct
  84. 84 folly::RecordIO — append-only 로그 파일 포맷
  85. 85 folly::io::Compression — zstd·lz4·snappy wrapper
  86. 86 folly::AsyncIO — io_uring·Linux AIO
  87. 87 folly::CancellationToken — 코루틴·Future 취소 전파
  88. 88 folly::observer — hot config의 atomic refresh
  89. 89 fbcode 패턴 모음 — folly 사용의 실전

관련 글

fbcode 패턴 모음 — folly 사용의 실전

Meta fbcode 코드 리뷰에서 반복적으로 등장하는 folly 사용 패턴 — overview + 시리즈 마무리.

· cpp

같은 시리즈에서 이어 읽기

folly::observer — hot config의 atomic refresh

folly::observer — read mostly 값의 atomic refresh, hot config·feature flag·LB weight 같은 패턴의 표준.

· cpp

같은 시리즈에서 이어 읽기

folly::CancellationToken — 코루틴·Future 취소 전파

CancellationSource/Token의 전파 모델 — coroutine·Future·callback 트리에서 협력적 취소.

· cpp

같은 시리즈에서 이어 읽기

이 글을 참조하는 글 (3)