Guidedog 설명서 0.2.0
언어
이 페이지의 내용
Guidedog / 문서 0.2.0

오류 메시지

진단은 문제의 이름과 위치를 밝히고 유용한 다음 행동을 알려야 합니다. Guidedog는 이 정보를 구조화된 데이터로 보관합니다. 터미널에는 색상과 소스 표시를 더하고, JSON은 터미널 장식 없이 데이터를 유지합니다.

진단 읽기

UNDEFINED SUBSTITUTION                              rst.substitution.undefined

  guide/page.rst:4: See |logo| here.
                        ^^^^^^

The substitution "|logo|" is not defined.
No output was written.

Add a definition, e.g. ".. |name| replace:: text".

진단은 항상 다음 순서의 네 부분으로 구성됩니다.

  1. 제목 표시줄. 제목은 문제 종류를 대문자로 표시합니다. 경고와 안내는 WARNING:와 NOTE:로 시작합니다. 오른쪽에는 rst.substitution.undefined 같은 진단 코드가 있으며, 검색에 쓸 수 있는 고정된 이름입니다.
  2. 위치. 파일과 줄 번호, 소스 줄, 문제 텍스트 아래의 표시를 보여 줍니다. 누락된 폴더나 옵션처럼 특정 줄과 관계없는 문제는 경로만 표시하거나 위치를 생략합니다.
  3. 무슨 일이 일어났는가. 문제를 설명하고, 필요하면 출력에 미치는 영향도 알립니다. 이 예에서는 아무것도 기록하지 않았다는 뜻입니다.
  4. 어떻게 해결하는가. 컬러 터미널에서 초록색으로 표시하는 구체적인 안내입니다. 해결 방법이 여럿이면 가장 적합할 가능성이 높은 방법부터 나열합니다.

색상은 이미 문구로 설명한 내용을 강조할 뿐입니다. --color=never는 색상을 끄고, --color=always는 터미널이 아닌 출력에서도 색상을 유지합니다.

다음 행동을 안내하는 힌트

Guidedog의 메시지도 이 규칙을 따른다. 힌트는 작업("Add", "Pass", "Set", "Rename", "Run")과 대상을 먼저 밝힌다. 대상은 --budget=MIB, conf.toml의 root_doc, 지시문 옵션 등이다. tests/hints_test.odin은 모든 메시지를 읽고 빈 힌트, 메시지 반복, 무엇을 보고할지 없는 "report this"를 거부한다. 수정 자체를 제시하는 제안("Did you mean numfig?")과 작업이 필요 없는 메모의 "Nothing to do:" 및 그 이유도 허용한다.

Guidedog 자체의 오류이면 안내에서 이를 명확히 밝힙니다. 실행한 명령, 문제를 일으킨 입력, guidedog --version 출력을 함께 보고하도록 요청합니다.

프로그램용 진단

--diagnostics=json은 보고서마다 한 줄의 JSON 객체를 표준 오류에 써서 편집기와 지속적 통합에서 읽을 수 있게 한다.

{"schema":1,"code":"rst.substitution.undefined","severity":"error",
 "title":"UNDEFINED SUBSTITUTION","message":"The substitution \"|logo|\" is not defined.",
 "hint":"Add a definition, e.g. \".. |name| replace:: text\".","path":"guide/page.rst",
 "line":4,"column":5,"end_line":4,"end_column":11,"source":"See |logo| here.",
 "category":""}

여기서는 줄바꿈했지만 실제 객체는 한 줄이다. schema는 필드가 바뀔 때만 변경되는 형식 버전이며 나머지를 읽기 전에 확인한다. 열은 1부터 Unicode 스칼라를 센다. 바이트나 터미널 칸 수가 아니다. source는 원본 줄 전체다. 터미널은 오류 주변 일부를 보여 주며 제어 문자를 이스케이프하고 넓은 문자 폭을 측정해 표시를 맞춘다. category는 suppress_warnings의 경고 분류이거나 빈 값이다.

메모리가 부족할 때

메모리 부족도 진단으로 보고하며, 충돌하지 않습니다. 두 종류가 있습니다.

host.budget (메모리 예산 도달)

빌드가 보유 가능한 메모리 예산(--budget=MIB, 기본 1 GiB)에 도달했다. 보고서는 단계와, 템플릿이라면 메모리를 요청한 줄을 밝힌다. 터미널에서는 예산 확대, 작업 메모리의 디스크 전환, 중단 중 한 번 선택하게 한다. 그 밖의 환경에서는 중단한다. --budget 또는 --memory=disk로 미리 선택할 수 있다. 힌트도 같은 예산을 숫자로 제시한다.

Build again with --budget=256, or with --memory=disk to keep working memory on
disk (slower); or split the work into smaller files.

제안 값은 현재 보유량에 거부된 단계 요구량의 네 배를 더한 값(출력과 쓰기용 사본도 보유함)과 기존 예산의 두 배 중 큰 값을 64 MiB 단위로 올림한다. 단계가 가용 메모리에 들어갈 때는 그 순간의 가용량을 넘지 않는다. 들어가지 않으면 이를 밝히고 --memory=disk를 먼저 제안한다.

Build again with --memory=disk to keep working memory on disk (slower): the step
needs a budget of about 1408 MiB, more than the 900 MiB this machine has free. Or
free that memory and build with --budget=1408, or split the document.
host.memory (메모리 부족)

시스템이 예산 내의 메모리 요청을 거부했다. 명령은 거부된 공간을 쓰지 않고 멈춘다. 빌드는 아무것도 게시하지 않고, GDS 변경은 전부 적용하거나 전혀 적용하지 않으며, convert는 완전한 페이지를 쓰거나 아무것도 쓰지 않는다. 메모리를 확보하거나 스레드를 줄여(-j 1) 다시 실행한다. 게시 결정 뒤 출력 교체에는 메모리가 필요 없어 할당 거부로 게시가 중간에 멈추지 않는다. 이전 게시 복구를 계획할 메모리가 없으면 그대로 남겨 다음 빌드가 처리하게 한다.

둘 다 상태 3으로 끝납니다.

종료 상태

모든 명령은 다음 상태 중 하나로 끝나므로 스크립트에서 실패 종류를 구분할 수 있습니다.

상태 의미
0 성공입니다. 출력을 기록했고, 빌드라면 게시했습니다.
1 입력에 문제가 있습니다. 문서 오류, 정책 거부(--raw 없는 raw 콘텐츠), 읽을 수 없는 문서, 또는 -W나 --strict로 오류 처리한 경고입니다.
2 명령 사용법이 잘못되었습니다. 알 수 없는 옵션이나 명령, 누락되거나 잘못된 값, conf.toml 또는 -D의 잘못된 설정입니다.
3 한도에 도달했습니다. 메모리 예산(--budget), 중첩 깊이(--max-depth), 노드 수(--max-nodes), 스택(--stack-kib), 너무 큰 소스, 시스템 메모리 부족이 해당됩니다.
4 파일이나 외부 프로그램에서 실패했습니다. 읽거나 쓸 수 없는 경로, 읽는 동안 변경된 파일, Typst 시작 또는 완료 실패가 해당됩니다.
5 Guidedog 내부에서 실패했으며, 진단에서 문제 보고를 요청합니다.
70 Guidedog이 충돌하면 GUIDEDOG CRASHED (internal error)와 실행 명령, 오류, guidedog --version 출력을 표시한다. 보고할 곳은 빌드가 지정한 이슈 추적기 또는 빌드 제공자다. 빌드는 마지막에만 게시하므로 이전 출력은 그대로 남는다.
130 Ctrl+C로 명령을 중단했으며, 게시된 파일은 그대로입니다.

어떤 이유로 빌드가 실패하든 이전 출력과 빌드 기록을 유지합니다. 문제를 수정한 뒤 다시 빌드하세요.