mobile-env-study

Flutter 기반 모바일 앱 개발 환경을 밑바닥부터 이해하고, "팀원이 clone 후 한 줄로 실행 가능한 reproducible build"를 달성하기 위한 학습 레포.

왜 이 레포를 만들었나

shorebird + FVM + Xcode + CocoaPods + Flutter tool이 얽혀있는 상태에서 팀원 간 환경 차이로 빌드가 깨지는 경험을 반복했다. 증상만 쫓아서 해결하다 보니 근본을 이해 못 하고 있다고 느꼈고, 처음부터 체계적으로 짚어가며 학습하기로 함.

최종 목표: 어떤 동료가 레포를 clone 해도 ./setup.sh 한 줄로 완전한 개발 환경이 세팅되는 상태를 만든다.

학습 로드맵

각 챕터는 "읽기 30분 + 실험 1시간" 분량을 목표로.

Tier 1 — 이번 문제의 본질 (1~2일)

• 01. reproducible build 개념

  • 왜 .gitignore에 뭐가 들어가고 안 들어가는지
  • 체크인 vs 생성물 구분 (pubspec.lock 체크인 ✅ / build/ 체크인 ❌)
  • 로컬 머신에 의존하는 절대 경로는 절대 커밋하면 안 된다는 원칙

• 02. Flutter 빌드 파이프라인 (iOS)

  • flutter run이 실제로 뭘 하는가 (flutter tool 소스 훑기)
  • ios/Flutter/Generated.xcconfig — flutter가 생성하는 Xcode 설정
  • ios/Flutter/xcode_backend.sh — Xcode가 flutter를 호출하는 브리지
  • ios/Podfile이 .flutter-plugins를 읽는 흐름

• 03. CocoaPods 기초

  • Podfile vs Podfile.lock 관계
  • 플러그인 podspec이 버전 제약을 바꿀 때 왜 충돌 나는지
  • pod install vs pod update vs pod install --repo-update 차이

• 04. FVM & Shorebird

  • .fvmrc → .fvm/flutter_sdk 심링크 생성 흐름
  • 심링크가 절대 경로인 이유와 머신 간 깨짐 원인
  • Shorebird가 Flutter를 어떻게 fork했는지 (FlutterImplicitEngineDelegate 등)

Tier 2 — 팀 onboarding 자동화 (추가 1~2일)

• 05. setup 스크립트 패턴
  • Shell scripting 실무 (set -e, set -u, command -v, trap)
  • Homebrew Brewfile (시스템 도구 관리)
  • mise / asdf로 언어 런타임 버전 관리 (FVM 대안 검토)
  • Makefile · just 커맨드로 공통 인터페이스

Tier 3 — 선택적 심화 (시간 되면)

• Shorebird 아키텍처 (OTA update 원리, iOS에서 가능한 이유)
• Xcode 빌드 설정 (PCH, DerivedData, code signing, provisioning)
• CI/CD 관점 (GitHub Actions에서 위 모든 걸 재현)

종합 실습

• final-project/ — 작은 Flutter 앱 만들고 scripts/setup.sh 한 줄로 팀원이 clone 후 바로 실행 가능한 상태 달성

학습 원칙

1. 읽기만 하지 말고 직접 실험해서 뭐가 깨지는지 본다 (experiments/ 디렉토리 활용).
2. 실제 겪은 에러와 연결해서 정리한다 (단순 이론 요약 ❌).
3. 각 챕터 끝에 "이 챕터를 통해 알게 된 것" 3줄 이내 요약.
4. 에러/해결 과정은 오픈닥터 앱 로컬 환경 설정 노션 문서에도 누적.

레퍼런스

• Flutter 공식 문서 — How Flutter is built
• CocoaPods Guides
• FVM 공식 문서
• Shorebird 공식 문서