Publishing Flet app to multiple platforms

Introduction

Flet CLI는 'flet build'커맨드를 제공하여 Flet앱을 실행파일이나 배포용 패키지로 만들 수 있다.

Platform matrix

	apk, aab	ipa	macos	linux	windows	web
MacOS	°	°	°			°
Windows	°			°(WSL)	°	°
Linux	°			°		°

Prerequisites

Flutter SDK

Flutter SDK 3.16이상이 설치되고 flutter와 dart커맨드 경로가 PATH 환경변수에 포함되어야 한다.
모든 플랫폼마다 플러터 필요사항이 있는 데, 가령 Mac의 경우 XCode와 Cocopods, Windows의 경우 Visual Studio2022가 필요하다. 리눅스의 경우 각종 추가툴과 라이브러리가 필요하다.

Project structure

'flet build' 명령은 다음과 같은 프로젝트구조를 가정하고 있다.

/assets/
    icon.png
main.py
requirements.txt
pyproject.toml

main.py는 Flet앱의 시작위치로 마지막에는 ft.app(main)함수로 끝난다.
assets은 애플리케이션의 자산(이미지,사운드,텍스트,기타)을 담고있는 폴더이다.
icon.png만 제공된다면 모든 플랫폼의 스플래시 화면이나 아이콘소스로 사용된다.
requirements.txt는 Flet앱에 필요한 파이썬 라이브러리 목록을 담고 있는 pip파일이다. 프로젝트 종속성 목록을 가져오기 위해 flet 빌드 명령에서 pyproject.toml을 사용할 수도 있다. 그러나 requirements.txt와 pyproject.toml이 모두 존재하는 경우 pyproject.toml은 무시된다.

프로젝트를 적합한 구조로 가장 편하게 시작하려면 flet create명령을 사용한다.

flet create myapp

How it works

flet build <target_platform> 커맨드는 Flet앱의 루트디렉토리에서 실행된다.

<flet_app_directory> % flet build <target_platform>

<target_platform>은 apk, aab, ipa, web, macos, windows, linux중 하나다.
다른 디렉토리 <path_to_python_app>에서 실행한다면 다음과 같이 한다

flet build <target_platform> <path_to_python_app>

빌드결과는 <python_app_directory>/build/<target_platform>에 만들어 진다. --output옵션을 지정할 수 있다.

flet build <target_platform> --output <path-to-output-dir>

Including optional controls

앱이 다음과 같은 컨트롤을 사용한다면, 컨트롤 관련 패키지가 빌드명령에 포함되어야 한다.

• Audio control implemented in flet_audio package.
• AudioRecorder control implemented in flet_audio_recorder package.
• Lottie control implemented in flet_lottie package.
• Rive control implemented in flet_rive package.
• Video control implemented in flet_video package.
• WebView control implemented in flet_webview package.

--include-packages <package_1> <package_2> ...옵션을 사용하여 플러터 패키지를 추가한다.
예를 들어 비디오와 오디오컨트롤을 사용한다면 빌드명령에 --include-packages flet_video flet_audio를 추가한다.

flet build apk --include-packages flet_video flet_audio

Icons

Flet 앱의 assets디렉토리에는 아이콘 이미지를 넣어둔다. 플랫폼별 아이콘을 다음과 같이 한다.

• iOS - icon_ios.png (or any supported image format). Recommended minimum image size is 1024 px. Image should not be transparent (have alpha channel). Defaults to icon.png with alpha-channel automatically removed.
• Android - icon_android.png (or any supported image format). Recommended minimum image size is 192 px. Defaults to icon.png.
• Web - icon_web.png (or any supported image format). Recommended minimum image size is 512 px. Defaults to icon.png.
• Windows - icon_windows.png (or any supported image format). ICO will be produced of 256 px size. Defaults to icon.png. If icon_windows.ico file is provided it will be just copied to windows/runner/resources/app_icon.ico unmodified.
• macOS - icon_macos.png (or any supported image format). Recommended minimum image size is 1024 px. Defaults to icon.png.

Splash screen

아이콘과 마찬가지로 assets디렉토리에 플랫폼별 이미지 파일을 넣어둔다.

• iOS (light) - splash_ios.png (or any supported image format). Defaults to splash.png and then icon.png.
• iOS (dark) - splash_dark_ios.png (or any supported image format). Defaults to light iOS splash, then to splash_dark.png, then to splash.png and then icon.png.
• Android (light) - splash_android.png (or any supported image format). Defaults to splash.png and then icon.png.
• Android (dark) - splash_dark_android.png (or any supported image format). Defaults to light Android splash, then to splash_dark.png, then to splash.png and then icon.png.
• Web (light) - splash_web.png (or any supported image format). Defaults to splash.png and then icon.png.
• Web (dark) - splash_dark_web.png (or any supported image format). Defaults to light web splash, then splash_dark.png, then to splash.png and then icon.png.
  --splash-dark-color(다크모드인 경우)와 --splash-color(라이트모드) 옵션으로 스플래시 배경색상을 지정할 수 있으며 기본값은 #333333과 #ffffff이다.

Flet app entry point

'flet build'명령은 main.py를 Flet앱의 시작지점으로 가정한다. '--module-name'인수를 사용하여 시작지점을 달리 지정할 수 있다.

Versioning

'--build-number'와 '--build-version'으로 버전정보를 제공할 수 있다. 이는 앱스토어와 플레이스토어에서 빌드/출시버전을 구분해주는 데 사용된다. 또 about 대화상자에 표시되는 버전정보로 표시된다.
'--build-number'(기본값은 1)는 정수값으로 내부버전번호 식별자로 사용된다. 매번 빌드마다 이전 빌드와 구분되는 유일한 식별자를 가진다. 이는 빌드가 다른 이전 빌드와 구분하는 데 사용하며, 높은 숫자가 최근 빌드임을 가리킨다.
'--build-version'(기본값은 1.0.0)은 'x.y.z'형태의 문자열로 사용자에게 보여주는 버전번호로 사용된다. 앱의 새버전에 대해 이전 버전과 다른 버전번호를 부여할 것이다.

Customizing packaging template

임시 플러터 프로젝트를 만들기 위해 'flet build'는 https://github.com/flet-dev/flet-build-template에 저장된 쿠키커터 템플릿(cookiecutter template)을 이용한다. flet build를 사용하여 필요에 맞춘 템플릿을 만들어 사용할 수 있다.

'--template'옵션은 저장소URL이나 템플릿폴더 경로에 템플릿을 저장하는 데 사용한다. 깃허브의 경우 'gh:'로 시작한다(예를 들어 gh:{my-org}/{my-repo}) 또는 깃허브 전체 경로를 사용한다(https://github.com/{my-org}/{my-repo}.git)

Extra args to flutter build command

--flutter-build-args 옵션은 flutter build 명령에게 추가 매개변수를 전달한다. 옵션은 여러 개를 붙여 사용할 수 있다. 가령 --no-tree-shake-icons 옵션을 추가한다면

flet build macos --flutter-build-args=--no-tree-shake-icons

값을 가진 옵션을 추가한다면

flet build ipa --flutter-build-args=--export-method --flutter-build-args=development

Verbose logging

--verbose 또는 -vv 옵션은 flet build 동안 모든 명령의 결과를 보여주도록한다.

Logging

stdout과 stderr로 모든 Flet앱의 결과를 out.log파일로 돌릴 수 있다. 파일 출력은 unbuffered이므로 다음과 같이 간단히 읽어들일 수 있다.

with open("out.log", "r") as f:
    log = f.read()

AlertDialog 또는 기타 컨트롤은 log변수 값을 보여주기 위해 사용할 수 있다. 종료코드 100으로 sys.exit()를 호출하며 프로그램이 종료될 때 전체 로그는 스크롤가능 창에 표시된다.

import sys
sys.exit(100)

다른 종료코드로 sys.exit()를 호출하면 로그표시없이 앱이 종료된다.