В руководстве R для R CMD check описаны три уровня итоговых замечаний: ERROR, WARNING и NOTE (официальное описание проверки пакетов). Поэтому проверяйте пакет в нативной среде macOS, если он должен поддерживать Mac или использует связанные с этой платформой компоненты: сначала зафиксируйте версию R и инструменты, затем проверьте архив исходников, компиляцию, тесты и документацию. Успешный результат на Mac не подтверждает совместимость с Windows или Linux и не гарантирует принятие пакета в CRAN.
Материал предназначен для исследователей и аспирантов, сопровождающих пакет R и готовящих его к выпуску или передаче коллегам.
Он также пригодится разработчикам с C-, C++- или Fortran-кодом, которым нужно проверить сборку на macOS arm64.
Техническим сотрудникам лабораторий он поможет организовать такую приёмку, даже если у разработчика нет локального Mac.
Сначала — границы проверки и критерии результата
R CMD check — это проверка пакета по ряду требований к исходникам, установке, тестам, примерам и документации, а не универсальное доказательство корректности всех вычислений. Состав проверок и доступные параметры зависят от выпуска R, поэтому перед публикацией сверяйте команды с действующей версией руководства Writing R Extensions.
Результат следует читать не только по последней строке. ERROR означает, что проверка обнаружила серьёзную проблему; WARNING и NOTE требуют анализа в контексте конкретного сообщения. Само наличие NOTE не следует автоматически приравнивать к успешной приёмке, как и нельзя считать любое замечание одинаково критичным. Сохраните полный журнал, найдите, на каком этапе возникло сообщение, и проверьте его причину.
На практике важно различать три решения:
- Локальная проверка исходников показывает, что обнаруживает установленная версия R в конкретном macOS-окружении.
- Проверка других платформ нужна, если в заявленной поддержке есть Windows или Linux.
- Рассмотрение в CRAN подчиняется отдельным требованиям и текущей политике репозитория; локальный результат не является обещанием публикации. Перед отправкой сверьтесь с действующей политикой CRAN.
Иными словами, Mac-проверка отвечает на вопрос «что происходит в этой среде?», а не «готов ли пакет для каждой системы и любого способа распространения?».
Подготовка среды: версия R, архитектура и инструменты
Перед первым запуском зафиксируйте состояние проекта и окружения. Это позволит отличить новую регрессию от уже существовавшей проблемы и повторить приёмку после исправлений. Запишите идентификатор коммита, вывод sessionInfo(), версию macOS, архитектуру и расположение выбранных инструментов разработчика.
Для базовой фиксации подойдут команды:
git status --short
git rev-parse HEAD
sw_vers -productVersion
uname -m
xcode-select -p
R --version
R -q -e 'cat(R.version$platform, "\n"); print(sessionInfo())'
Команды Git применимы, если проект ведётся в репозитории Git. Если это не так, укажите в журнале другой способ идентификации исходников: например, имя и контрольную сумму передаваемого архива. Вывод uname -m относится к текущему процессу, поэтому при запуске R через совместимый слой архитектуру самого R лучше дополнительно сверить с R.version$platform.
Что подготовить до запуска проверки? Нужны исходники конкретного коммита, работающая установка R, список зависимостей и понимание того, какие части проекта должны собираться на Mac. Для пакета с нативным кодом отдельно запишите компилятор и доступные настройки R:
R CMD config CC
R CMD config CXX
R CMD config FC
Некоторые настройки или компиляторы могут отсутствовать — это само по себе ещё не доказывает ошибку пакета. Сопоставьте вывод с тем, какие языки действительно используются в исходниках, а также с требованиями внешних библиотек.
Для сборки могут потребоваться Xcode Command Line Tools. Установка и выбор этих инструментов — отдельные действия: Apple описывает их в документации по установке Command Line Tools и настройке выбранного каталога разработчика. Проверьте путь из xcode-select -p, а при необходимости установите или выберите подходящий каталог согласно актуальной инструкции Apple. Наличие полного Xcode нельзя объявлять универсальным требованием для каждого пакета; потребность зависит от кода и его зависимостей.
Достаточно ли установить Command Line Tools? Это определяется конкретной сборкой. Если пакет компилирует собственный код, ему нужны совместимые компилятор, заголовочные файлы и библиотеки. Если ошибка указывает на отсутствующий SDK или системный компонент, сначала проверьте выбранный каталог инструментов и зависимость, названную в сообщении, а не устанавливайте наугад дополнительное программное обеспечение. Подробности установки R для macOS также приведены в руководстве R Installation and Administration.
Сборка архива и полный журнал проверки
Проверяйте не только рабочую папку, но и собранный исходный архив: иначе можно не заметить, что нужный файл не попал в распространяемую версию. Официальная документация R отдельно описывает сборку и проверку пакета. Для проекта, где каталог пакета называется mypackage, последовательность выглядит так:
R CMD build mypackage
R CMD check mypackage_0.1.0.tar.gz
Имя архива во второй команде нужно заменить на фактически созданное сборкой. Версия в примере — часть имени, а не рекомендация присваивать проекту конкретный номер. Сначала выполните обычную проверку архива; дополнительные режимы используйте только если понимаете, какие проверки они включают и для какой цели нужны.
В таблице различены объекты и выводы, которые часто ошибочно считают взаимозаменяемыми:
| Вариант проверки | Что проверяется | Какой вывод допустим |
|---|---|---|
| Проверка каталога проекта | Состояние рабочего дерева, переданного команде | Полезно для быстрой диагностики; не подтверждает, что собранный архив содержит все нужные файлы |
| Проверка архива исходников | Пакет, подготовленный для распространения, и предусмотренные процедурой этапы проверки | Показывает результат для этого архива, версии R и текущей платформы |
| Проверка на Windows или Linux | Пакет в соответствующей операционной системе и её окружении | Добавляет свидетельство для проверенной платформы; результат Mac её не заменяет |
| Проверка перед отправкой в CRAN | Пакет с учётом актуальных требований CRAN и проверок, применимых при рассмотрении | Помогает подготовиться, но локальный запуск не гарантирует принятие |
После запуска сохраните весь вывод терминала, архив, идентификатор коммита и информацию о среде в одном месте. Зафиксируйте также каталог с результатами проверки, если он создан, и не ограничивайтесь скриншотом итоговой строки. В сообщении об ошибке важны контекст, команда и этап, а не только краткий статус.
Для каждой проблемы запишите: текст первого содержательного сообщения, этап проверки, затронутый файл или зависимость, результат после исправления. Если тест падает только после сборки архива, проверяйте именно этот путь воспроизведения, а не только локальный запуск функции из рабочей папки.
Компиляция и нативные зависимости на macOS arm64
Пакет без нативного кода и пакет с C, C++ или Fortran проходят разные практические риски. Во втором случае ошибка сборки может быть вызвана исходниками пакета, несовпадением архитектуры, отсутствующими заголовками, библиотекой, не установленной в окружении, или выбранным набором инструментов. Исправление зависит от причины; установка одной и той же дополнительной среды для всех ошибок — ненадёжная стратегия.
При сообщении компилятора двигайтесь от конкретного сбоя:
- Найдите первую ошибку компиляции или связывания, а не последующие строки, которые лишь сообщают о прерванной сборке.
- Определите, относится ли имя файла к исходникам пакета или к внешней библиотеке.
- Сверьте архитектуру R и требуемой библиотеки. Бинарная зависимость другой архитектуры может не связываться с текущей сборкой.
- Проверьте, доступен ли указанный заголовок и где система ожидает его найти.
- Повторите сборку после устранения одной причины и сохраните новый полный журнал.
Такой разбор отделяет дефект кода от ошибки подготовки среды. Например, «файл заголовка не найден» и «символ не найден при связывании» — разные симптомы: в первом случае проверяют наличие и путь к заголовку, во втором — библиотеку, её архитектуру и настройки связывания. Не добавляйте пути к каталогам глобально, пока не установлено, какой компонент их должен предоставлять.
С чего начинать при ошибке компиляции R-пакета на Mac? С первого сообщения компилятора, имени проблемного файла и команды, которая завершилась неудачно. Затем сопоставьте требуемые библиотеки с настройками компилятора R и выбранным каталогом инструментов. Если ошибка остаётся, подготовьте минимальное воспроизведение на том же архиве и в том же окружении: попытка одновременно обновить инструменты, зависимости и код затрудняет поиск причины.
Условия проверки, связанные с переменными окружения и последовательностью R CMD check, описаны в разделе руководства R о процессе проверки. Используйте его для уточнения параметров, но не копируйте окружение другого проекта без проверки: список системных библиотек и компиляторов у пакетов различается.
Тесты, примеры и документация
После сборки разберите проверки тестов, примеров и документации по отдельности. Для научного пакета недостаточно, чтобы одна функция запускалась вручную: тесты должны работать в чистой среде, а инструкции — соответствовать файлам и зависимостям, которые действительно входят в проект.
При диагностике тестов проверьте, не читает ли код личные файлы из домашнего каталога, не использует ли заранее созданные данные и не зависит ли от объекта, оставленного в интерактивной сессии. Если тест получает данные из сети, проверьте, можно ли организовать корректное локальное воспроизведение и что произойдёт при недоступности источника. Удалять такой тест или превращать сетевую ошибку в успешный результат без объяснения не следует: сначала определите, должен ли пакет работать без сетевого доступа и какие результаты проект обещает пользователям.
Проверки примеров полезно сопоставлять с документацией функций: опубликованный пример должен выполняться с объявленными зависимостями и не требовать частных файлов лаборатории. Для vignette проверьте исходник, инструменты его сборки, ссылки на данные и результат рендеринга. Отдельно убедитесь, что необходимые файлы входят в исходный архив.
Как локализовать сбой документации или vignette? Сначала определите, на каком этапе возникла проблема: при проверке Rd-файла, выполнении примера, сборке vignette или поиске файла. Затем запустите соответствующий фрагмент в чистой сессии, проверьте объявленные зависимости и пути к данным. Документация по тестированию установленного пакета в R поясняет, какие типы тестов можно выполнять для установленного пакета; это помогает отличить проблему исходников от ситуации, когда проверяется уже установленная копия.
Научные вычисления могут давать небольшие различия между средами из-за численной арифметики, платформенных библиотек или генерации случайных значений. Не подменяйте диагностику произвольным увеличением допуска: сначала зафиксируйте ожидаемое поведение, используемые данные и причину допустимой погрешности. Если тест чувствителен к случайным числам, обеспечьте контролируемый сценарий и документируйте, что именно проверяется. Универсальное числовое значение допуска для всех пакетов здесь было бы необоснованным.
Приёмка, передача результата и недостающий Mac
Перед передачей проекта оформите краткий протокол: идентификатор исходников, сведения об R и macOS, архитектура, выбранные инструменты, имя проверенного архива, статусы и ссылки на журналы. Отдельно перечислите оставшиеся замечания и обозначьте их как исправленные, принятые с обоснованием или требующие дальнейшей проверки. Так коллеги смогут повторить процедуру и понять, что именно означает отметка «проверено на Mac».
Если в целевую поддержку входят Windows или Linux, запланируйте отдельную проверку на этих системах. Сверьте требования распространения с текущей политикой CRAN непосредственно перед отправкой: политика может изменяться, а локальный результат относится только к выполненному запуску. При необходимости повторите проверку после обновления R, системных инструментов или зависимостей, если это меняет условия сборки.
Означает ли успешная проверка на Mac совместимость с Windows и Linux? Нет. Она подтверждает результат только для проверенной версии R, macOS, архитектуры и набора зависимостей. Для заявленной поддержки других систем проведите отдельную проверку там и разберите платформенные различия, особенно для путей файлов, внешних библиотек и нативного кода.
Что делать, если у лаборатории нет Mac? Сначала определите, требуется ли именно нативная проверка macOS arm64, или проект можно проверить на доступных системах, оставив Mac-проверку отдельным этапом. Если она обязательна, можно организовать временный удалённый доступ к реальному Mac: описание удалённой среды NodeMini поможет оценить такой формат, а центр помощи NodeMini — разобраться с доступом и рабочим процессом. До запуска проверьте, можно ли безопасно передавать туда код и данные лаборатории; конфиденциальные материалы должны обрабатываться по правилам вашей организации.
Локальная Linux- или Windows-машина удобна для повседневной разработки, но не воспроизводит macOS-инструментарий, поведение системных библиотек и фактическую сборку на целевой архитектуре. При этом приобретать отдельный Mac разумно не для каждого проекта: покупка оправданнее, когда лаборатории нужна постоянная машина, физические подключения или длительная регулярная нагрузка; для разовой приёмки сначала сравните организационные ограничения и длительность задачи. Если лаборатории временно недоступна macOS, аренда среды NodeMini может закрыть именно этап проверки без замены основного HPC-контура. Начните с чистого исходного архива, зафиксируйте окружение и перед завершением сохраните воспроизводимый журнал R CMD check — тогда итог будет полезен не только автору пакета, но и следующему сопровождающему.