Отладка

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 на bundle CA-сертификатов. Bundle может быть в формате 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 без изменения закоммиченного манифеста.