Библиотека для нового модуля лежит на GitHub, в Library Manager по её имени тишина, а интернет в мастерской кончился ровно в тот вечер, когда она понадобилась. Первый раз я решал эту головоломку часами: качал архив, распаковывал куда попало и недоумевал, почему скетч не видит header. Теперь установка из архива занимает минуту на любой из двух путей — покажу оба и обе главные ловушки, которые портят вечер чаще самого отсутствия интернета.
База уже была: Library Manager в один клик закрывает девять установок из десяти, а офлайн-установка из zip разбирала сам сценарий без сети. Здесь — анатомия: что среда делает с архивом, куда распаковывает, какая структура папки нужна, и почему имя папки и имя в #include то совпадают, то ссорятся. Про версии, дубли и конфликты двух копий одной библиотеки есть отдельный урок про версии и дубли — там не повторяюсь.
Третий случай молчания менеджера самый тихий: поиск пуст, потому что библиотека записана не под именем модуля. Ищете «TroykaOLED», а в индексе она живёт под фирменным именем производителя с тире посередине. Мой способ за минуту: открыть страницу модуля у продавца — там почти всегда ссылка на архив или репозиторий с точным именем, оттуда и качать. Подбирать похожие названия в поиске менеджера — путь к чужой библиотеке с похожим API и совсем другим поведением.
Add .ZIP Library: что происходит на самом деле
Официальный путь: Sketch → Include Library → Add .ZIP Library…, дальше стандартное окно выбора файла. Среда распаковывает архив в папку libraries внутри скетчбука — на Windows это Documents/Arduino/libraries, в Linux — Arduino/libraries в домашней папке; точное место видно в настройках, устройство скетчбука разобрали в уроке про структуру папок. Перезапуск не нужен: следующий Ctrl+R уже найдёт новую библиотеку, и пункт Include Library покажет её имя в списке — вставить #include можно одним кликом, без набора руками. Точку назначения можно перенести: в настройках среды задаётся путь скетчбука, и архив ляжет в libraries именно этого пути — удобно держать библиотеки на другом диске.
Ручная распаковка даёт тот же результат без меню: распаковал в libraries — и всё, я пользуюсь ею, когда библиотек несколько и надо расставить их по именам, а меню — когда одна и лень думать. Единственное требование для обоих путей: на верхнем уровне папки должен лежать файл library.properties — паспорт библиотеки с именем, версией и списком архитектур. Нет паспорта — среда считает папку легаси и ищет header с именем папки прямо в корне; от этого правила растут обе главные ловушки ниже.
Вместе с библиотекой приезжают примеры: File → Examples, секция кастомных библиотек внизу списка — там лежат папки examples из архива. Это и лучший тест установки: открыли пример, скомпилировали — библиотека живая, и заодно виден канонический способ её использования. Версию тоже видно без вскрытия файлов: она записана в паспорте, и среда показывает её в списке установленных.
Структура папки и имя в #include
Свежий формат называется 1.5 и выглядит так: папка LibraryName, внутри library.properties, src/LibraryName.h и папка examples с демонстрационными скетчами. Компилятору раскрывается только src: #include <LibraryName.h> находит src/LibraryName.h, даже если папка на диске называется иначе — паспорт важнее имени папки. Легаси-формат проще: header лежит в корне, и тут имя папки и имя в #include совпадать обязаны — переименуете папку без паспорта, и компилятор выдаст no such file or directory на ровном месте. Обе схемы живут годами, миллион библиотек так и остались легаси. Внутри src живут и вспомогательные header-ы: пользователю нужно помнить только одно имя — остальные подтягиваются из основного файла сами.
Мой чек-лист при сомнениях из трёх шагов: открыть папку и найти library.properties; если паспорт есть — смотреть, что лежит в src; если нет — сверять имя папки с именем header. Свою библиотеку с нуля по этим же правилам собирали в уроке про шаги создания библиотеки, а карту всех путей установки рисовали в уроке про библиотеки в IDE. Двух минут с папкой обычно хватает, чтобы спор «кто виноват» закончился до первой перепрошивки.
Пара живых примеров на закрепление. FastLED — формат 1.5: паспорт в корне, все header-ы в src, и дополнительных модулей там десяток — компилятор подтягивает только упомянутый в include. Дисплейные библиотеки старых производителей — чаще легаси: один header в корне, имя папки совпадает с именем в include до буквы. Встречаются и сборки с папками под архитектуры внутри src — среда сама выберет свою, лезть туда не нужно.
// Na plate: DS18B20 na pin 10, rezistor 4.7 kOm mejdu data i 5V.// OneWire chasto ustanavlivayut iz .zip - Library Manager inogda molchit.#include <OneWire.h> OneWire ds(10); void setup() { Serial.begin(9600);} void loop() { byte addr[8]; if (!ds.search(addr)) { Serial.println("konec spiska ustrojstv"); ds.reset_search(); delay(2000); return; } if (OneWire::crc8(addr, 7) != addr[7]) { Serial.println("adres s isporchennym CRC - provod dlinnovat"); return; } Serial.print("ustrojstvo: "); for (int i = 0; i < 8; i++) { if (addr[i] < 16) { Serial.print("0"); } Serial.print(addr[i], HEX); Serial.print(" "); } Serial.println(); delay(200);}| Путь | Что делаете | Когда выбирать |
|---|---|---|
| Library Manager | поиск по имени, кнопка Install | библиотека есть в индексе — выбор по умолчанию |
| Add .ZIP Library | Sketch → Include Library → Add .ZIP Library… | архив с GitHub или от производителя, индекс молчит |
| Ручная распаковка | папку — в libraries внутри скетчбука | несколько библиотек разом или чистка старых копий |
| Проверка паспорта | library.properties на верхнем уровне папки | всегда: нет паспорта — среда ищет header по имени папки |
| Examples после установки | File → Examples, секция кастомных библиотек | проверка установки живым скетчем |
Теперь мнение, с которым можно спорить: Library Manager держит релизы, а GitHub — жизнь. Между «исправление влито в репозиторий» и «версия вышла в менеджере» проходит от пары недель до полугода, и если ваш модуль лечится именно этим коммитом, единственный рабочий путь — кнопка Code → Download ZIP. Я так вытащил дисплейный драйвер за неделю до релиза: версия из менеджера падала на моей партии модулей, в репозитории уже стоял фикс. С момента установки архива я записываю имя ветки в комментарий скетча — через полгода без этой записи не понять, что за зверь в папке.
Обратная сторона того же мнения: если скетч собирается и модуль работает — гнаться за последней версией незачем. Мастер-ветка — это чьё-то «у меня работает» без релизной обкатки, и она способна унести совместимость: половина моих утренних «почему не компилируется» — чужой скетч образца прошлого года против свежего мастера. Правило короткое: релиз из менеджера по умолчанию, GitHub — по конкретной причине, которую вы можете назвать одной фразой. И перед установкой из ветки гляньте на дату последнего коммита: «свежее» иногда означает «сломано вчера», и полгода тишины в репозитории надёжнее недельной давности правок.
Обновление установленной из архива версии — отдельный ритуал. Сначала удалить старую папку целиком, потом положить новую: копирование поверх оставляет мусор от удалённых файлов прошлой версии, и половина странных сборок после «обновления» выросла именно из этого. Имя папки при обновлении сверяйте с паспортом — репозиторий переименовали, и в libraries теперь две разные библиотеки с одним include, компилятор берёт первую попавшуюся.
Самый показательный эффект ручных установок — предупреждение Multiple libraries were found в логе компиляции: две папки претендуют на один include, среда берёт первую по своему списку приоритетов и честно пишет, кого нашла ещё. Сборка при этом может пройти успешно — и через месяц внезапно сломаться после того, как вы положили рядом ещё одну копию. Увидели предупреждение — откройте лог, найдите обе папки, оставьте одну: дуэли копий решаются чисткой, а не надеждой на удачу.
Порядок в libraries — привычка, которая оплачивается годами: одна библиотека — одна папка, копий «на всякий случай» не держать, старые версии сносить сразу после успешного обновления. За два года папка разрастается до пары сотен имён, и в этой толпе двойники находят только по логу предупреждений. Пять минут чистки раз в месяц — и ни одна установка не превращает сборку в лотерею.
- 1. Куда Add .ZIP Library кладёт распакованную библиотеку?
- 2. В папке нет library.properties, header лежит в корне. Что должно совпасть?
- 3. Внутри zip папка в папке, паспорт во второй. Что сделает установщик?
- 4. Когда я беру версию с GitHub, а не из менеджера?
- 5. Нужен ли перезапуск среды после Add .ZIP Library?
- Sketch → Include Library → Add .ZIP Library распаковывает архив в libraries скетчбука; ручная распаковка туда же даёт тот же результат.
- Паспорт library.properties на верхнем уровне — главный признак живой библиотеки; в формате 1.5 header ищется в src.
- Без паспорта папка легаси: имя папки обязано совпадать с именем в #include.
- Папка в папке внутри архива ломает установку — переносите содержимое внутренней папки на уровень выше.
- Релиз из менеджера по умолчанию; GitHub — когда в репозитории есть фикс, которого в релизе ещё нет.
Частые вопросы по теме урока
- Куда Add .ZIP Library кладёт распакованную библиотеку?
- Архив распаковывается в libraries внутри скетчбука — на Windows это Documents/Arduino/libraries. Точное место видно в настройках среды. в libraries внутри скетчбука (Documents/Arduino)
- В папке нет library.properties, header лежит в корне. Что должно совпасть?
- Без паспорта папка считается легаси: компилятор ищет header по имени папки. Переименовали — получите no such file or directory на ровном месте. имя папки и имя header в #include
- Внутри zip папка в папке, паспорт во второй. Что сделает установщик?
- Двойную вложенность не переваривает никто: паспорт ищут на верхнем уровне. Лечение — перенести содержимое внутренней папки на уровень выше и положить в libraries. не найдёт паспорт на верхнем уровне и откажется
- Когда я беру версию с GitHub, а не из менеджера?
- Мастер-ветка — чьё-то «у меня работает» без обкатки. По умолчанию релиз из менеджера; GitHub — по конкретной причине, названной одной фразой. когда в репозитории есть нужный фикс, которого нет в релизе
- Нужен ли перезапуск среды после Add .ZIP Library?
- Перезапуск не требуется: библиотека живёт в libraries скетчбука, и следующая компиляция её подхватит, а Include Library покажет имя в списке. не нужен: следующий Ctrl+R увидит библиотеку