Утилита для локальной отладки задач

yc-invoke — утилита для запуска задач из Яндекс Контеста локально на устройстве автора задачи. Она позволяет:

• Запускать на проверку локальные файлы решения, в том числе на ограниченном количестве тестов.
• Отлаживать решения с помощью механизмов удаленного дебага.
• Получить доступ к терминалу контейнера на различных шагах проверки задачи.

Требования к системе и установка

Системные требования

Установка и обновление

Выполните в терминале команду, чтобы установить последнюю версию утилиты:

powershell -ExecutionPolicy ByPass -c "irm https://yastatic.net/s3/contest/yc-invoke/install.ps1 | iex"

curl -fsSL https://yastatic.net/s3/contest/yc-invoke/install.sh | sudo sh -

Для обновления повторно выполните команду установки.

Настройка и удаление

Для настройки утилиты локальной отладки выполните в терминале следующую команду:

yc-invoke configure

После ее выполнения автоматически откроется браузер. Подтвердите доступ и введите код из браузера в терминал для аутентификации.

Удаление

rmdir /s /q %appdata%/yc-invoke
rmdir /s /q %localappdata%/yc-invoke

sudo rm /usr/local/bin/yc-invoke
rm -rf "~/.config/yc-invoke"
rm -rf "~/.cache/yc-invoke"

sudo rm /usr/local/bin/yc-invoke
rm -rf "~/Library/Application Support/yc-invoke"
rm -rf "~/Library/Caches/yc-invoke"

Локальная отладка задачи

Для того чтобы провести локальную отладку, вам понадобится:

• Установленная и настроенная утилита локальной отладки;
• ID настроенной в Яндекс Контесте задачи, для которой у вас есть права на редактирование;
• ID компилятора, с помощью которого будет отправляться решение в задачу.

Запуск утилиты для отладки:

yc-invoke run PROBLEM_ID COMPILER_ID PATH_TO_SOLUTION

• PROBLEM_ID — ID задачи в виде трех буквенно-цифровых последовательностей, разделенных /.
• COMPILER_ID — ID компилятора.
• PATH_TO_SOLUTION — путь к файлу вашего решения.

Пример команды: yc-invoke run 12345/2000-01-01/abCdefGjkL gcc_cpp20 solution.cpp.

Подсказку по вызову для конкретной задачи и компилятора можно посмотреть в разделе Тесты и решения.

Локальные файлы задачи

Вы можете указать локальную директорию, в которой частично или полностью лежит файловая система задачи. Если в этой директории будет обнаружен какой-то файл, необходимый для запуска (тест, чекер и т.д.), он будет использован вместо файла из задачи, загруженного через панель администратора.

Для этого при запуске утилиты используйте флаг --problem-files и укажите путь к директории:

yc-invoke run 12345/2000-01-01/abCdefGjkL gcc_cpp20 solution.cpp --problem-files ./some-problem-files

Запуск на выбранных тестах

Когда нужно запустить задачу на ограниченном количестве тестов, можете указать маску, по которой они будут выбраны.

Для этого при запуске утилиты используйте флаг --tests с указанием желаемых тестов:

yc-invoke run 12345/2000-01-01/abCdefGjkL gcc_cpp20 solution.cpp --tests tests/{01-05,07}

Синтаксис написания масок соответствует выражениям, используемым в настройке шаблона входного файла Наборов тестов.

Доступ в сеть

Чтобы включить доступ в интернет во время локального запуска задачи, используйте флаг --network:

yc-invoke run 12345/2000-01-01/abCdefGjkL gcc_cpp20 solution.cpp --network

Терминал контейнера

Вы можете подключиться к терминалу контейнера, чтобы проверить, какие именно файлы и окружение вам доступно. Для этого добавьте флаг --pause к команде yc-invoke run.

После создания изолированного контейнера, но перед запуском каждого процесса (компиляции, исполнения, чекера) процесс тестирования будет приостановлен и утилита предоставит вам команду для подключения к контейнеру:

$ yc-invoke run 12345/2000-01-01/abCdefGjkL gcc_cpp20 solution.cpp --pause

⏸︎ Compiling solution
Open container shell: docker exec -it debbfc022e6b2ea2ade2806ef458c904d6e3ff3a72163c01ee64916903be4d99 bash
'c' to continue • Ctrl-C to abort

Выполните эту команду в соседнем терминале, чтобы подключиться к контейнеру. Вы можете нажать кнопку c, чтобы запустить соответствующий процесс. Контейнер завершится сразу после завершения этого процесса — терминал так же закроется в этот момент.

Отладка решения

Вы можете подключиться к контейнеру с отладчиком, чтобы найти ошибку в решении или дополнительных файлах.

Рекомендуется использовать механизмы удалённого дебага в вашем языке программирования. Дополнительные флаги компиляции вы можете добавить только в Make-задачи, где есть возможность управлять флагами компилятора.

Чтобы сетевой порт стал доступен, при запуске утилиты используйте флаг --expose. Например, --expose 8000 предоставит на порту 8000 вашего ПК доступ к порту 8000 контейнера.

Также вы можете:

• Открыть несколько портов: --expose 8000,9000;
• Пробросить порт на порт вашего ПК с другим номером: --expose 8000:9000 предоставит на порту 8000 вашего ПК доступ к порту 9000 контейнера;
• Пробросить UDP-порт: --expose 8000/udp

Для других языков программирования отладка происходит аналогично. Воспользуйтесь руководством разработчика соответствующего языка, чтобы найти нужные настройки.

Если в вашем языке нет решения для удалённой отладки, вы можете выводить данные в стандартный поток ошибок (stderr). Такой вывод показывается в терминале при исполнении. Флаг -v при запуске утилиты предотвратит очистку вывода после завершения процесса.

При возникновении проблем

Если в утилите произошла какая-то ошибка, повторите запуск, добавив флаг -v. Этот флаг увеличивает количество выводимой информации:

yc-invoke run 12345/2000-01-01/abCdefGjkL gcc_cpp20 solution.cpp -v

Подробный лог хранится в системной директории приложения:

• Windows: %AppData%\yc-invoke\yc-invoke.log.
• Linux: ~/.config/yc-invoke/yc-invoke.log.
• macOS: ~/Library/Application Support/yc-invoke/yc-invoke.log.

Ограничения в работе утилиты

• Время исполнения задачи через утилиту измеряется с меньшей точностью, чем при обычном запуске задачи в системе Яндекс Контест. Запуски одной и той же задачи с одинаковыми настройками могут приводить к разным результатам.

  В случае запуска на ARM-процессорах решение запускается с использованием программной виртуализации, и это может приводить к разнице во времени с Контестом в десятки раз.

• Утилита некорректно определяет расход памяти, составляющий менее 10 МБ.

• При приближении к лимиту памяти и аллокации небольшими фрагментами памяти вместо моментального выставления вердикта Memory limit exceeded (ML) решение может зависнуть перед падением (в частности, получить вердикты Time-limit exceeded (TL) или Idleness limit exceeded (IL) вместо ML). Это особенность Linux и cgroups.

  Аналогично, при превышении лимита на количество процессов система Яндекс Контест аварийно завершает решение; а утилита вместо этого возвращает ошибку системным вызовам fork(..) и аналогам, в связи с чем решение может упасть с какой-то собственной ошибкой или даже продолжить работу.

• Поддерживаются только TESTLIB_EXITCODE_CHECKER, EJUDGE_EXITCODE_CHECKER и стандартные чекеры. Нет поддержки чекеров типа TESTLIB_CHECKER (XML-вывод на основе testlib.pas).

• Не поддерживаются чекеры без указания компилятора (Legacy-запуск с шебангом).

• Не поддерживаются «недокерные» компиляторы, а также компиляторы, собранные поверх Ubuntu 18.04 и 20.04.

• Не гарантируется изоляция запускаемых процессов от хост-системы: запускать недоверенный код не рекомендуется.

Ограничения, которые будут устранены в последующих релизах

• Поддержано ограниченное множество компиляторов: GCC (C17, C23, C++20, C++23), Clang (C++20, C++23), C# (.NET 8), Bash 5, Go, JDK 22, Node.js 20, Node.js 22, PyPy 3, Python 3.13, Swift 6, TypeScript 5.8 и Make-аналоги.
• Не запускается постпроцессор.
• Поддержан только тип задачи PROBLEM_WITH_CHECKER.
• Не поддержано ограничение на объём вывода.
• Возможен некорректный подсчёт количества потоков, когда их меньше 10.