Dokka Gradle 문제 해결

이 페이지는 Gradle 빌드에서 Dokka를 사용하여 문서를 생성할 때 발생할 수 있는 일반적인 문제들을 설명합니다.

문제가 여기에 나열되어 있지 않다면, 이슈 트래커에 의견이나 문제를 보고하거나 공식 Kotlin Slack의 Dokka 커뮤니티에서 대화해 보세요. Slack 초대장은 여기에서 받을 수 있습니다.

메모리 문제

대규모 프로젝트에서 Dokka는 문서를 생성하기 위해 상당한 양의 메모리를 사용할 수 있습니다. 특히 대량의 데이터를 처리할 때 Gradle의 메모리 제한을 초과할 수 있습니다.

Dokka 생성 시 메모리가 부족하면 빌드가 실패하며, Gradle은 java.lang.OutOfMemoryError: Metaspace와 같은 예외를 발생시킬 수 있습니다.

Dokka의 성능을 개선하기 위해 활발한 노력이 진행 중이지만, 일부 제한 사항은 Gradle에서 기인합니다.

메모리 문제가 발생하면 다음 해결 방법을 시도해 보세요:

• 힙 공간 늘리기
• Gradle 프로세스 내에서 Dokka 실행하기

힙 공간 늘리기

메모리 문제를 해결하는 한 가지 방법은 Dokka 생성기(generator) 프로세스의 Java 힙(heap) 메모리 용량을 늘리는 것입니다. build.gradle.kts 파일에서 다음 설정 옵션을 조정하세요:

    dokka {
        // Gradle이 관리하는 새로운 프로세스를 생성합니다.
        dokkaGeneratorIsolation = ProcessIsolation {
            // 힙 크기를 설정합니다.
            maxHeapSize = "4g"
        }
    }

이 예제에서는 최대 힙 크기가 4 GB("4g")로 설정되어 있습니다. 빌드에 가장 적합한 설정을 찾기 위해 값을 조정하고 테스트해 보세요.

만약 Dokka가 Gradle 자체의 메모리 사용량보다 현저히 높은 수준의 힙 크기를 요구한다면, Dokka GitHub 저장소에 이슈를 생성해 주세요.

이 설정은 각 서브프로젝트에 적용해야 합니다. 모든 서브프로젝트에 적용되는 컨벤션 플러그인(convention plugin)에서 Dokka를 구성하는 것을 권장합니다.

Gradle 프로세스 내에서 Dokka 실행하기

Gradle 빌드와 Dokka 생성 모두에 많은 메모리가 필요한 경우, 이들이 별도의 프로세스로 실행되어 단일 머신에서 상당한 메모리를 소모할 수 있습니다.

메모리 사용량을 최적화하려면 Dokka를 별도의 프로세스가 아닌 동일한 Gradle 프로세스 내에서 실행할 수 있습니다. 이렇게 하면 각 프로세스에 메모리를 별도로 할당하는 대신 Gradle용 메모리를 한 번만 설정하면 됩니다.

동일한 Gradle 프로세스 내에서 Dokka를 실행하려면 build.gradle.kts 파일에서 다음 설정 옵션을 조정하세요:

    dokka {
        // 현재 Gradle 프로세스 내에서 Dokka를 실행합니다.
        dokkaGeneratorIsolation = ClassLoaderIsolation()
    }

힙 공간 늘리기와 마찬가지로, 이 설정이 프로젝트에서 잘 작동하는지 테스트하여 확인하세요.

Gradle의 JVM 메모리 구성에 대한 자세한 내용은 Gradle 문서를 참조하세요.

Gradle의 Java 옵션을 변경하면 새로운 Gradle 데몬(daemon)이 실행되며, 이는 오랫동안 유지될 수 있습니다. 다른 Gradle 프로세스를 수동으로 중지할 수 있습니다.

또한, ClassLoaderIsolation() 설정과 관련된 Gradle 이슈로 인해 메모리 누수가 발생할 수 있습니다.