컴파일 환경 선언으로 앱 구성하기

컴파일 환경 선언으로 앱 구성하기 (Configuring apps with compilation environment declarations)

컴파일 환경 선언(compilation environment declaration)으로 애플리케이션 동작을 커스터마이즈하는 방법을 배워 볼게요.

출처: Configuring apps with compilation environment declarations

본문

Dart 애플리케이션을 빌드하거나 실행할 때 컴파일 환경 선언(compilation environment declarations) 을 지정할 수 있어요. 컴파일 환경 선언은 컴파일 시점에 접근되고 평가되는 키-값 쌍으로 구성 옵션을 지정해요.

참고 이 페이지는 "환경(environment)"을 Dart 컴파일 환경을 가리키는 말로 사용해요. 이 용어의 흔한 용법은 운영 체제 환경을 가리켜요.

여러분의 앱은 환경 선언의 값을 사용해 기능이나 동작을 바꿀 수 있어요. Dart 컴파일러는 환경 선언 값을 사용한 제어 흐름 때문에 도달할 수 없게 된 코드를 제거할 수 있어요.

다음과 같은 이유로 환경 선언을 정의하고 사용할 수 있어요:

  • 디버깅 중에 기능 추가하기 (로깅 활성화 같은).
  • 애플리케이션의 별도 변형(flavor) 만들기.
  • HTTP 서버의 포트처럼 애플리케이션 동작 구성하기.
  • 테스트를 위해 애플리케이션의 실험 모드 활성화하기.
  • 테스트 백엔드와 프로덕션 백엔드 사이를 전환하기.

Dart 애플리케이션을 실행하거나 컴파일할 때 환경 선언을 지정하려면 --define 옵션이나 그 약어 -D를 사용해요. <NAME>=<VALUE> 형식으로 선언 키-값 쌍을 지정해요:

$ dart run --define=DEBUG=true -DFLAVOR=free

이 선언들을 다른 도구로 설정하는 방법을 배우려면 이 가이드의 환경 선언 지정하기 섹션을 확인하세요. 그 섹션은 선언 문법과 커맨드라인 및 IDE·에디터에서 지정하는 방법을 설명해요.

환경 선언에 접근하기 (Accessing environment declarations)

지정된 환경 선언 값에 접근하려면 fromEnvironment 생성자 중 하나를 const와 함께 또는 상수 컨텍스트 안에서 사용해요. true/false 값에는 bool.fromEnvironment, 정수 값에는 int.fromEnvironment, 그 외의 것에는 String.fromEnvironment을 사용해요.

참고 환경 선언 생성자들은 const로 호출될 때만 동작한다고 보장돼요. 대부분의 컴파일러는 그 값을 컴파일 시점에 평가할 수 있어야 해요.

fromEnvironment 생성자들은 각각 환경 선언의 이름 또는 키를 필요로 해요. 또한 기본 대체 값을 덮어쓰는 선택적 defaultValue 명명 인자도 받아들여요. 기본 대체 값은 선언이 정의되지 않았거나 지정된 값을 기대 타입으로 파싱할 수 없을 때 사용돼요.

예를 들어, 환경 선언 DEBUG가 true로 설정됐을 때만 로그 메시지를 출력하고 싶다면:

void log(String message) {
  // Log the debug message if the environment declaration 'DEBUG' is `true`.
  // If there was no value specified, do not log.
  if (const bool.fromEnvironment('DEBUG', defaultValue: false)) {
    print('Debug: $message');
  }
}

이 조각에서 컴파일 중에 DEBUG가 false로 설정되어 있거나 전혀 지정되지 않았다면, 프로덕션 컴파일러는 그 조건과 본문을 완전히 제거할 수 있어요.

fromEnvironment 생성자들은 선언이 지정되지 않았거나 지정된 값을 파싱할 수 없을 때 기본 값으로 폴백해요. 따라서 환경 선언이 지정되었는지 구체적으로 확인하려면 bool.hasEnvironment 생성자를 사용해요:

if (const bool.hasEnvironment('DEBUG')) {
  print('Debug behavior was configured!');
}

환경 선언 지정하기 (Specifying environment declarations)

경고 Dart 도구와 컴파일러는 현재 쉼표로 구분된 값이 있는 환경 선언을 일관되게 처리하지 않아요. 이 처리의 표준화를 추적하려면 SDK issue 44995를 참고하세요.

Dart CLI

dart run과 dart compile 하위 명령 모두 환경 선언 값을 지정하기 위한 임의 개수의 -D 또는 --define 옵션을 받아들여요.

$ dart run --define=DEBUG=true -DFLAVOR=free main.dart
$ dart compile exe --define=DEBUG=true -DFLAVOR=free main.dart
$ dart compile js --define=DEBUG=true -DFLAVOR=free main.dart
$ dart compile aot-snapshot --define=DEBUG=true -DFLAVOR=free main.dart
$ dart compile jit-snapshot --define=DEBUG=true -DFLAVOR=free main.dart
$ dart compile kernel --define=DEBUG=true -DFLAVOR=free main.dart
webdev

개발용 및 프로덕션용 웹 컴파일러 양쪽에 환경 선언을 전달하도록 webdev를 구성하는 방법은 webdev 구성 문서를 확인하세요.

Visual Studio Code

런치 구성(launch.json)의 configurations 아래에 원하는 환경 선언을 담은 새 toolArgs 키를 추가해요:

"configurations": [
    {
        "name": "Dart",
        "request": "launch",
        "type": "dart",
        "toolArgs": [
          "--define=DEBUG=true"
        ]
    }
]

자세한 내용은 VS Code 런치 구성 문서를 확인하세요.

JetBrains IDE

프로젝트의 Run/Debug Configurations에서 VM 옵션에 원하는 환경 선언을 추가해요.

[그림] JetBrains IDE에 define 옵션 추가하기

자세한 내용은 JetBrains의 Dart Run/Debug Configurations 문서를 확인하세요.

Flutter

Flutter 도구에 환경 선언을 지정하려면 대신 --dart-define 옵션을 사용해요:

$ flutter run --dart-define=DEBUG=true

더 알아보기