Установка библиотеки из ZIP-архива: когда нет интернета

Дом творчества в сорока минутах от города, кружок по субботам, интернет падает каждые вторые выходные. В ту субботу у меня на столе лежала флешка с архивом LiquidCrystal_I2C.zip, скачанным дома заранее, и восемь пар глаз ждали текст на дисплеях. Я открыл менеджер библиотек — и получил честный, беспощадный ответ: список пуст, поиск не работает, сеть недоступна. Менеджер — это витрина, а витрина без связи не продаёт. Пятнадцать минут тишины я потратил на то, чтобы разложить всё по полочкам руками, и с тех пор ZIP-путь у меня отрепетирован как запасной выход.

Разберём оба маршрута: диалогом среды — он быстрее, и руками — он надёжнее, потому что вы видите, куда что легло. Разберём три грабли распаковки, на которых я потерял тот вечер и два следующих, и приём проверки, который ставит точку в вопросе «установилась или нет». О том, чем менеджер отличается от ZIP и зачем вообще нужны версии, мы уже говорили в уроке про менеджер библиотек, а полная карта трёх способов установки с конфликтами версий — в уроке про библиотеки. Здесь — только офлайн-маршрут и его подводные камни.

Маршрут первый — силами среды. Меню «Скетч → Подключить библиотеку → Добавить .ZIP библиотеку…» (в классической 1.8.x та же команда называется Sketch → Include Library → Add .ZIP Library). Открывается обычный выбор файла: показываете архив на флешке, жмёте OK — и среда сама распаковывает содержимое в папку Документы\Arduino\libraries, создавая подпапку с именем библиотеки. Ничего вручную распаковывать не нужно, перезапускать среду тоже: диалог сканирует список на ходу. На моей машине вся операция занимает меньше десяти секунд, и из них восемь — выбор файла мышкой.

Маршрут второй — руками, и у него есть смысл даже при живом интернете: он не оставляет тайн. Закрывать среду не обязательно, но полезно помнить: список библиотек сканируется при старте, поэтому после ручной установки библиотека появится в меню только после перезапуска IDE. Порядок такой: распаковываете архив обычным проводником, находите папку, внутри которой лежат library.properties и файлы с расширениями .h и .cpp, — и кладёте именно её в Документы\Arduino\libraries. Не архив, не содержимое, а саму папку. Эта же папка — дом всех библиотек, устроенный так, как мы разбирали в уроке про структуру sketchbook.

Проверка установки, которой я заканчиваю каждый кружковый вечер: меню «Файл → Примеры» — и прокрутить список в самый низ. У каждой установленной сторонней библиотеки там появляется своя секция с примерами; увидели имя библиотеки между «примерами из своей папки» и штатными — значит, всё встало. Второй контроль — собрать любой из этих примеров кнопкой «Проверить»: если компиляция прошла, среда нашла и заголовок, и код. Проверить сам скетч, который вы собираетесь вести на занятие, лучше ещё дома при интернете — так у меня появилось железное правило готовить флешку за день, а не за пятнадцать минут до кружка.

Грабля первая — двойная вложенность, чемпион всех офлайн-вечеров. Скачиваете библиотеку с GitHub кнопкой Code → Download ZIP — архив называется что-то вроде LiquidCrystal_I2C-main.zip, а внутри лежит папка LiquidCrystal_I2C-main, внутри которой уже library.properties и код. Смешно, но часто внутри оказывается ещё один уровень: папка с примерами или повторным названием. Правило одной строки: в Документы\Arduino\libraries кладём ту папку, внутри которой лежит library.properties — не выше, не ниже. Я как-то закинул всю распакованную кучу целиком, среда молча не увидела библиотеку, и я десять минут искал виноватого в настройках, хотя виноват был уровень вложенности.

Грабля вторая — суффиксы -main и -master в имени папки. Само по себе такое имя не ломает компиляцию: среде всё равно, как папка называется, ей важно, что внутри есть library.properties. Опасность другая: поставив сегодня папку IRremote-main, а через месяц ту же библиотеку из менеджера, вы получите две копии с одинаковым заголовком — и первую же сборку с #include украсит знакомое по уроку про библиотеки предупреждение «Multiple libraries were found». Лечение простое: после установки из ZIP переименуйте папку без суффикса или удалите её, когда появится версия из менеджера. Моё правило: в sketchbook/libraries каждой библиотеки живёт ровно одна копия — иначе проверяйте, какая из двух реально используется.

Грабля третья — «не тот архив» и путь. На страницах с инструкциями кнопка скачивания иногда ведёт на архив исходников сайта или на PDF с картинками — внешне всё то же .zip, а внутри ни одного .h файла. Перед установкой гляньте внутрь: в корне библиотечной папки обязаны лежать library.properties, заголовочный файл и папка src или .cpp-файл. С путём обратная история: кириллица и пробелы в имени папки библиотеки в подавляющем числе случаев работают, но если среда упорно не видит библиотеку, а вложенность вы проверили, — переименуйте папку латиницей без пробелов, это дешевле часа допроса с пристраиванием. И последнее отличие ZIP-пути от менеджера: архив не хранит список версий, только дату скачивания. Запишите её в заметку к проекту — через полгода это единственная зацепка в вопросе «под какой версией всё собиралось».

Пара слов об офлайн-гигиене, потому что флешка — это тоже система. Архивы библиотек я храню в папке arhivy рядом со sketchbook, в имени файла — библиотека и дата: LiquidCrystal_I2C_2025-03-14.zip. Скачиваю всегда из официального репозитория автора или страницы библиотеки на arduino.cc: у архивов с файловых обменников бывают сюрпризы от добавленной рекламы до переписанных файлов. И берите архив целиком, а не отдельный .h файл из чьего-то сообщения на форуме — половина кода библиотеки обычно живёт во втором и третьем файлах, которых в сообщении не видно, и недокачанная библиотека проявится ошибкой «not declared» при сборке, о которой у нас отдельный урок про чтение лога компиляции.

Честное мнение с границей: ZIP — путь для офлайна, форков и самописных библиотек, и только. По умолчанию я ставлю через менеджер: он подтягивает версии, следит за зависимостями и даёт откат одной кнопкой, чего папка на флешке не умеет. Но понимать ZIP-маршрут нужно хотя бы ради того, чтобы перестать видеть в библиотеке магию: это чужой код в папке, который компилятор просто складывает рядом с вашим. Именно это показывает симулятор ниже — «библиотека» из двух функций, живущая прямо в скетче. Так же собирается и настоящая библиотека: интерфейс в файле .h, реализация в .cpp, а свои функции, свёрнутые в такой же двухслойный пирог, мы уже писали в уроке про свои функции, а применяли к настоящему дисплею — в уроке про LCD I2C.