Dokka Gradle 문제 해결

Dokka Gradle 문제 해결 (Dokka Gradle troubleshooting)

이 페이지는 Gradle 빌드에서 Dokka로 문서를 생성할 때 마주칠 수 있는 일반적인 문제들을 설명해요.

여기에 나오지 않은 문제라면, 이슈 트래커에 피드백이나 문제를 보고하거나 공식 Kotlin Slack에서 Dokka 커뮤니티와 대화해 보세요. Slack 초대는 여기에서 받을 수 있어요.

출처: Dokka Gradle troubleshooting

본문

메모리 문제 (Memory issues)

대규모 프로젝트에서 Dokka는 문서를 생성하기 위해 상당한 양의 메모리를 소비할 수 있어요. 특히 많은 양의 데이터를 처리할 때 Gradle의 메모리 한도를 초과할 수 있어요.

Dokka 생성이 메모리 부족으로 끝나면 빌드가 실패하고, Gradle이 java.lang.OutOfMemoryError: Metaspace 같은 예외를 던질 수 있어요.

Dokka의 성능을 개선하려는 노력이 진행 중이지만, 일부 제약은 Gradle에서 비롯돼요.

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

힙 공간 늘리기 (Increase heap space)

메모리 문제를 해결하는 한 가지 방법은 Dokka 생성기 프로세스의 Java 힙 메모리 양을 늘리는 거예요. build.gradle.kts 파일에서 다음 구성 옵션을 조정해요.

    dokka {
        // Dokka generates a new process managed by Gradle
        dokkaGeneratorIsolation = ProcessIsolation {
            // Configures heap size
            maxHeapSize = "4g"
        }
    }

이 예시에서는 최대 힙 크기를 4GB("4g")로 설정했어요. 빌드에 가장 적합한 설정을 찾으려면 값을 조정하고 테스트해 보세요.

Dokka가 상당히 늘어난 힙 크기를 요구한다는 것을 발견했다면(예: Gradle 자체의 메모리 사용량보다 훨씬 크다면), Dokka의 GitHub 저장소에 이슈를 만들어 주세요.

NOTE: 이 구성을 각 하위 프로젝트에 적용해야 해요. 모든 하위 프로젝트에 적용되는 컨벤션 플러그인에서 Dokka를 구성하는 것을 권장해요.

Gradle 프로세스 안에서 Dokka 실행하기 (Run Dokka within the Gradle process)

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

메모리 사용을 최적화하려면 Dokka를 별도 프로세스 대신 같은 Gradle 프로세스 안에서 실행할 수 있어요. 이렇게 하면 각 프로세스에 메모리를 따로 할당하는 대신 Gradle용 메모리를 한 번만 구성하면 돼요.

Dokka를 같은 Gradle 프로세스 안에서 실행하려면 build.gradle.kts 파일에서 다음 구성 옵션을 조정해요.

    dokka {
        // Runs Dokka in the current Gradle process
        dokkaGeneratorIsolation = ClassLoaderIsolation()
    }

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

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

NOTE: Gradle의 Java 옵션을 바꾸면 새 Gradle 데몬이 시작되는데, 이 데몬은 오랫동안 유지될 수 있어요. 다른 Gradle 프로세스를 수동으로 중지할 수 있어요.

추가로, ClassLoaderIsolation() 구성과 관련된 Gradle 이슈가 메모리 누수를 일으킬 수 있어요.