디버깅
명령어가 예상대로 동작하지 않을 때 문제를 진단할 수 있도록 Tuist는 여러 도구를 제공합니다.
세션 데이터에는 파일 경로, 프로젝트 이름, 요청/응답 본문과 같은 민감한 정보가 포함될 수 있습니다. 민감한 헤더(예: 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: HTTP 트래픽을 보고 분석하는 네이티브 macOS 앱입니다. 파일 > 가져오기를 통해 HAR 파일을 가져옵니다.
- 브라우저 개발자 도구: Chrome, Firefox, Safari 모두 네트워크 탭에서 HAR 파일 가져오기를 지원합니다.
- HAR Viewer: 웹 기반 HAR 파일 뷰어입니다.
Tuist의 디렉터리 구성과 사용자 정의 디렉터리 설정 방법은 Directories 문서에서 자세히 알아보세요.
xcodebuild를 실행하는 명령어는 출력을 xcbeautify로 포맷팅합니다. 포맷팅되지 않은 출력을 보려면 --verbose를 전달하세요. xcodebuild 출력 포맷팅을 참조하세요.
기본적으로 CLI는 실행이 예기치 않게 종료될 때 세션 경로를 출력합니다. 그렇지 않은 경우 위에서 언급한 경로(즉, 가장 최근의 세션 디렉터리)에서 세션 데이터를 찾을 수 있습니다.
5일 이상 된 세션 디렉터리는 자동으로 정리됩니다. Tuist는 기본적으로 최대 50개의 비활성 세션 디렉터리를 유지하면서 현재 실행 중인 Tuist 프로세스가 소유한 세션은 보존합니다. 동일한 상태 디렉터리를 사용하는 많은 Tuist 명령어를 실행하는 CI 환경에서는 TUIST_SESSION_MAX_SESSIONS로 비활성 세션上限을 높일 수 있습니다. 예를 들어 TUIST_SESSION_MAX_SESSIONS=200와 같이 설정합니다. 잘못된 값, 0, 음수 값은 무시되며 Tuist는 기본값인 50으로 되돌아갑니다.
지속적 통합#
환경이 일회용인 CI에서는 Tuist 세션 데이터를 내보내도록 CI 파이프라인을 구성하는 것이 좋습니다. 아티팩트 내보내기는 CI 서비스 전반에서 일반적으로 지원하는 기능이며, 구성은 사용하는 서비스에 따라 다릅니다. 예를 들어 GitHub Actions에서는 actions/upload-artifact 액션을 사용하여 세션 데이터를 아티팩트로 업로드할 수 있습니다:
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 setup cache를 실행할 때와 빌드할 때 모두 TUIST_CAS_LOG를 파일 경로로 설정하세요. Tuist는 해당 파일에 캐시 통계와 오류를 추가합니다:
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의 모든 Hypertext Transfer Protocol (HTTP) 트래픽은 합리적인 기본값을 가진 공유 URLSession를 통해 이동합니다. 느리거나 혼잡한 네트워크 경로(예: 기업 프록시를 통해 객체 스토리지에 접근하는 자체 호스팅 설정)에서는 개별 요청이 자원 타임아웃에 도달하여 완료되기 전에 중단될 수 있습니다. 특히 캐시 다운로드의 경우 타임아웃에 도달하면 Tuist는 모듈을 소스에서 빌드하는 방식으로 대체하는데, 이는 캐시된 바이너리를 조금 더 기다리는 것보다 훨씬 비용이 큽니다. 환경 변수를 통해 기본 설정을 조정할 수 있으며, 설정되지 않았거나 잘못된 값으로 설정된 경우 기본값이 적용됩니다:
# 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
자원 타임아웃은 전체 전송에 대한 실제 시간 상한선이며, 정지 감지기가 아니므로 이동하는 가장 큰 아티팩트에 충분히 커야 합니다. 따라서 샤드가 다운로드하는 테스트 제품과 같은 전체 파일 전송은 90초 대신 기본적으로 10분으로 설정되며, 새로운 데이터 없이 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에 대해 신뢰됨으로 표시) 하는 것이 표준 접근 방식이지만, GUI 세션이나 모바일 장치 관리(MDM)가 없어 신뢰 비트를 설정할 수 없는 헤드리스 CI 호스트에서는 종종 실용적이지 않습니다.
이러한 경우 Tuist가 직접 CA 인증서 번들을 지정하도록 할 수 있습니다. 번들은 PEM(연결된 하나 이상의 -----BEGIN CERTIFICATE----- 블록)이거나 단일 DER 파일일 수 있습니다. 시스템 루트 저장소는 이와 함께 계속 신뢰되므로 공개 인증서는 정상적으로 검증되며 인증서 평가는 절대 우회되지 않습니다.
# 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
구성 파일에도 선언할 수 있습니다:
[network]
ca_certificate = "/etc/ssl/certs/self-hosted-ca.pem"
TUIST_CA_CERTIFICATE 환경 변수는 구성 파일보다 우선 적용되므로, 커밋된 매니페스트를 변경하지 않고도 CI 비밀로 제공하기 편리합니다.