쿼리 도움말 파일 테스트

쿼리 도움말 파일 테스트 정보

쿼리 도움말 파일을 Markdown으로 렌더링하여 CodeQL 리포지토리에 업로드하거나 코드 검사에서 사용하기 전에 유효한지 확인합니다.

쿼리 도움말은 쿼리 작동 방식을 설명하고 쿼리가 식별하는 잠재적인 문제에 대한 정보를 제공하는 쿼리와 함께 제공되는 설명서입니다. 모든 새 쿼리에 대한 쿼리 도움말을 작성하는 것이 좋습니다. 자세한 내용은 CodeQL 리포지토리에서 CodeQL에 기여를 참조하세요.

CodeQL CLI에는 쿼리 도움말을 테스트하고 콘텐츠를 markdown으로 렌더링하는 명령이 포함되어 있으므로 IDE의 콘텐츠를 쉽게 미리 볼 수 있습니다. 명령을 사용하여 CodeQL 리포지토리에 업로드하거나 다른 사용자와 공유하기 전에 쿼리 도움말 파일의 유효성을 검사합니다. CodeQL CLI 2.7.1 이상부터 CodeQL 분석 중에 생성된 SARIF 파일에 markdown 렌더링 쿼리 도움말을 포함하면 쿼리 도움말이 코드 검사 UI에 표시될 수 있습니다. 자세한 내용은 "CodeQL CLI을 사용하여 데이터베이스 분석"을 참조하세요.

필수 구성 요소

• 쿼리 도움말(.qhelp) 파일에는 기본 이름이 동일한 쿼리(.ql) 파일이 있어야 합니다.
• 쿼리 도움말 파일은 쿼리 도움말 설명서의 표준 구조 및 스타일을 따라야 합니다. 자세한 내용은 CodeQL 리포지토리의 쿼리 도움말 스타일 가이드 를 참조하세요.

실행 중 codeql generate query-help

다음 명령을 실행하여 쿼리 도움말 파일을 테스트할 수 있습니다.

codeql generate query-help <qhelp|query|dir|suite> --format=<format> [--output=<dir|file>]

여기서 <qhelp|query|dir|suite> 는 다음 중 하나입니다.

• 파일의 경로입니다 .qhelp .
• 파일의 경로입니다 .ql .
• 쿼리 및 쿼리 도움말 파일이 포함된 디렉터리의 경로입니다.
• 쿼리 도구 모음의 경로 또는 CodeQL 팩에 대한 잘 알려진 쿼리 도구 모음의 이름입니다. 자세한 내용은 "CodeQL 쿼리 도구 모음 만들기"를 참조하세요.

쿼리 도움말이 --format 렌더링되는 방법을 정의하는 옵션을 지정해야 합니다. 현재 쿼리 도움말을 markdown으로 렌더링하려면 를 지정 markdown 해야 합니다.

옵션은 --output 렌더링된 쿼리 도움말을 저장할 파일 경로를 정의합니다.

• 하나 이상의 .qhelp 파일을 정의하는 파일 또는 쿼리 도구 모음이 포함된 .qhelp 디렉터리의 경우 디렉터리를 지정 --output 해야 합니다. 출력 디렉터리 내의 파일 이름은 파일 이름에서 .qhelp 파생됩니다.
• 단일 .qhelp 또는 .ql 파일의 경우 옵션을 지정할 --output 수 있습니다. 출력 경로를 지정하지 않으면 렌더링된 쿼리 도움말이 에 stdout기록됩니다.

쿼리 도움말 파일을 테스트할 때 사용할 수 있는 모든 옵션에 대한 자세한 내용은 쿼리 도움말 참조 생성 설명서를 참조하세요.

결과

명령을 실행하면 CodeQL이(가) 함께 제공되는 .ql 파일이 있는 각 .qhelp 파일을 렌더링하려고 시도합니다. 단일 파일의 경우 옵션을 지정 --output 하지 않으면 렌더링된 stdout 콘텐츠가 에 인쇄됩니다. 다른 모든 사용 사례의 경우 렌더링된 콘텐츠는 지정된 출력 경로에 저장됩니다.

기본적으로 CodeQL CLI은 다음과 같은 경우 경고 메시지를 출력합니다.

• 잘못된 쿼리 도움말 요소에 대한 설명과 함께 쿼리 도움말이 잘못되었습니다.
• .qhelp 명령에 지정된 모든 파일은 함께 제공되는 .ql 파일과 동일한 기본 이름을 갖지 않습니다.
• .ql 명령에 지정된 모든 파일은 함께 제공되는 .qhelp 파일과 동일한 기본 이름을 갖지 않습니다.

명령에 옵션을 포함하여 --warnings CodeQL CLI에서 이러한 경고를 처리하는 방법을 알 수 있습니다. 자세한 내용은 쿼리 도움말 참조 생성 설명서를 참조하세요.

추가 참고 자료

• "도움말 파일 쿼리"