Как встроить С-библиотеку в Swift-фреймворк

В 2014 году был представлен Swift, новый язык для разработки приложений экосистемы Apple. Новинка принесла не только новые возможности и функции, но и проблемы — тем, кто хотел пользоваться старыми добрыми C-библиотеками. В этой статье я рассмотрю одну из них — бандлинг C-библиотеки в Swift-фреймворк. Существует несколько способов её решения; в данном случае я объясню, как сделать это при помощи clang explicit-модулей.

Для примера мы возьмём внешнюю C-библиотеку libgif ^[1] и встроим её в наш Swift-фреймворк GifSwift. Если вы хотите сразу увидеть результат, полностью проект можно посмотреть здесь ^[2].

Подготовка libgif

Прежде чем внедрять в наш проект библиотеку libgif, её нужно собрать из исходников.

1. Скачиваем последнюю версию тарболла здесь ^[3].
2. Распаковываем архив, при помощи консоли заходим в папку и запускаем:

   ./configure && make check

   Примечание: для простоты мы собираем библиотеку для платформы x86-64, а потому она будет работать только в iOS-симуляторе или на macOS. Построение мультиархитектурной статической библиотеки – отдельная тема, которой я не касаюсь в этой статье. Полезные инструкции вы найдёте здесь ^[4].

3. Если всё пройдёт без ошибок, файлы библиотеки можно будет найти в ${lib_gif_source}/lib/.libs. Нас интересуют два файла:

   lib/.libs/libgif.a # Статическая библиотека
   lib/gif_lib.h # Интерфейс
   

Настройка проекта

Теперь настроим проект под наши нужды.

1. Создаём новый проект при помощи шаблона Cocoa Touch Framework, даём ему имя GifSwift.
2. Добавляем созданные нами файлы библиотеки libgif в отдельную группу внутри проекта.
3. Добавляем в проект новый таргет для тестового приложения, чтобы посмотреть результат.

Итоговая структура проекта должна выглядеть примерно так:

Импортируем в Swift

Для того чтобы импортировать C-библиотеку в Swift, мы должны описать её как модуль ^[5]. Описание представляет собой файл .modulemap, содержащий список заголовочных файлов для импорта и статических библиотек для линковки. Полученный модуль может быть импортирован в Swift или Objective-C-код (при помощи @import).

Этот способ импорта библиотеки во фреймворк будет работать в большинстве случаев (более подробно об этом подходе читайте здесь ^[6]). Он отлично подходит, если вы создаёте внутренний фреймворк или просто разбиваете своё приложение на модули. Но такой способ также имеет и недостатки. Например, он неэффективен в том случае, если вы хотите передать свою библиотеку кому-то при помощи Carthage, Cocoapods или в виду бинарного артефакта. Причина в том, что получившийся фреймворк в общем случае не портируем, поскольку при компиляции он привязывается к конкретному расположению заголовочных файлов и библиотек из module map на вашем компьютере.

Явный модуль

Чтобы обойти эти ограничения, воспользуемся ещё одним способом — explicit-модулем для библиотеки. Еxplicit-модуль — это модуль, который объявляется подмодулем при помощи ключевого слова explicit, помещается в родительский модуль и не импортируется автоматически. Он работает аналогично *_Private.h для фреймворков Objective-C. Если вы хотите использовать объявленные в нём API, необходимо импортировать модуль явно (explicitly).

Мы создаём явный модуль для C-библиотеки внутри фреймворка. Для этого нам нужно провести переопределение сгенерированного XCode-модуля. Также обратите внимание на то, что мы не указываем библиотеку libgif.a для линковки (link gif), а вместо этого сделаем это прямо в проекте, используя интерфейс XCode.

Примечание: узнать больше об explicit-модулях можно по ссылке ^[5]

1. Добавляем в корневую папку проекта файл с названием GifSwift.modulemap:

   framework module GifSwift {
       umbrella header "GifSwift.h"
   
       explicit module CLibgif {
           private header "gif_lib.h"
       }
   
       export *
   }
   

   Этот файл содержит спецификацию для явного модуля CLibgif и состоит из одного объявленного заголовочного файла (поскольку в нашей библиотеке как раз один такой). Файл загружается в получившийся модуль для фреймворка.

2. Файл с описанием модуля не нужно добавлять в состав фреймворка, но он должен быть указан в настройках таргета:

   Build Settings — Packaging — Module Map (MODULEMAP_FILE)
   =
   $SRCROOT/GifSwift/GifSwift.modulemap

3. libgif-файлы должны быть добавлены в таргет фреймворка в виде приватного хедера (gif_lib.h) и статической библиотеки (libgif.a). Обратите внимание на то, что заголовочный файл для C-библиотеки добавлен в таргет как private. Это необходимо для нашего explicit-модуля. Ничто не мешает добавить этот заголовочный файл как public, но наша задача – скрыть детали реализации как можно более простыми средствами.

   

4. Теперь можно импортировать явный модуль внутри фреймворка при помощи import GifSwift.CLibgif

Swift-обёртка

Теперь можно заняться интерфейсом нашего фреймворка. Достаточно одного класса, представляющего собой гифку с парой свойств:

import Foundation
import GifSwift.CLibgif

public class GifFile {

    private let path: URL
    private let fileHandlePtr: UnsafeMutablePointer<GifFileType>
    private var fileHandle: GifFileType {
        return self.fileHandlePtr.pointee
    }

    deinit {
        DGifCloseFile(self.fileHandlePtr, nil)
    }

    // MARK: - API
    public init?(path: URL) {
        self.path = path

        let errorCode = UnsafeMutablePointer<Int32>.allocate(capacity: 1)
        if let handle = path.path.withCString({ DGifOpenFileName($0, errorCode) }) {
            self.fileHandlePtr = handle
            DGifSlurp(handle)
        } else {
            debugPrint("Error opening file (errorCode.pointee)")
            return nil
        }
    }

    public var size: CGSize {
        return CGSize(width: Double(fileHandle.SWidth), height: Double(fileHandle.SHeight))
    }

    public var imagesCount: Int {
        return Int(fileHandle.ImageCount)
    }
}

GifFile.swift оборачивает низкоуровневые программные интерфейсы для обработки файлов и получает доступ к некоторым свойствам, отображая их на более удобные типы Foundation.

Проверка

Для того чтобы протестировать нашу библиотеку, я добавил в проект файл cat.gif:

import UIKit
import GifSwift

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        if let file = GifFile(path: Bundle.main.url(forResource: "cat", withExtension: "gif")!) {
            debugPrint("Image has size: (file.size) and contains (file.imagesCount) images")
        }
    }
}

При запуске этого кода в консоли мы увидим следующее:

"Image has size: (250.0, 208.0) and contains 44 images"

Получившийся фреймворк содержит всё необходимое для использования, имеет Swift-интерфейс и по умолчанию скрывает C-код от клиентов. Впрочем, это не совсем правда. Как я писал выше, импортируя GifSwift.CLibgif, вы получите доступ ко всем закрытым модулям, однако по умолчанию такого метода инкапсуляции достаточно, чтобы скрыть детали реализации фреймворка.

Автор: lemsergey

Источник ^[7]