Сборка библиотеки из исходников

Репозиторий библиотеки содержит набор исходных модулей, каждый из которых реализует отдельный криптографический примитив или вспомогательную функциональность: генерацию случайных чисел, симметричное шифрование, хэш-функции, режимы работы блочных шифров, кодировки и утилиты работы с битовыми массивами. Основная идея сборки заключается в объединении этих модулей в единый файл sjcl.js, пригодный для использования в браузере или Node.js.

Исходная структура проекта организована так, чтобы отделить «ядро» библиотеки от расширяемых компонентов. Каталог core содержит базовые реализации криптографических алгоритмов и утилит. Каталог test используется для модульного тестирования. Каталог build содержит инструменты сборки и конфигурационные файлы, определяющие, какие части библиотеки попадут в итоговый бандл.

Сборка библиотеки опирается на минимальный набор внешних инструментов, которые используются только на этапе компиляции:

интерпретатор Python (для выполнения скриптов объединения модулей)
Java (опционально, для запуска Closure Compiler при минимизации)
утилита make (для автоматизации последовательности сборки)
стандартные средства командной строки Unix или их аналоги в Windows-среде

Важным моментом является отсутствие runtime-зависимостей: итоговый файл не требует сторонних библиотек и полностью самодостаточен.

Механизм объединения модулей

Сборка начинается с формирования списка исходных файлов. Этот список определяется конфигурацией, где явно перечислены модули ядра и дополнительные компоненты.

Каждый модуль представляет собой JavaScript-файл, который не предполагает использования системы import/export в классическом виде. Вместо этого применяется последовательная конкатенация файлов с соблюдением порядка зависимостей.

Ключевая роль принадлежит скрипту упаковки (packager), который:

читает список модулей
анализирует зависимости между ними
объединяет их в единый файл
добавляет служебные обёртки пространства имён sjcl

Базовая сборка без минификации

Процесс базовой сборки ориентирован на получение читаемой версии библиотеки. Он используется для отладки и разработки.

Последовательность операций включает:

запуск скрипта упаковки из каталога build
чтение всех файлов из core
последовательную конкатенацию кода
формирование итогового файла sjcl.js

На этом этапе код остаётся не минифицированным, с сохранением структуры и отступов. Это упрощает диагностику ошибок и анализ внутренней логики.

Конфигурация включаемых модулей

Гибкость библиотеки обеспечивается возможностью выбора компонентов, которые попадут в сборку. Это реализуется через конфигурационные списки, где указываются:

криптографические алгоритмы (AES, SHA, HMAC и др.)
режимы шифрования (CBC, CCM, GCM при наличии реализации)
утилиты кодирования (Base64, Hex, BitArray)
генератор случайных чисел

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

Минимизация и оптимизация

Для production-сборки применяется дополнительный этап оптимизации. Он заключается в пропуске итогового файла через Java-based Closure Compiler.

Процесс включает:

генерацию промежуточного sjcl.js
передачу файла в Closure Compiler
применение агрессивной минификации:
- сокращение имён переменных
- удаление неиспользуемого кода
- инлайнинг простых функций
- оптимизация выражений

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

Режимы сборки

Система сборки обычно поддерживает несколько предустановленных режимов:

базовая сборка (без минификации)
полная сборка (включение всех модулей)
облегчённая сборка (только криптографическое ядро)
сборка с оптимизацией (через Closure Compiler)

Каждый режим управляется параметрами скриптов в каталоге build, что позволяет автоматизировать процесс через make или аналогичные утилиты.

Работа makefile

Файл автоматизации сборки описывает последовательность целей, среди которых:

очистка временных файлов
генерация ядра библиотеки
запуск тестов
сборка итогового файла
запуск минификации

Makefile обеспечивает детерминированность процесса: один и тот же набор исходников всегда приводит к идентичному результату при одинаковых условиях окружения.

Генерация пространства имён

Одной из ключевых особенностей сборки является формирование глобального объекта sjcl. Все модули подключаются внутрь этого пространства имён, что предотвращает загрязнение глобальной области видимости JavaScript.

Механизм упаковки автоматически:

создаёт объект-обёртку
размещает внутри него функции и классы
экспортирует публичные методы через свойства объекта

Это позволяет использовать библиотеку без конфликтов с другими скриптами в браузере.

Тестирование после сборки

После формирования сборки обычно выполняется прогон тестового набора. Тесты проверяют:

корректность шифрования и расшифрования
совпадение хэш-значений с эталонами
стабильность генерации случайных чисел
корректность работы кодировок

Тестирование может запускаться как на исходных модулях, так и на собранной версии, что позволяет выявлять ошибки на этапе упаковки.

Типичные проблемы сборки

При сборке из исходников часто возникают характерные проблемы:

отсутствие Python или использование несовместимой версии интерпретатора
ошибки порядка зависимостей модулей
некорректная конфигурация включаемых компонентов
проблемы совместимости Closure Compiler с современным JavaScript-синтаксисом
различия в поведении файловой системы между Windows и Unix-средами

Каждая из этих проблем обычно проявляется либо на этапе упаковки, либо при запуске тестов.

Инкрементальная сборка

Для ускорения разработки применяется инкрементальный режим, при котором пересобираются только изменённые модули. Это достигается за счёт:

сравнения временных меток файлов
кеширования промежуточных результатов
повторного использования уже сгенерированных частей библиотеки

Такой подход снижает время итерации при изменении отдельных криптографических компонентов.

Структура итогового файла

Собранный файл представляет собой единый JavaScript-документ, внутри которого:

объявляется пространство имён sjcl
последовательно подключаются модули ядра
регистрируются алгоритмы и утилиты
экспортируются публичные API-функции

Файл не содержит внешних зависимостей и может быть загружен как обычный скрипт в браузере или подключён через require в Node.js при соответствующей обёртке.