В этом материале описывается последний выпуск Интерфейса командной строки CodeQL. Дополнительные сведения об этом выпуске см. в разделе https://github.com/github/codeql-cli-binaries/releases.
Чтобы просмотреть сведения о параметрах, доступных для этой команды в более раннем выпуске, выполните команду с параметром в терминале --help .
Краткий обзор
codeql query run (--database=<database> | --dataset=<dataset>) [--output=<file.bqrs>] [--threads=<num>] [--ram=<MB>] <options>... -- <file.ql>Описание
Выполните один запрос.
Эта команда выполняет один запрос к базе данных CodeQL или необработанному набору данных QL.
По умолчанию результат запроса будет отображаться в терминале в удобной для человека отрисовке. Если вы хотите выполнить дальнейшую обработку результатов, настоятельно рекомендуется использовать --output параметр для записи результатов в файл в промежуточном двоичном формате, который затем можно распаковывать в различные более удобные для компьютера представления с помощью декодирования codeql bqrs.
Если запрос выдает результаты в форме, которую можно интерпретировать как оповещения исходного кода, анализ базы данных codeql может оказаться более удобным способом его выполнения. В частности, анализ базы данных codeql может создавать выходные данные в формате SARIF, который можно использовать с различными средствами просмотра оповещений.
Сведения о параллельном выполнении нескольких запросов см. в разделе Run-queries базы данных codeql.
Основные параметры
<file.ql>
[Обязательный] Источник QL выполняемого запроса.
-o, --output=<file.bqrs>
Файл, в котором будут выводиться данные запроса, будут записаны в формате BQRS.
Параметры выбора запрашиваемого содержимого
Необходимо указать именно один из этих вариантов.
-d, --database=<database>
Путь к базе данных CodeQL для запроса.
--dataset=<dataset>
[Дополнительно] Путь к необработанному набору данных QL для запроса.
Параметры для управления оценщиком запросов
--[no-]tuple-counting
[Дополнительно] Отображение счетчиков кортежей для каждого этапа оценки в журналах средства оценки запросов. --evaluator-log Если этот параметр указан, счетчики кортежей будут включены в текстовые и структурированные журналы JSON, созданные командой . (Это может быть полезно для оптимизации производительности сложного кода QL.)
--timeout=<seconds>
[Дополнительно] Установите время ожидания для оценки запроса в секундах.
Функция времени ожидания предназначена для перехвата случаев, когда для оценки сложного запроса потребуется "навсегда". Это не эффективный способ ограничить общее время, которое может занять вычисление запроса. Оценка будет продолжаться до тех пор, пока каждая отдельная часть вычисления по времени завершается в течение времени ожидания. В настоящее время эти отдельные временные части являются уровнями RA оптимизированного запроса, но в будущем они могут измениться.
Если время ожидания не указано или равно 0, время ожидания не устанавливается (за исключением тестового запуска codeql, где время ожидания по умолчанию составляет 5 минут).
-j, --threads=<num>
Используйте это количество потоков для оценки запросов.
По умолчанию равен 1. Можно передать 0, чтобы использовать один поток на каждом ядре на компьютере, или -N , чтобы оставить N ядер неиспользуемых (за исключением использования хотя бы одного потока).
--[no-]save-cache
[Дополнительно] Агрессивно записывайте промежуточные результаты в кэш диска. Это занимает больше времени и использует (гораздо) больше места на диске, но может ускорить последующее выполнение аналогичных запросов.
--[no-]expect-discarded-cache
[Дополнительные возможности. Принимать решения о том, какие предикаты следует оценивать и что записывать в кэш диска, исходя из предположения, что кэш будет удален после выполнения запросов.
--[no-]keep-full-cache
[Дополнительно. Не очищайте кэш диска после завершения оценки. Это может сэкономить время, если вы собираетесь выполнить очистку набора данных codeql или очистку базы данных codeql .
--max-disk-cache=<MB>
Задайте максимальный объем пространства, который может использовать кэш диска для промежуточных результатов запроса.
Если этот размер не настроен явным образом, средство оценки попытается использовать "разумный" объем кэша в зависимости от размера набора данных и сложности запросов. Явное задание более высокого предела, чем это использование по умолчанию, включит дополнительное кэширование, что может ускорить последующие запросы.
--min-disk-free=<MB>
[Дополнительно] Задайте целевой объем свободного места в файловой системе.
Если --max-disk-cache значение не задано, средство оценки попытается ограничить использование кэша диска, если свободное пространство в файловой системе окажется ниже этого значения.
--min-disk-free-pct=<pct>
[Дополнительно] Задайте целевую долю свободного места в файловой системе.
Если --max-disk-cache значение не задано, средство оценки попытается ограничить использование кэша диска, если свободное пространство в файловой системе будет меньше этого процента.
--external=<pred>=<file.csv>
CSV-файл, содержащий строки для внешнего предиката \--external вариантов.
--xterm-progress=<mode>
[Дополнительно] Определяет, следует ли отображать отслеживание хода выполнения во время оценки QL с помощью последовательностей элементов управления xterm. Возможны следующие значения:
no: никогда не производить фантазии прогресса; Предположим, глупый терминал.
auto(по умолчанию): автоматически определяет, выполняется ли команда в соответствующем терминале.
yes: предположим, что терминал может понимать последовательности элементов управления xterm. Функция по-прежнему зависит от возможности автоматического определение размера терминала и также будет отключена, если -q она задана.
25x80 (или аналогично): например yes, а также явно укажите размер терминала.
25x80:/dev/pts/17 (или аналогичный): отображение хода выполнения на терминале, отличном от stderr. В основном используется для внутреннего тестирования.
Параметры управления выходными данными структурированных журналов средства оценки
--evaluator-log=<file>
[Дополнительно] Вывод структурированных журналов о производительности средства оценки в указанный файл. Формат этого файла журнала может быть изменен без уведомления, но будет потоком объектов JSON, разделенных двумя символами новой строки (по умолчанию) или одним, если --evaluator-log-minify параметр передан. Используйте для codeql generate log-summary <file> создания более стабильной сводки по этому файлу и избегайте непосредственного анализа файла. Файл будет перезаписан, если он уже существует.
--evaluator-log-minify
[Дополнительно] Если --evaluator-log параметр передан, передача этого параметра позволит свести к минимуму размер создаваемого журнала JSON за счет того, что он будет гораздо менее удобочитаемым.
Параметры управления использованием ОЗУ
-M, --ram=<MB>
Задайте общий объем ОЗУ, который должен быть разрешен для использования оценщиком запросов.
Параметры управления компиляцией QL
--warnings=<mode>
Обработка предупреждений от компилятора QL. Одно из двух значений:
hide: отключение предупреждений.
show(по умолчанию): вывод предупреждений, но продолжение компиляции.
error: предупреждения обрабатываются как ошибки.
--[no-]debug-info
Выдача сведений о расположении источника в RA для отладки.
--[no-]fast-compilation
[Не рекомендуется] [Дополнительно] Пропускать особенно медленные шаги оптимизации.
--no-release-compatibility
[Дополнительно. Используйте новейшие функции компилятора за счет переносимости.
Время от времени новые функции языка QL и оптимизация средства оценки будут поддерживаться QL Evauator в нескольких выпусках, прежде чем они будут включены по умолчанию в компиляторе QL. Это гарантирует, что производительность при разработке запросов в последнем выпуске CodeQL может соответствовать немного более старым выпускам, которые все еще могут использоваться для сканирования кода или интеграции CI.
Если вы не заботитесь о том, чтобы ваши запросы были совместимы с другими (более ранними или более поздними) выпусками CodeQL, иногда можно достичь небольшой дополнительной производительности с помощью этого флага, чтобы включить последние улучшения в компиляторе на ранних этапах.
В выпусках, в которых нет последних улучшений для включения, этот параметр не выполняет никаких действий. Таким образом, его можно установить раз и навсегда в глобальном файле конфигурации CodeQL.
Новейшие функции всегда включены по умолчанию в тестовом запуске codeql.
--[no-]local-checking
Выполняйте начальные проверки только той части источника QL, которая используется.
--no-metadata-verification
Не проверка внедренные метаданные запроса в комментариях QLDoc для допустимости.
--compilation-cache-size=<MB>
[Дополнительно. Переопределите максимальный размер каталога кэша компиляции по умолчанию.
Параметры настройки среды компиляции
--search-path=<dir>[:<dir>...]
Список каталогов, в которых можно найти пакеты QL. Каждый каталог может быть либо пакетом QL (или пакетом пакетов, содержащим файл в корневом .codeqlmanifest.json каталоге), либо непосредственным родительским элементом одного или нескольких таких каталогов.
Если путь содержит несколько каталогов, их порядок определяет приоритет между ними: если имя пакета, которое необходимо разрешить, совпадает в нескольких деревьях каталогов, то первое из них выигрывает.
Указание на это при извлечении репозитория CodeQL с открытым кодом должно работать при запросе одного из языков, которые там живут.
Если вы извлекли репозиторий CodeQL как одноуровневый элемент распакованой цепочки инструментов CodeQL, вам не нужно предоставлять этот параметр. В таких каталогах всегда будет выполняться поиск пакетов QL, которые невозможно найти в противном случае. (Если это значение по умолчанию не работает, настоятельно рекомендуется выполнить настройку --search-path раз и навсегда в файле конфигурации для каждого пользователя.
(Примечание. В Windows разделитель пути — ).;
--additional-packs=<dir>[:<dir>...]
Если указан этот список каталогов, они будут искать пакеты перед теми, которые в --search-path. Порядок между ними не имеет значения; Это ошибка, если имя пакета найдено в двух разных местах в этом списке.
Это полезно, если вы временно разрабатываете новую версию пакета, которая также отображается в пути по умолчанию. С другой стороны, не рекомендуется переопределять этот параметр в файле конфигурации. некоторые внутренние действия добавляют этот параметр на лету, переопределяя любое настроенное значение.
(Примечание. В Windows разделитель пути — ).;
--library-path=<dir>[:<dir>...]
[Дополнительно] Необязательный список каталогов, которые будут добавлены в путь поиска необработанного импорта для библиотек QL. Его следует использовать только в том случае, если вы используете библиотеки QL, которые не были упакованы как пакеты QL.
(Примечание. В Windows разделитель пути — ).;
--dbscheme=<file>
[Дополнительно] Явным образом определяет, для каких запросов dbscheme следует компилироваться. Это должно быть дано только абонентами, которые очень уверены в том, что они делают.
--compilation-cache=<dir>
[Дополнительно] Укажите дополнительный каталог для использования в качестве кэша компиляции.
--no-default-compilation-cache
[Дополнительно] Не используйте кэши компиляции в стандартных расположениях, например в пакете QL, содержавшем запрос, или в каталоге цепочки инструментов CodeQL.
Параметры настройки диспетчера пакетов CodeQL
--registries-auth-stdin
Выполните проверку подлинности в реестрах контейнеров GitHub Enterprise Server, передав список \<registry_url>=\
Например, можно передать "https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2" для проверки подлинности в два экземпляра GitHub Enterprise Server.
Это переопределяет переменные среды CODEQL_REGISTRIES_AUTH и GITHUB_TOKEN. Если вам нужно пройти проверку подлинности только в реестре контейнеров github.com, можно использовать более простой --github-auth-stdin вариант.
--github-auth-stdin
Выполните проверку подлинности в реестре контейнеров github.com, передав github.com маркер GitHub Apps или личный маркер доступа через стандартные входные данные.
Чтобы пройти проверку подлинности в реестрах контейнеров GitHub Enterprise Server, передайте --registries-auth-stdin или используйте переменную среды CODEQL_REGISTRIES_AUTH.
Это переопределяет переменную среды GITHUB_TOKEN.
Общие параметры
-h, --help
Показать этот текст справки.
-J=<opt>
[Дополнительно] Предоставьте параметр виртуальной машине JVM, выполняющую команду .
(Остерегайтесь, что параметры, содержащие пробелы, будут обрабатываться неправильно.)
-v, --verbose
Постепенно увеличивайте количество выводемых сообщений о ходе выполнения.
-q, --quiet
Постепенно уменьшайте количество выводемых сообщений о ходе выполнения.
--verbosity=<level>
[Дополнительно] Явно задайте уровень детализации для одной из ошибок, предупреждений, progress, progress+, progress++, progress+++. Переопределяет -v и -q.
--logdir=<dir>
[Дополнительно] Запись подробных журналов в один или несколько файлов в указанном каталоге с созданными именами, включающими метки времени и имя выполняющейся подкоманды.
(Чтобы записать файл журнала с именем, над которым у вас есть полный контроль, вместо этого при необходимости предоставьте --log-to-stderr и перенаправьте stderr.)