Python 생태계의 패키징 도구인 Briefcase는 직접 관리하지 않는 외부 빌드 결과물(Artifacts)을 가져와 각 운영체제에 최적화된 설치 프로그램으로 변환하는 기능을 제공합니다. 이 방식은 PyInstaller나 py2app 등 다른 도구로 먼저 빌드된 애플리케이션을 MSI, DMG, DEB와 같은 공식 배포 형식으로 래핑할 때 매우 유용합니다.

외부 애플리케이션 패키징의 핵심 개념

표준적인 Briefcase 프로젝트와 달리 외부 앱 패키징 모드에서는 sources 항목을 정의하지 않습니다. 대신 external_package_path 설정을 통해 이미 준비된 빌드 결과물의 위치를 지정합니다. Briefcase는 지정된 경로의 파일들을 수집하여 서명(Signing), 공증(Notarization), 그리고 설치 프로그램 메타데이터 생성을 수행합니다.

플랫폼별 설정 최적화

macOS 배포 설정

macOS에서 외부 앱을 패키징할 때는 이미 유효한 .app 번들이 존재해야 합니다. 단일 바이너리 파일은 지원되지 않으며, 반드시 디렉토리 구조를 갖춘 앱 번들이어야 합니다.

• external_package_path: 배포할 .app 파일의 경로를 지정합니다.
• formal_name: 이 설정값은 반드시 .app 번들의 실제 이름과 정확히 일치해야 합니다. (예: "MyTool.app"인 경우 "MyTool"로 설정)

Briefcase는 패키징 과정에서 앱 번들 내부 요소와 최종 생성되는 DMG 또는 PKG 파일에 대해 자동으로 코드 서명 및 Apple 공증 절차를 진행합니다.

Linux(Debian/Ubuntu) 설정

Linux 환경에서는 설치될 시스템의 루트 구조를 모방한 디렉토리가 필요합니다.

# pyproject.toml 설정 예시
[tool.briefcase.app.myapp.linux]
external_package_path = "build/linux_root"
system_runtime_requires = ["libgtk-3-0", "libglu1-mesa"]

위 설정에서 build/linux_root 폴더 내부에는 usr/bin/myapp과 같은 경로로 실행 파일이 배치되어 있어야 합니다. 또한 Linux 패키징 시에는 소머 코드 의존성인 requires 대신 시스템 라이브러리 수준의 의존성인 system_runtime_requires를 반드시 정의해야 합니다.

Windows(MSI) 설정

Windows 패키징 시에는 Program Files 디렉토리에 설치될 모든 정적 리소스가 포함된 폴더를 지정합니다.

# pyproject.toml 설정 예시
[tool.briefcase.app.myapp.windows]
external_package_path = "out/win64_build"
external_package_executable_path = "bin/launcher.exe"

기본적으로 Briefcase는 앱의 formal_name과 일치하는 실행 파일을 검색하지만, external_package_executable_path 옵션을 통해 실제 실행 파일의 상대 경로를 사용자 정의할 수 있습니다.

패키징 워크플로우 실습

외부 앱 패키징은 별도의 중간 빌드 단계 없이 곧바로 package 명령어를 실행하여 진행합니다.

macOS 실행 예시

$ briefcase package
[my-app] Packaging external content from /Users/dev/dist/My-App.app
...
[my-app] Packaged dist/My-App-1.2.0.dmg

Windows 실행 예시

C:\> briefcase package
[my-app] Packaging external content from .\out\win64_build
...
[my-app] Packaged dist\My_App-1.2.0.msi

주의사항 및 권장 사항

패키징에 사용되는 메타데이터를 수정해야 할 경우, Briefcase가 생성한 임시 템플릿 파일(예: Entitlements.plist)을 직접 편집하는 것은 권장되지 않습니다. Briefcase는 실행 시마다 해당 파일을 다시 생성하므로, 모든 변경 사항은 pyproject.toml의 entitlements 항목을 통하거나 커스텀 template을 지정하는 방식으로 관리해야 합니다.

또한, 동일한 버전의 패키지를 중복 생성할 경우 기존 앱 데이터를 덮어쓸 것인지 묻는 경고가 나타날 수 있습니다. 이는 패키징을 위한 주변 메타데이터에만 영향을 주며, 원본 소스인 external_package_path 내부의 데이터는 변경되지 않습니다.