Tuesday, July 4, 2023

Flutter CLI: 개발 워크플로우를 혁신하는 명령어 활용법
  /   No comments   

Flutter는 뛰어난 UI 프레임워크일 뿐만 아니라, 강력하고 효율적인 커맨드 라인 인터페이스(Command Line Interface, CLI)를 제공합니다. 많은 개발자가 Android Studio나 VS Code와 같은 통합 개발 환경(IDE)의 편리한 버튼에 익숙하지만, Flutter CLI의 깊이와 잠재력을 이해하면 개발 워크플로우를 완전히 새로운 차원으로 끌어올릴 수 있습니다. CLI는 단순한 프로젝트 생성과 실행을 넘어, 섬세한 환경 설정, 정교한 빌드 파이프라인 구축, 자동화된 테스트 및 배포에 이르기까지 개발의 모든 단계를 제어할 수 있는 핵심 도구입니다.

이 글에서는 Flutter 개발자라면 반드시 알아야 할 핵심적인 CLI 명령어들을 단순히 나열하는 것을 넘어, 각 명령어가 어떤 상황에서 어떻게 활용될 수 있는지, 그리고 숨겨진 유용한 옵션들은 무엇인지 심도 있게 분석합니다. 개발 환경의 건강 상태를 진단하는 것부터 시작하여, 의존성 관리의 미묘한 차이를 이해하고, 다양한 플랫폼을 위한 맞춤형 빌드를 생성하는 과정까지, 실무에서 마주할 수 있는 다양한 시나리오를 바탕으로 CLI 명령어의 진정한 가치를 탐색해 보겠습니다.

1. 환경 설정 및 프로젝트 관리: 견고한 시작을 위한 토대

모든 성공적인 프로젝트는 잘 갖춰진 개발 환경에서 시작됩니다. Flutter CLI는 개발 환경을 진단하고, 프로젝트의 기본 구조를 설정하며, SDK 자체를 관리하는 강력한 명령어들을 제공하여 개발의 첫 단추를 올바르게 끼울 수 있도록 돕습니다.

1.1. 개발 환경 종합 진단: `flutter doctor -v`

flutter doctor는 Flutter 개발 여정의 가장 첫걸음이라 할 수 있는 명령어입니다. 이 명령어는 현재 시스템에 Flutter 개발에 필요한 모든 요소(Flutter SDK, 연결된 기기, 개발 도구 등)가 올바르게 설치되고 설정되었는지 종합적으로 검사합니다. 하지만 단순히 flutter doctor만 사용하는 것보다 -v (또는 --verbose) 플래그를 추가하면 훨씬 더 풍부하고 상세한 정보를 얻을 수 있습니다.

flutter doctor -v

이 명령어를 실행하면 다음과 같은 상세한 결과물을 볼 수 있습니다:

  • Flutter SDK 정보: 현재 사용 중인 Flutter의 버전, 채널(stable, beta, dev, master), 프레임워크 및 엔진의 리비전, Dart와 DevTools의 버전 등 SDK에 대한 모든 세부 정보가 표시됩니다. 이는 특정 버전에서 발생하는 버그를 추적하거나, 팀원들과 개발 환경을 동기화할 때 매우 중요합니다.
  • Android toolchain: Android SDK의 설치 경로, Android NDK의 위치, Java 바이너리 경로 등 안드로이드 개발에 필요한 도구들의 위치와 상태를 자세히 보여줍니다. 환경 변수(ANDROID_SDK_ROOT 등)가 잘못 설정되었을 경우, 이 상세 정보를 통해 문제의 원인을 정확히 파악할 수 있습니다.
    • - Xcode (macOS 전용): Xcode의 설치 경로, 버전, CocoaPods 설치 여부 및 버전 등을 확인합니다. iOS 빌드 문제를 해결하는 데 결정적인 단서를 제공합니다. - Chrome: 웹 개발을 위한 Chrome 브라우저의 설치 여부를 확인합니다. - Android Studio / VS Code: 설치된 IDE와 Flutter 및 Dart 플러그인의 버전 정보를 보여줍니다. 플러그인 충돌이나 버전 비호환성 문제를 진단할 때 유용합니다. - 연결된 기기: 현재 PC에 연결되고 인식된 모든 기기(물리적 기기, 에뮬레이터, 시뮬레이터)의 목록과 ID를 보여줍니다.

flutter doctor -v는 "문제가 있습니다"라는 단순한 진단을 넘어, "어떤 경로의 어떤 버전 도구에서 문제가 발생했습니다"와 같이 구체적인 원인을 제시해주므로, 복잡한 환경 설정 문제를 해결하는 데 없어서는 안 될 첫 번째 디버깅 도구입니다.

1.2. 프로젝트의 첫 삽: `flutter create`

flutter create는 새로운 Flutter 프로젝트를 생성하는 명령어입니다. 가장 기본적인 사용법은 다음과 같습니다.

flutter create my_awesome_app

하지만 이 명령어는 단순히 폴더와 파일을 생성하는 것 이상의 강력한 옵션들을 제공합니다.

  • 조직(Organization) 지정: --org 옵션을 사용하면 패키지 이름을 지정할 수 있습니다. 이는 특히 Android의 `applicationId`나 iOS의 `bundle identifier`를 초기부터 올바르게 설정하는 데 중요합니다. 
    flutter create --org com.example my_awesome_app
  • 템플릿 활용: --template 옵션으로 기본적인 카운터 앱 외의 다른 템플릿으로 프로젝트를 시작할 수 있습니다. 예를 들어, 재사용 가능한 패키지나 플러그인을 만들고 싶다면 다음과 같이 사용할 수 있습니다. 
    flutter create --template=package my_package
flutter create --template=plugin my_plugin
  • 지원 플랫폼 지정: --platforms 옵션을 사용하면 프로젝트가 지원할 플랫폼을 초기에 지정할 수 있습니다. 예를 들어, 모바일 앱만 개발할 계획이라면 불필요한 웹이나 데스크톱 관련 파일을 생성하지 않도록 할 수 있습니다. 
    flutter create --platforms=ios,android my_mobile_app

이러한 옵션들을 활용하면 프로젝트 초기 설정에 드는 시간을 절약하고, 처음부터 프로젝트의 목적에 맞는 명확한 구조를 갖출 수 있습니다.

1.3. Flutter SDK 관리 및 설정: `flutter upgrade`와 `flutter config`

개발 환경은 한 번 설정하고 끝나는 것이 아니라 지속적으로 관리되어야 합니다. Flutter는 새로운 기능 추가와 버그 수정이 활발하게 이루어지므로, SDK를 최신 상태로 유지하는 것이 중요합니다.

flutter upgrade

flutter upgrade 명령어는 현재 사용 중인 Flutter 채널의 최신 버전으로 SDK를 업데이트합니다. 이 과정에서 Flutter 프레임워크, 엔진, Dart SDK가 모두 함께 업데이트됩니다. 정기적으로 이 명령어를 실행하여 최신 기능과 성능 개선, 보안 패치의 이점을 누리는 것이 좋습니다.

한편, flutter config 명령어는 Flutter 도구 자체의 동작을 설정하는 데 사용됩니다. 예를 들어, 구글에 익명 사용 통계를 보내는 것을 원치 않는다면 다음과 같이 비활성화할 수 있습니다.

flutter config --no-analytics

또는, 데스크톱 지원과 같은 실험적인 기능을 활성화할 수도 있습니다. 예를 들어 macOS 개발을 활성화하려면 다음 명령어를 사용합니다.

flutter config --enable-macos-desktop

현재 설정된 모든 값을 확인하려면 아무 옵션 없이 flutter config를 실행하면 됩니다. 이 명령어는 Flutter의 동작을 자신의 개발 환경과 선호도에 맞게 미세 조정할 수 있게 해주는 강력한 도구입니다.

2. 개발, 실행, 디버깅: 살아있는 앱과의 상호작용

프로젝트의 토대가 마련되었다면, 이제 코드를 작성하고 앱을 실행하며 생명을 불어넣을 차례입니다. Flutter CLI는 개발 과정에서 가장 빈번하게 사용되는 실행 및 디버깅 관련 명령어들을 통해 생산성을 극대화합니다.

2.1. 실행 대상 확인: `flutter devices`

앱을 실행하기 전에, 어떤 기기에서 실행할 수 있는지 확인해야 합니다. flutter devices 명령어는 현재 컴퓨터에 연결되어 Flutter가 인식할 수 있는 모든 기기의 목록을 보여줍니다.

flutter devices

출력 결과에는 기기의 이름, 고유 ID, 지원 플랫폼, 그리고 연결 상태(에뮬레이터인지, 물리적 기기인지 등)가 포함됩니다. 여기서 얻은 'device id'는 이후 flutter run 명령어에서 특정 기기를 타겟팅할 때 매우 유용하게 사용됩니다.

2 devices connected.

sdk gphone64 x86 64 (mobile) • emulator-5554 • android-x64    • Android 12 (API 31) (emulator)
iPhone 14 Pro (mobile)      • 1234ABCD-5678-... • ios            • com.apple.CoreSimulator.SimRuntime.iOS-16-2 (simulator)

2.2. 앱 실행과 Hot Reload: `flutter run`

flutter run은 Flutter 개발의 핵심이라고 할 수 있는 명령어입니다. 이 명령어는 프로젝트를 컴파일하고 지정된 기기에 설치한 후 실행합니다. 하지만 이 명령어의 진정한 힘은 다양한 옵션과 'Hot Reload' 기능에 있습니다.

flutter run

기본적으로 이 명령어는 연결된 기기 중 하나를 선택하여 디버그 모드로 앱을 실행합니다. 만약 여러 기기가 연결되어 있다면 -d (또는 --device-id) 옵션으로 특정 기기를 지정할 수 있습니다.

flutter run -d emulator-5554

빌드 모드(Build Modes)

flutter run은 세 가지 주요 빌드 모드를 지원하며, 이는 앱의 성능과 디버깅 기능에 큰 영향을 미칩니다.

  • Debug Mode (기본값): Hot Reload와 디버깅을 위해 사용됩니다. 앱의 성능은 최적화되어 있지 않지만, 개발 속도를 비약적으로 향상시켜 줍니다. ASSERT 문과 서비스 확장이 활성화됩니다.
  • Profile Mode: --profile 플래그를 사용합니다. 실제 앱 성능을 측정하고 분석하는 데 사용됩니다. 디버깅 기능은 비활성화되지만, DevTools와 같은 프로파일링 도구를 사용할 수 있도록 최소한의 기능은 유지됩니다.
  • Release Mode: --release 플래그를 사용합니다. 사용자에게 배포될 최종 버전을 만들 때 사용됩니다. 모든 디버깅 기능이 제거되고, 성능과 앱 크기에 대해 최대한으로 최적화됩니다.

고급 실행 옵션

flutter run은 더 복잡한 개발 시나리오를 위한 강력한 옵션들을 제공합니다.

  • Flavor를 이용한 환경 분리: --flavor 옵션을 사용하면 개발(dev), 스테이징(staging), 프로덕션(prod) 등 다양한 환경에 맞는 앱을 빌드하고 실행할 수 있습니다. 이는 각 환경별로 다른 API 엔드포인트나 설정을 적용할 때 필수적입니다. 
    flutter run --flavor dev --target lib/main_dev.dart
  • 컴파일 시 변수 주입: --dart-define 옵션은 컴파일 시점에 코드에 상수를 주입하는 방법입니다. API 키나 중요한 설정 값을 소스 코드에 직접 하드코딩하지 않고 안전하게 관리할 수 있습니다. 
    flutter run --dart-define=API_KEY=YOUR_SECRET_KEY

2.3. 로그 추적 및 분석: `flutter logs`

IDE의 콘솔 출력을 넘어, 실행 중인 앱의 로그를 지속적으로 확인하고 싶을 때 flutter logs 명령어가 유용합니다. 이 명령어는 현재 연결된 기기에서 실행 중인 Flutter 앱의 모든 로그(print, log, 시스템 이벤트 등)를 실시간으로 스트리밍합니다.

flutter logs

이 명령어는 특히 앱이 예기치 않게 종료되거나, 백그라운드에서 동작하는 로직을 디버깅할 때 강력한 힘을 발휘합니다. --clear-logs 옵션을 사용하면 이전에 쌓인 로그를 모두 지우고 현재 시점부터의 로그만 확인할 수도 있어, 특정 문제를 재현하고 분석하는 데 집중할 수 있습니다.

3. 의존성 관리: 프로젝트의 생태계 다루기

현대적인 앱 개발에서 외부 패키지(의존성) 활용은 필수적입니다. Flutter는 `pub`이라는 강력한 패키지 관리 시스템을 가지고 있으며, CLI를 통해 이 의존성들을 효과적으로 관리할 수 있습니다. 의존성 관리를 잘못하면 'Dependency Hell'이라 불리는 복잡한 버전 충돌 문제에 빠질 수 있으므로, 관련 명령어들을 정확히 이해하는 것이 중요합니다.

3.1. 의존성 설치의 기본: `flutter pub get`

flutter pub get은 가장 기본적이면서도 중요한 의존성 관리 명령어입니다. 이 명령어는 프로젝트의 루트 디렉토리에 있는 `pubspec.yaml` 파일을 읽어와, `dependencies`와 `dev_dependencies`에 명시된 모든 패키지를 다운로드하고 프로젝트에 연결합니다.

flutter pub get

이 명령어는 다음과 같은 상황에서 실행해야 합니다.

  • 새로운 프로젝트를 클론(clone)했을 때
  • pubspec.yaml 파일에 새로운 의존성을 추가하거나 기존 의존성의 버전 제약 조건을 변경했을 때
  • 팀원이 의존성을 변경하고 원격 저장소에 푸시(push)한 코드를 풀(pull)했을 때

flutter pub get을 실행하면 `pubspec.lock` 파일이 생성되거나 업데이트됩니다. 이 파일은 현재 프로젝트에서 사용하기로 결정된 모든 의존성의 정확한 버전을 기록하는 '잠금 파일'입니다. 덕분에 팀의 모든 구성원이 `flutter pub get`을 실행하면 항상 동일한 버전의 패키지를 설치하게 되어, "제 컴퓨터에서는 잘 되는데요?"와 같은 문제를 방지할 수 있습니다.

3.2. 업데이트 가능한 패키지 확인: `flutter pub outdated`

프로젝트가 진행되면서 사용하는 패키지들은 계속해서 새로운 버전이 출시됩니다. 보안 패치, 버그 수정, 새로운 기능이 포함된 최신 버전을 사용하는 것이 좋지만, 어떤 패키지가 업데이트 가능한지 일일이 확인하는 것은 번거로운 일입니다. 이때 `flutter pub outdated` 명령어를 사용합니다.

flutter pub outdated

이 명령어는 `pubspec.yaml`에 명시된 모든 의존성을 분석하여, 현재 설치된 버전과 `pub.dev`에 등록된 최신 버전을 비교하여 표 형식으로 보여줍니다. 출력되는 표에는 다음과 같은 중요한 정보가 포함됩니다.

  • Current: 현재 `pubspec.lock` 파일에 기록된 버전
  • Upgradable: `pubspec.yaml`의 버전 제약 조건(예: `^1.0.4`)을 만족하면서 업데이트할 수 있는 가장 높은 버전
  • Resolvable: 다른 패키지와의 의존성 관계를 모두 고려했을 때, 실제로 업그레이드될 수 있는 버전. 만약 다른 패키지가 구버전의 패키지를 요구한다면 이 버전은 'Upgradable'보다 낮을 수 있습니다.
    • - Latest: 버전 제약 조건을 무시하고 현재 `pub.dev`에서 사용 가능한 가장 최신 버전

이 정보를 통해 어떤 패키지를 안전하게 업데이트할 수 있는지, 그리고 버전 제약 조건을 수정해야 하는지를 명확하게 판단할 수 있습니다.

3.3. 안전한 업그레이드 시뮬레이션: `flutter pub upgrade --dry-run`

패키지를 업그레이드하는 것은 때때로 예기치 않은 문제를 일으킬 수 있습니다. 특히, 메이저 버전(예: 1.x.x -> 2.x.x) 업데이트는 기존 코드와 호환되지 않는 변경(Breaking Change)을 포함할 수 있습니다. 실제 업그레이드를 진행하기 전에 어떤 변경이 일어날지 미리 확인해보고 싶을 때 --dry-run 옵션을 사용합니다.

flutter pub upgrade --dry-run

이 명령어는 실제 파일(pubspec.lock)을 변경하지 않고, flutter pub upgrade를 실행했을 경우 어떤 패키지가 어떤 버전으로 변경될지를 시뮬레이션하여 보여줍니다. 이를 통해 잠재적인 버전 충돌이나 큰 변화가 예상되는 패키지를 사전에 인지하고 대비할 수 있습니다. 문제가 없을 것이라 판단되면, 실제 업그레이드를 위해 flutter pub upgrade를 실행하면 됩니다.

3.4. 패키지 게시: `flutter pub publish`

만약 다른 개발자들이 사용할 수 있는 유용한 위젯이나 라이브러리를 직접 만들었다면, `pub.dev`에 게시하여 공유할 수 있습니다. `flutter pub publish` 명령어는 이 과정을 도와줍니다.

flutter pub publish

이 명령어를 실행하기 전에, `pubspec.yaml`에 패키지의 이름(name), 설명(description), 버전(version), 홈페이지(homepage) 등 필수적인 메타데이터가 잘 작성되어 있는지 확인해야 합니다. 또한, `CHANGELOG.md` 파일을 통해 버전별 변경 사항을 기록하는 것이 좋습니다. 게시하기 전, --dry-run 옵션을 사용하여 패키지에 문제가 없는지 최종 점검할 수 있습니다.

flutter pub publish --dry-run

이 사전 검사를 통해 `pub.dev`의 정책을 위반하거나 필수 정보가 누락된 부분을 미리 찾아 수정할 수 있습니다.

4. 테스트 및 코드 품질 유지

견고하고 유지보수하기 좋은 애플리케이션을 만들기 위해서는 테스트와 일관된 코드 스타일이 필수적입니다. Flutter CLI는 테스트를 실행하고 코드 형식을 자동으로 맞춰주는 도구를 내장하고 있어, 코드 품질을 높은 수준으로 유지하는 데 도움을 줍니다.

4.1. 자동화된 테스트 실행: `flutter test`

Flutter는 유닛 테스트, 위젯 테스트, 통합 테스트 등 다양한 수준의 테스트를 지원합니다. `flutter test` 명령어는 프로젝트 내의 `test` 디렉토리에 있는 모든 `_test.dart` 파일을 찾아 테스트를 실행하고 결과를 보고합니다.

flutter test

프로젝트가 커지면 모든 테스트를 실행하는 데 시간이 오래 걸릴 수 있습니다. 이 경우, 특정 파일이나 특정 테스트만 실행할 수 있습니다.

# 특정 파일의 모든 테스트 실행
flutter test test/my_widget_test.dart

# 특정 이름의 테스트만 실행
flutter test --plain-name "Counter increments smoke test"

테스트는 CI/CD(지속적 통합/지속적 배포) 파이프라인의 핵심적인 부분입니다. 새로운 코드가 추가될 때마다 자동으로 `flutter test`를 실행하도록 설정하면, 버그가 메인 브랜치에 통합되는 것을 사전에 방지하여 안정성을 크게 높일 수 있습니다.

4.2. 코드 스타일의 일관성: `flutter format`

여러 개발자가 함께 작업하는 프로젝트에서는 일관된 코드 스타일을 유지하는 것이 매우 중요합니다. 이는 코드 가독성을 높이고, 불필요한 스타일에 대한 논쟁을 줄여줍니다. `flutter format` 명령어는 Dart 공식 스타일 가이드에 따라 코드의 형식을 자동으로 맞춰줍니다.

# 특정 파일 포맷팅
flutter format lib/main.dart

# lib 디렉토리 내의 모든 dart 파일 포맷팅
flutter format lib/

IDE에서는 파일을 저장할 때마다 자동으로 포맷팅을 실행하도록 설정할 수 있지만, CLI 명령어는 Git의 pre-commit hook과 연동하여 커밋하기 전에 모든 변경된 파일의 형식을 강제하거나, CI 과정에서 코드 스타일을 검사하는 용도로 매우 유용하게 사용될 수 있습니다.

5. 빌드, 배포, 그리고 정리

개발과 테스트가 완료되면, 애플리케이션을 사용자에게 전달하기 위한 빌드 과정을 거쳐야 합니다. Flutter CLI는 다양한 플랫폼과 배포 시나리오에 맞는 정교한 빌드 옵션을 제공합니다.

5.1. 배포를 위한 최종 산출물 생성: `flutter build`

flutter build 명령어는 배포 가능한 앱 패키지를 생성합니다. 대상 플랫폼에 따라 다양한 하위 명령어를 가집니다.

  • Android:
    • flutter build apk: 단일 APK 파일을 생성합니다. 테스트나 직접 배포에 용이합니다.
    • flutter build appbundle: Google Play Store에 권장되는 형식인 AAB(Android App Bundle) 파일을 생성합니다. 사용자의 기기에 최적화된 APK를 Play Store가 동적으로 생성하여 전달하므로, 앱 다운로드 크기를 줄일 수 있습니다.
  • iOS:
    • flutter build ios: Xcode 프로젝트를 빌드하여 `.app` 파일을 생성합니다. (macOS 환경에서만 가능)
      • -
    • flutter build ipa: TestFlight나 App Store에 배포하기 위한 IPA 파일을 생성합니다.
    • - Web: flutter build web - Desktop: flutter build macos, flutter build windows, flutter build linux

이 명령어들은 기본적으로 릴리즈 모드(--release)로 동작하며, flutter run에서 사용했던 --flavor, --dart-define 같은 옵션들을 동일하게 사용할 수 있습니다. 추가로, 빌드 버전을 명시하는 옵션도 매우 중요합니다.

flutter build appbundle --build-name=1.0.0 --build-number=1

--build-name은 사용자에게 보여지는 버전 이름(예: '1.2.5')이고, --build-number는 스토어에서 버전을 구분하는 데 사용하는 내부적인 숫자(예: 1, 2, 3...)입니다.

보안 및 최적화 옵션

릴리즈 빌드 시에는 코드 보안과 최적화를 위한 추가 옵션을 고려해야 합니다.

  • --obfuscate: Dart 코드를 난독화하여 리버스 엔지니어링을 어렵게 만듭니다.
  • --split-debug-info: 디버그 정보를 별도의 파일로 분리하여 앱 크기를 줄이고, 나중에 프로덕션 환경에서 발생한 크래시 로그를 분석(symbolicate)하는 데 사용합니다.
flutter build apk --obfuscate --split-debug-info=./debug_info

5.2. 빌드 캐시 정리: `flutter clean`

때때로 의존성 문제, 네이티브 코드 변경, 또는 알 수 없는 이유로 빌드가 계속 실패하는 경우가 있습니다. 이런 상황에서 가장 먼저 시도해볼 수 있는 해결책이 바로 `flutter clean`입니다.

flutter clean

이 명령어는 프로젝트 루트 디렉토리의 `build` 폴더와 Dart 도구가 생성한 임시 파일들을 모두 삭제합니다. 이는 이전에 빌드되면서 생성된 캐시나 중간 산출물들이 일으킬 수 있는 충돌을 원천적으로 제거하는 효과가 있습니다. `flutter clean`을 실행한 후에는 반드시 `flutter pub get`을 다시 실행하여 의존성을 재설정하고, 그 다음에 빌드를 시도해야 합니다.

결론: 터미널 속의 지휘자

지금까지 살펴본 것처럼, Flutter CLI는 단순히 IDE의 버튼을 대체하는 도구가 아닙니다. 터미널의 검은 화면 속에서 몇 줄의 명령어를 입력하는 것은 개발의 전 과정을 더 깊이 이해하고, 더 정교하게 제어하며, 궁극적으로는 더 높은 생산성을 달성하기 위한 강력한 행위입니다. `flutter doctor`로 개발 환경의 건강을 진단하고, `flutter create`의 다양한 옵션으로 프로젝트의 청사진을 그리며, `flutter run`의 빌드 모드와 `dart-define`으로 유연하게 앱을 실행하고, `flutter build`의 세밀한 옵션으로 최종 결과물을 조각하는 모든 과정은 여러분을 단순한 코더가 아닌, 프로젝트의 흐름을 지휘하는 '지휘자'로 만들어 줄 것입니다.

여기에 소개된 명령어들은 빙산의 일각에 불과합니다. 각 명령어에 --help 플래그를 붙여(예: `flutter run --help`) 숨겨진 더 많은 옵션과 가능성을 탐색해 보세요. 터미널과 친숙해질수록, 여러분의 Flutter 개발 경험은 더욱 깊고 풍부해질 것입니다.


0 개의 댓글:

Post a Comment