Отладка

Tuist предоставляет несколько инструментов для диагностики проблем, когда команды работают не так, как ожидалось.

Warning

Данные сессии могут содержать конфиденциальную информацию, такую как пути к файлам, названия проектов и тела запросов/ответов. Хотя чувствительные заголовки (например, Authorization) скрываются, будьте осторожны при передаче данных сессии другим лицам.

Данные сессии#

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

При каждом запуске создается каталог сессии по пути $XDG_STATE_HOME/tuist/sessions/{uuid}/, где $XDG_STATE_HOME принимает значение ~/.local/state, если переменная окружения не установлена. Вы также можете использовать $TUIST_XDG_STATE_HOME для установки каталога состояния, специфичного для Tuist, который имеет приоритет над $XDG_STATE_HOME.

Каждый каталог сессии содержит:

logs.txt — текстовые логи сессии CLI
network.har — файл HTTP Archive (HAR), содержащий все сетевые запросы и ответы, сделанные во время сессии

Просмотр HAR-файлов#

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

Proxyman: нативное приложение для macOS для просмотра и анализа HTTP-трафика. Импортируйте HAR-файл через File > Import.
Инструменты разработчика в браузере: Chrome, Firefox и Safari поддерживают импорт HAR-файлов на вкладке Network.
HAR Viewer: веб-инструмент для просмотра HAR-файлов.

Tip

Узнайте больше об организации каталогов Tuist и о том, как настроить пользовательские каталоги, в документации по каталогам.

По умолчанию CLI выводит путь к сессии, если выполнение завершается неожиданно. Если этого не происходит, вы можете найти данные сессии по указанному выше пути (то есть в самом последнем каталоге сессии).

Каталоги сессий старше 5 дней автоматически удаляются. По умолчанию Tuist хранит не более 50 неактивных каталогов сессий, сохраняя при этом сессии, принадлежащие текущим запущенным процессам Tuist. В средах CI, где выполняется много команд Tuist с одним и тем же каталогом состояния, вы можете увеличить лимит неактивных сессий с помощью TUIST_SESSION_MAX_SESSIONS, например TUIST_SESSION_MAX_SESSIONS=200. Недопустимые значения, ноль и отрицательные значения игнорируются, и Tuist возвращается к значению по умолчанию 50.

Непрерывная интеграция#

В среде CI, где окружения являются временными, вы можете настроить свой конвейер CI для экспорта данных сессии Tuist. Экспорт артефактов — это распространенная возможность среди сервисов CI, и конфигурация зависит от используемого сервиса. Например, в GitHub Actions вы можете использовать действие actions/upload-artifact для загрузки данных сессии в качестве артефакта:

yaml

name: Node CI

on: [push]

env:
  TUIST_XDG_STATE_HOME: /tmp

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      # ... other steps
      - run: tuist generate
      # ... do something with the project
      - name: Export Tuist session data
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: tuist-sessions
          path: /tmp/tuist/sessions/

Отладка кэша Xcode#

Для отладки проблем с кэшем Xcode установите TUIST_CAS_LOG в путь к файлу как при выполнении tuist setup cache, так и при сборке. Tuist добавляет статистику кэша и ошибки в этот файл:

bash

export TUIST_CAS_LOG=$HOME/.local/state/tuist/cas.log
tuist setup cache
xcodebuild build -scheme YourScheme

В среде CI Tuist записывает этот лог в ~/.local/state/tuist/cas.log без какой-либо дополнительной настройки.

Настройка таймаутов сети и повторных попыток#

Весь трафик Tuist по протоколу передачи гипертекста (HTTP), включая вызовы сервера, работу с реестром, превью и передачу артефактов кэша, проходит через общий URLSession с разумными настройками по умолчанию. На медленных или перегруженных сетевых путях (например, при самостоятельном размещении с доступом к объектному хранилищу через корпоративный прокси) отдельный запрос может исчерпать время ожидания ресурса до завершения. Особенно при загрузке из кэша истечение таймаута заставляет Tuist переключаться на сборку модуля из исходного кода, что намного дороже, чем немного подождать готовый бинарный файл из кэша. Вы можете настроить базовые параметры через переменные окружения; значения по умолчанию применяются, если они не установлены или имеют недопустимое значение:

bash

# Maximum time (in seconds) a single resource transfer can take before it's cancelled
# (default: 90, or 600 for whole-file transfers such as test-product shard artifacts)
export TUIST_HTTP_TIMEOUT_INTERVAL_FOR_RESOURCE=600

# Maximum time (in seconds) to wait for new data on an existing request (default: 120)
export TUIST_HTTP_TIMEOUT_INTERVAL_FOR_REQUEST=300

# Maximum number of simultaneous connections per host (default: 20)
export TUIST_HTTP_MAXIMUM_CONNECTIONS_PER_HOST=40

# Maximum retries after the initial attempt (default: 3, maximum: 10)
export TUIST_HTTP_MAXIMUM_RETRY_COUNT=1

# Initial exponential backoff delay in milliseconds (default: 100, maximum: 30000)
export TUIST_HTTP_RETRY_BASE_DELAY_IN_MILLISECONDS=250

Таймаут ресурса — это ограничение по реальному времени на всю передачу, а не защита от зависания, поэтому он должен быть достаточно большим для самого крупного перемещаемого артефакта. Передачи целых файлов, такие как тестовые продукты, загружаемые шардом, поэтому по умолчанию имеют таймаут 10 минут вместо 90 секунд, а зависшая передача все равно завершается ошибкой после TUIST_HTTP_TIMEOUT_INTERVAL_FOR_REQUEST при отсутствии новых данных. Эти передачи читают TUIST_HTTP_TIMEOUT_INTERVAL_FOR_RESOURCE только для увеличения своего лимита, никогда не снижая его ниже 10 минут, поэтому значение, выбранное для быстрого отказа запросов к кэшу, не отменяет загрузку тестовых продуктов шардом. Увеличение TUIST_HTTP_TIMEOUT_INTERVAL_FOR_RESOURCE позволяет завершить восстанавливаемую, но медленную загрузку вместо таймаута. Для загрузок из кэша это означает получение попадания в кэш вместо возврата к сборке из исходного кода, поэтому увеличивайте его осознанно: то же значение, которое поддерживает медленную загрузку из кэша, также задерживает возврат к сборке из исходного кода. Снижение TUIST_HTTP_MAXIMUM_RETRY_COUNT может предотвратить умножение худшего времени ожидания на несколько попыток при более длительном таймауте. Задержки повторных попыток удваиваются после каждой неудачи, включают до одной базовой задержки случайного джиттера и никогда не превышают 30 секунд.

Доверие пользовательскому CA-сертификату#

По умолчанию Tuist проверяет TLS-сертификаты против корневого хранилища операционной системы. Когда вы запускаете самостоятельно размещенный сервер Tuist или Kura, использующий частный центр сертификации, Tuist также должен доверять этому CA. Установка корневого сертификата в системную связку ключей (и отметка его как доверенного для SSL) является стандартным подходом, но это часто непрактично на headless-хостах CI, где нет графического сеанса или управления мобильными устройствами (MDM) для установки флага доверия.

В таких случаях вы можете напрямую указать Tuist на пакет CA-сертификатов. Пакет может быть в формате PEM (один или несколько объединенных блоков -----BEGIN CERTIFICATE-----) или одиночным DER-файлом. Системное корневое хранилище остается доверенным вместе с ним, поэтому публичные сертификаты продолжают проверяться нормально, а оценка сертификатов никогда не обходится.

bash

# Path to a PEM/DER CA bundle to trust on top of the system root store (default: unset)
export TUIST_CA_CERTIFICATE=/etc/ssl/certs/self-hosted-ca.pem

Вы также можете указать его в вашем файле конфигурации:

toml

[network]
ca_certificate = "/etc/ssl/certs/self-hosted-ca.pem"

Переменная окружения TUIST_CA_CERTIFICATE имеет приоритет над файлом конфигурации, что удобно для предоставления в качестве секрета CI без изменения закоммиченного манифеста.