Создание приложения с использованием C Interop и libcurl – учебник

Создание проекта Kotlin/Native

1. В IntelliJ IDEA выберите Файл | Новый | Проект.

2. В левой панели выберите Kotlin Multiplatform | Приложение Native.

3. Укажите имя и выберите папку, в которую нужно сохранить ваше приложение.

   

4. Нажмите Далее, а затем Готово.

IntelliJ IDEA создаст новый проект с необходимыми файлами и папками. Важно понимать, что приложение, написанное на Kotlin/Native, может быть нацелено на различные платформы, если код не имеет платформ-специфических требований. Ваш код помещён в папку NativeMain с соответствующим NativeTest. Для этого учебника сохраните структуру папок такой, как есть.

Вместе с новым проектом генерируется файл build.gradle(.kts). Обратите особое внимание на следующее в файле сборки:

kotlin {
    val hostOs = System.getProperty("os.name")
    val isMingwX64 = hostOs.startsWith("Windows")
    val nativeTarget = when {
        hostOs == "Mac OS X" -> macosX64("native")
        hostOs == "Linux" -> linuxX64("native")
        isMingwX64 -> mingwX64("native")
        else -> throw GradleException("Host OS is not supported in Kotlin/Native.")
    }

    nativeTarget.apply {
        binaries {
            executable {
                entryPoint = "main"
            }
        }
    }
}

kotlin {
    def hostOs = System.getProperty("os.name")
    def isMingwX64 = hostOs.startsWith("Windows")
    def nativeTarget
        if (hostOs == "Mac OS X") nativeTarget = macosX64('native')
        else if (hostOs == "Linux") nativeTarget = linuxX64("native")
        else if (isMingwX64) nativeTarget = mingwX64("native")
        else throw new FileNotFoundException("Host OS is not supported in Kotlin/Native.")

    nativeTarget.with {
        binaries {
            executable {
                entryPoint = 'main'
            }
        }
    }
}

• Целевые платформы определяются с помощью macOSX64, linuxX64, и mingwX64 для macOS, Linux и Windows. Полный список поддерживаемых платформ см. в обзоре Kotlin Native.

• Сам entry определяет ряд свойств, указывающих на то, как генерируется двоичный файл и точка входа приложения. Эти значения можно оставить по умолчанию.

• Взаимодействие с C настроено как дополнительный этап сборки. По умолчанию все символы из C импортируются в пакет interop. Возможно, вы захотите импортировать весь пакет в файлы .kt. Узнайте больше о настройке этого.

Создание файла определения

При написании приложений для нативных платформ часто требуется доступ к определённым функциональным возможностям, которые не включены в стандартную библиотеку Kotlin, такие как отправка HTTP-запросов, чтение и запись из диска и так далее.

Kotlin/Native помогает использовать стандартные библиотеки C, открывая целый экосистему возможностей для практически всего, что может понадобиться. Kotlin/Native уже поставляется с набором предварительно собранных платформенных библиотек, которые предоставляют дополнительную общую функциональность стандартной библиотеке.

Идеальный сценарий для взаимодействия – вызов функций C так, как будто это функции Kotlin, с таким же сигнатурами и соглашениями. Именно для этого пригождается инструмент cinterop. Он принимает библиотеку C и генерирует соответствующие Kotlin-обвязки, так что библиотека может использоваться как будто это код Kotlin.

Для генерации этих обвязок создайте файл определения библиотеки .def содержащий информацию о необходимых заголовках. В этом приложении вам понадобится библиотека libcurl для отправки HTTP-запросов. Для создания файла определения:

1. Выберите папку src и создайте новую директорию с помощью Файл | Новый | Директория.

2. Назовите новую директорию nativeInterop/cinterop. Это общепринятое соглашение для расположения файлов заголовков, хотя его можно переопределить в файле build.gradle(.kts) при использовании другого расположения.

3. Выберите эту новую подпапку и создайте новый файл libcurl.def с помощью Файл | Новый | Файл.

4. Обновите ваш файл следующим кодом:

   headers = curl/curl.h
   headerFilter = curl/*
   
   compilerOpts.linux = -I/usr/include -I/usr/include/x86_64-linux-gnu
   linkerOpts.osx = -L/opt/local/lib -L/usr/local/opt/curl/lib -lcurl
   linkerOpts.linux = -L/usr/lib/x86_64-linux-gnu -lcurl
   

   • headers — список файлов заголовков для генерации Kotlin-заглушек. Вы можете добавить несколько файлов в эту запись, разделяя их символом \ в новой строке. В данном случае это только curl.h. Ссылающиеся файлы должны быть доступны в пути системы (в данном случае это /usr/include/curl).

   • headerFilter показывает, что именно включается. В C, все заголовки также включаются, когда один файл ссылается на другой с помощью директивы #include. Иногда это не требуется, и вы можете добавить этот параметр используя шаблоны glob для тонкой настройки.

     headerFilter — необязательный аргумент, который в основном используется, когда библиотека установлена как системная библиотека. Вам не нужно получать внешние зависимости (например, системный заголовок stdint.h ) в библиотеку взаимодействия. Это может быть важно для оптимизации размера библиотеки и устранения потенциальных конфликтов между системной и предоставляемой Kotlin/Native средой компиляции.

   • Следующие строки относятся к параметрам компоновщика и компилятора, которые могут отличаться в зависимости от разных целевых платформ. В данном случае это macOS (суффикс .osx) и Linux (суффикс .linux). Параметры без суффикса также возможны (например, linkerOpts=) и применяются ко всем платформам.

Соглашение заключается в том, что каждая библиотека получает свой файл определения, обычно с тем же именем, что и библиотека. Дополнительную информацию обо всех доступных параметрах cinterop см. в разделе Interop.

Добавление взаимодействия в процесс сборки

Для использования файлов заголовков убедитесь, что они генерируются в процессе сборки. Для этого добавьте следующую запись в файл build.gradle(.kts).

nativeTarget.apply {
    compilations.getByName("main") {    // NL
        cinterops {                     // NL
            val libcurl by creating     // NL
        }                               // NL
    }                                   // NL
    binaries {
        executable {
            entryPoint = "main"
        }
    }
}

nativeTarget.with {
    compilations.main { // NL
        cinterops {     // NL
            libcurl     // NL
        }               // NL
    }                   // NL
    binaries {
        executable {
            entryPoint = 'main'
        }
    }
}

Новые строки помечены как // NL. Сначала добавляется cinterops, а затем запись для каждого файла def. По умолчанию используется имя файла. Вы можете переопределить его с помощью дополнительных параметров:

val libcurl by creating {
    defFile(project.file("src/nativeInterop/cinterop/libcurl.def"))
    packageName("com.jetbrains.handson.http")
    compilerOpts("-I/path")
    includeDirs.allHeaders("path")
}

libcurl {
    defFile project.file("src/nativeInterop/cinterop/libcurl.def")
    packageName 'com.jetbrains.handson.http'
    compilerOpts '-I/path'
    includeDirs.allHeaders("path")
}

Подробнее о доступных параметрах см. в разделе Взаимодействие с C.

Напишите код приложения

Теперь у вас есть библиотека и соответствующие Kotlin-заглушки, и вы можете использовать их в своём приложении. Для этого урока преобразуйте пример simple.c в Kotlin.

В папке src/nativeMain/kotlin/ обновите свой файл Main.kt следующим кодом:

import kotlinx.cinterop.*
import libcurl.*

fun main(args: Array<String>) {
    val curl = curl_easy_init()
    if (curl != null) {
        curl_easy_setopt(curl, CURLOPT_URL, "https://example.com")
        curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L)
        val res = curl_easy_perform(curl)
        if (res != CURLE_OK) {
            println("curl_easy_perform() failed ${curl_easy_strerror(res)?.toKString()}")
        }
        curl_easy_cleanup(curl)
    }
}

Как вы можете видеть, явные объявления переменных устранены в версии на Kotlin, но всё остальное почти такое же, как и в версии на C. Все вызовы, которые вы ожидаете в библиотеке libcurl, доступны в эквиваленте на Kotlin.

Компиляция и запуск приложения

1. Скомпилируйте приложение. Для этого вызовите runDebugExecutableNative в списке задач Gradle или используйте следующую команду в терминале:

   ./gradlew runDebugExecutableNative
   

   В этом случае, сгенерированная часть cinterop неявно включается в сборку.

2. Если во время компиляции ошибок нет, щелкните зелёную иконку Запуск в области рядом с методом main() или используйте комбинацию клавиш Alt+Enter, чтобы вызвать меню запуска в IntelliJ IDEA.

   IntelliJ IDEA откроет вкладку Запуск и отобразит вывод — содержимое https://example.com.

   

Вы можете увидеть фактический вывод, потому что вызов curl_easy_perform выводит результат в стандартный вывод. Вы можете скрыть его, используя curl_easy_setopt.