Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Використання дезінфікуючих засобів

Що таке санітайзери?

Санітайзери — це статичні інструменти, які допомагають знаходити помилки, які традиційні налагоджувачі зазвичай не можуть виявити. Це особливо корисно в поєднанні з Модульне тестування у безперервній інтеграції.

Санітайзери можна використовувати в Windows, macOS і Linux за допомогою компіляторів Clang (LLVM), GCC або Visual Studio. Certain platforms також можуть мати власні дезінфікуючі засоби. У ситуаціях, коли один дезінфікуючий засіб надається кількома різними компіляторами, пам’ятайте, що їхні результати та поведінка дещо відрізнятимуться.

Використання дезінфікуючих засобів на Godot

Санітайзери вимагають перекомпілювати двійковий файл. Це означає, що ви не можете використовувати офіційні двійкові файли Godot для запуску дезінфікуючих засобів.

Під час compiling з увімкненими дезінфікуючими засобами, отриманий двійковий файл матиме суфікс .san до назви, щоб відрізнити його від двійкового файлу без дезінфікуючих засобів.

Існує вплив на продуктивність, оскільки потрібно виконувати багато додаткових перевірок під час виконання. Використання пам'яті також збільшиться. Можна ввімкнути певні комбінації кількох дезінфікуючих засобів в одній збірці. Остерігайтеся впливу на продуктивність під час використання кількох дезінфікуючих засобів одночасно, оскільки кінцевий двійковий файл може бути надто повільним.

Певні параметри можна передати в дезінфікуючі засоби без необхідності перекомпілювати двійковий файл за допомогою змінних середовища.

Адресний санітайзер (ASAN)

Адресний дезінфікуючий засіб зазвичай є найбільш часто використовуваним дезінфікуючим засобом. Він може діагностувати такі проблеми, як переповнення буфера та доступ поза межами. Якщо механізм аварійно завершує роботу з повідомленням на зразок free(): invalid pointer, зазвичай це результат переповнення буфера. (Це повідомлення друкує середовище виконання C, а не Godot.)

У певних ситуаціях (наприклад, виявлення неініціалізованих зчитувань пам’яті) засобу очищення адреси недостатньо. Замість цього слід використовувати Дезінфікуючий засіб пам'яті (MSAN).

Також можна виявити ситуації використання після повернення, вказавши змінну середовища ASAN_OPTIONS=detect_stack_use_after_return=1 перед запуском Godot (а не під час його компіляції). Це збільшує час виконання дезінфікуючої адреси, тому вмикайте цю функцію лише тоді, коли вона вам дійсно потрібна.

Щоб увімкнути дезінфекцію адрес у збірці Godot, передайте параметр use_asan=yes SCons під час компіляції. Увімкнення ASAN зазвичай робить кінцевий двійковий приблизно вдвічі повільнішим.

Попередження

Через дизайнерське рішення дезінфікуючі засоби адреси, пам’яті та потоку є взаємовиключними. Це означає, що ви можете використовувати лише один із цих санітайзерів у певному двійковому файлі.

Засіб для дезінфекції витоків (LSAN)

Засіб очищення від витоків може виявляти витоки пам’яті, коли пам’ять, яка більше не використовується, ніколи не звільняється запущеною програмою. Це потенційно може призвести до ситуацій нестачі пам’яті, якщо програма працює достатньо довго. Оскільки Godot може працювати на dedicated servers протягом місяців або навіть років без перезапуску, важливо виправляти витоки пам’яті, коли вони трапляються.

Щоб увімкнути засіб очищення від витоків у збірці Godot, передайте параметр use_lsan=yes SCons під час компіляції. Увімкнення LSAN має лише невеликі витрати на продуктивність, але програма буде виходити набагато повільніше, оскільки виявлення витоку відбувається під час виходу програми.

Дезінфікуючий засіб пам'яті (MSAN)

Засіб очищення пам’яті доповнює Адресний санітайзер (ASAN). На відміну від засобу очищення адреси, засіб очищення пам’яті може виявляти неініціалізовані зчитування пам’яті.

Щоб увімкнути очисник пам’яті в збірці Godot, передайте параметр use_msan=yes SCons під час компіляції. Увімкнення MSAN зазвичай робить кінцевий двійковий приблизно в 3 рази повільнішим.

Попередження

Через дизайнерське рішення дезінфікуючі засоби адреси, пам’яті та потоку є взаємовиключними. Це означає, що ви можете використовувати лише один із цих санітайзерів у певному двійковому файлі.

Дезінфікуючий засіб для ниток (TSAN)

Засіб дезінфекції потоків використовується для відстеження умов змагання, пов’язаних із багатопотоковістю. Умова змагання - це коли кілька потоків намагаються змінити ті самі дані одночасно. Оскільки операційна система може впорядковувати планування потоків у будь-який спосіб, це призводить до неправильної поведінки, яка трапляється лише час від часу (і тому може бути важко відстежити). Щоб запобігти умові змагання, потрібно додати блокування, щоб гарантувати, що лише один потік може отримати доступ до спільних даних у певний момент часу.

Щоб увімкнути дезінфекцію потоків у збірці Godot, передайте опцію use_tsan=yes SCons під час компіляції. Увімкнення TSAN зазвичай робить отриманий двійковий файл у 10 разів повільнішим, водночас примножуючи використання пам’яті приблизно на коефіцієнт 8 разів.

Попередження

Через дизайнерське рішення дезінфікуючі засоби адреси, пам’яті та потоку є взаємовиключними. Це означає, що ви можете використовувати лише один із цих санітайзерів у певному двійковому файлі.

Примітка

У Linux, якщо ви натрапили на таку помилку:

FATAL: ThreadSanitizer: unexpected memory mapping

Можливо, вам знадобиться тимчасово знизити ентропію рандомізації адресного простору (ASLR) у вашій системі за допомогою:

sudo sysctl vm.mmap_rnd_bits=28

Або краще повністю вимкнути його за допомогою:

sudo sysctl kernel.randomize_va_space=0

І як тільки ви закінчите з дезінфікуючим засобом потоку, збільште ентропію ASLR за допомогою:

sudo sysctl vm.mmap_rnd_bits=32

Або повторно ввімкніть ASLR за допомогою:

sudo sysctl kernel.randomize_va_space=2

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

Важливо скасувати зміни якомога швидше, оскільки зниження ентропії ASLR або повне вимкнення ASLR може становити загрозу безпеці.

Дезінфікуючий засіб невизначеної поведінки (UBSAN)

Засіб невизначеної поведінки використовується для відстеження ситуацій, коли програма демонструє випадкову та непередбачувану поведінку. Це пов’язано з кодом C/C++, який приймається компілятором, але не є коректним. Компіляція з іншим набором оптимізацій також може змінити спостережувані результати невизначеної поведінки.

Щоб увімкнути засіб дезінфекції невизначеної поведінки в збірці Godot, передайте параметр use_ubsan=yes SCons під час компіляції. Увімкнення UBSAN має лише невеликі витрати на продуктивність.

Дезінфікуючі засоби для конкретної платформи

Інтернет

Під час compiling for the Web доступні 2 додаткові опції дезінфекції SCons:

  • use_assertions=yes вмикає твердження Emscripten під час виконання, які можуть виявляти різні проблеми.

  • use_safe_heap=yes вмикає Sanitizer SAFE_HEAP від Emscripten. Він надає функціональність, схожу на ASAN, але зосереджується на проблемах, які є специфічними для WebAssembly. SAFE_HEAP не гарантовано буде сумісний з ASAN і UBSAN в одному двійковому файлі, тому вам, можливо, доведеться створювати його окремо.