Kotlin/Native 바이너리 옵션

이 페이지에서는 Kotlin/Native 최종 바이너리를 구성할 때 유용한 바이너리 옵션들과, 프로젝트에서 바이너리 옵션을 설정하는 방법을 소개해요.

출처: Kotlin/Native binary options

본문

활성화 방법

바이너리 옵션은 gradle.properties 파일, 빌드 파일에서 설정하거나 컴파일러 인자로 전달할 수 있어요.

Gradle 프로퍼티에서

프로젝트의 gradle.properties 파일에서 kotlin.native.binary 프로퍼티를 사용해 바이너리 옵션을 설정할 수 있어요. 예:

kotlin.native.binary.latin1Strings=true

빌드 파일에서

build.gradle.kts 파일에서 프로젝트의 바이너리 옵션을 설정할 수 있어요.

특정 바이너리에 대해 binaryOption 속성을 사용해요. 예:

kotlin {
    iosArm64 {
        binaries {
            framework {
                binaryOption("smallBinary", "true")
            }
        }
    }
}

freeCompilerArgs 속성에 -Xbinary=$option=$value 컴파일러 옵션으로 전달해요. 예:

kotlin {
    iosArm64 {
        compilations.configureEach {
            compilerOptions.configure {
                freeCompilerArgs.add("-Xbinary=smallBinary=true")
            }
        }
    }
}

커맨드라인 컴파일러에서

Kotlin/Native 컴파일러를 실행할 때 커맨드라인에 -Xbinary=$option=$value로 직접 전달할 수 있어요. 예:

kotlinc-native main.kt -Xbinary=enableSafepointSignposts=true

바이너리 옵션

이 표는 존재하는 모든 옵션을 나열한 것이 아니라 가장 주목할 만한 옵션들만 정리한 것이에요.

옵션	값	설명	상태
`enableReleaseBinaryCache`	- `true` - `false`(기본값)	릴리스 모드에서 컴파일러가 캐시를 사용하게 해 빌드를 더 빠르게 만들지만, 일부 컴파일러 최적화는 희생돼요.	2.4.20부터 Experimental
`objcExportBlockExplicitParameterNames`	- `true` - `false`(기본값)	내보낸 Objective-C 헤더의 함수 타입에 명시적 파라미터 이름을 추가해요.	2.2.20부터 Experimental
`smallBinary`	- `true` - `false`(기본값)	릴리스 바이너리의 크기를 줄여요.	2.2.20부터 Experimental
`stackProtector`	- `yes` - `strong` - `all` - `no`(기본값)	스택 카나리(stack canary)를 활성화해요. 취약한 함수에는 `yes`, 모든 함수에는 `all`, 더 강한 휴리스틱을 쓰려면 `strong`을 사용해요.	2.2.20부터 사용 가능
`pagedAllocator`	- `true`(기본값) - `false`	할당의 페이징(버퍼링)을 제어해요. `false`면 메모리 할당자가 객체 단위로 메모리를 예약해요.	2.2.0부터 Experimental
`latin1Strings`	- `true` - `false`(기본값)	Latin-1 인코딩 문자열 지원을 제어해 애플리케이션 바이너리 크기를 줄이고 메모리 사용량을 조정해요.	2.2.0부터 Experimental
`mmapTag`	`UInt`	메모리 태깅을 제어해요. Apple 플랫폼에서 메모리 사용량 추적에 필요해요. 값 `240`–`255`를 쓸 수 있고(기본값은 `246`), `0`이면 태깅을 비활성화해요.	2.2.0부터 사용 가능
`disableMmap`	- `true` - `false`(기본값)	기본 할당자를 제어해요. `true`면 `mmap` 대신 `malloc` 메모리 할당자를 사용해요.	2.2.0부터 사용 가능
`gc`	- `cms`(기본값) - `pmcs` - `stwms` - `noop`	가비지 컬렉션 동작을 제어해요: - `cms`는 동시 마크 앤 스윕(concurrent mark and sweep) 사용 - `pmcs`는 병렬 마크 동시 스윕(parallel mark concurrent sweep) 사용 - `stwms`는 단순 stop-the-world 마크 앤 스윕 사용 - `noop`은 가비지 컬렉션 비활성화	`cms`가 2.4.0부터 기본값
`gcMarkSingleThreaded`	- `true` - `false`(기본값)	가비지 컬렉션의 마크 단계 병렬화를 비활성화해요. 큰 힙에서 GC 일시 중지 시간이 늘어날 수 있어요.	1.7.20부터 사용 가능
`enableSafepointSignposts`	- `true` - `false`(기본값)	Xcode Instruments에서 디버깅하기 위해 프로젝트의 GC 관련 일시 중지를 추적할 수 있게 해요.	2.0.20부터 사용 가능
`preCodegenInlineThreshold`	`UInt`	실제 코드 생성 단계 이전에 실행되는 Kotlin IR 컴파일러의 인라인 최적화 패스를 구성해요(기본적으로 비활성화). 권장 토큰 수(컴파일러가 파싱한 코드 단위)는 40이에요.	2.1.20부터 Experimental
`objcDisposeOnMain`	- `true`(기본값) - `false`	Swift/Objective-C 객체의 해제(deinitialization)를 제어해요. `false`면 메인 스레드 대신 전용 GC 스레드에서 해제가 일어나요.	1.9.0부터 사용 가능
`appStateTracking`	- `enabled` - `disabled`(기본값)	애플리케이션이 백그라운드에서 실행될 때 타이머 기반 GC 호출을 제어해요. `enabled`면 메모리 사용량이 너무 높아졌을 때만 GC가 호출돼요.	1.7.20부터 Experimental
`bundleId`	`String`	`Info.plst` 파일에 번들 ID(`CFBundleIdentifier`)를 설정해요.	1.7.20부터 사용 가능
`bundleShortVersionString`	`String`	`Info.plst` 파일에 짧은 번들 버전(`CFBundleShortVersionString`)을 설정해요.	1.7.20부터 사용 가능
`bundleVersion`	`String`	`Info.plst` 파일에 번들 버전(`CFBundleVersion`)을 설정해요.	1.7.20부터 사용 가능
`sourceInfoType`	- `libbacktrace` - `coresymbolication`(Apple 타깃) - `noop`(기본값)	예외 스택 트레이스에 파일 위치와 줄 번호를 추가해요. `coresymbolication`은 Apple 타깃에서만 사용할 수 있고, 디버그 모드의 macOS와 Apple 시뮬레이터에서는 기본적으로 활성화돼요.	1.6.20부터 Experimental

안정성 수준에 대한 자세한 내용은 관련 문서를 참고하세요.

다음 단계

최종 네이티브 바이너리를 빌드하는 방법을 알아보세요.

더 알아보기

새 메모리 관리자로 마이그레이션하기
Kotlin/Native 디버깅