Sync course repository updates

.devcontainer/.clang-format

@@ -1,6 +1,9 @@
 ---
 Language: Cpp
-# BasedOnStyle:  Google
+# Єдиний стиль форматування C++ прикладів у курсі.
+# Файл копіюється в корінь devcontainer-а, щоб clang-format знаходив його
+# незалежно від директорії, з якої запускається команда.
+# BasedOnStyle: Google
 AccessModifierOffset: -2
 AlignAfterOpenBracket: Align
 AlignConsecutiveMacros: false

.devcontainer/.clang-tidy

@@ -0,0 +1,52 @@
+# clang-tidy використовується як static analysis шар для C++ коду.
+# Набір перевірок навмисно широкий, але не всі warning-и є помилками:
+# частину сигналу студенти мають навчитися читати поступово.
+Checks: >
+  -*,
+  bugprone-*,
+  clang-analyzer-*,
+  cppcoreguidelines-*,
+  modernize-*,
+  performance-*,
+  readability-*,
+  -readability-avoid-const-params-in-decls,
+  -readability-function-cognitive-complexity,
+  misc-unused-using-decls,
+
+# Аналізувати лише код домашніх робіт і типові source/include директорії,
+# а не системні headers або сторонні бібліотеки.
+HeaderFilterRegex: '(^|/)(homework_[0-9]+|include|src)/'
+
+# Помилки analyzer/core-guidelines/modernize мають ламати перевірку.
+# Readability і performance лишаються попередженнями, щоб не блокувати
+# навчальні ітерації надто рано.
+WarningsAsErrors: clang-analyzer-*,
+  cppcoreguidelines-*,
+  modernize-*,
+
+# Naming rules формують один стиль для прикладів курсу.
+CheckOptions:
+  - key: readability-identifier-naming.FunctionCase
+    value: lower_case
+  - key: readability-identifier-naming.VariableCase
+    value: lower_case
+  - key: readability-identifier-naming.ConstantCase
+    value: CamelCase
+  - key: readability-identifier-naming.ConstantPrefix
+    value: k
+  - key: readability-identifier-naming.LocalVariableCase
+    value: lower_case
+  - key: readability-identifier-naming.ParameterCase
+    value: lower_case
+  - key: readability-identifier-naming.MemberCase
+    value: lower_case
+  - key: readability-identifier-naming.MemberSuffix
+    value: _
+  - key: readability-identifier-naming.PrivateMemberCase
+    value: lower_case
+  - key: readability-identifier-naming.PrivateMemberSuffix
+    value: _
+  - key: readability-identifier-naming.ClassCase
+    value: CamelCase
+  - key: readability-identifier-naming.StructCase
+    value: CamelCase

.devcontainer/.clangd

@@ -1,4 +1,17 @@
+# clangd працює як language server у VS Code.
+# Основна інформація про include paths і compile flags береться з
+# compile_commands.json, який генерує root CMakeLists.txt.
 InlayHints:
   Enabled: Yes
+  # Імена параметрів у викликах не показуються, щоб не перевантажувати
+  # екран на простих прикладах.
   ParameterNames: No
+  # Типи, виведені через auto, корисно бачити під час навчання C++.
   DeducedTypes: Yes
+
+# clang-tidy конфіг лежить у repo/container, але diagnostics вимкнено до
+# заняття 2.6, де static analysis буде окремою темою.
+Diagnostics:
+  ClangTidy:
+    Remove:
+      - '*'

.devcontainer/.cmake-format.json

@@ -1,4 +1,9 @@
 {
+    "_course_note": [
+        "Конфіг cmake-format для CMakeLists.txt у курсі.",
+        "Файл копіюється в корінь devcontainer-а, щоб formatter знаходив",
+        "його незалежно від поточної директорії запуску."
+    ],
     "_help_parse": "Options affecting listfile parsing",
     "parse": {
         "_help_additional_commands": [

.devcontainer/Dockerfile

@@ -12,7 +12,7 @@
 #   docker inspect --format='{{index .RepoDigests 0}}' ubuntu:noble
 FROM ubuntu:noble@sha256:c4a8d5503dfb2a3eb8ab5f807da5bc69a85730fb49b5cfca2330194ebcc41c7b
 
-# Noninteractive frontend, щоб apt не зависнув чекаючи відповіді на
+# Неінтерактивний frontend, щоб apt не зависнув чекаючи відповіді на
 # питання (часовий пояс, клавіатура, kernel upgrade prompt). У Dockerfile
 # інтерактивного stdin немає - без цього build може зависнути назавжди.
 ARG DEBIAN_FRONTEND="noninteractive"
@@ -39,10 +39,11 @@ RUN apt update && \
 # запуску - тобто вони знайдуться незалежно від того, де всередині
 # контейнера змонтовано проєкт.
 COPY .clang-format /.clang-format
+COPY .clang-tidy /.clang-tidy
 COPY .clangd /.clangd
 COPY .cmake-format.json /.cmake-format.json
 
-# Environment:
+# Змінні середовища:
 # - TZ: UTC як нейтральний дефолт. Логи завжди в UTC, без суперечок з
 #   літнім часом різних регіонів.
 # - LC_ALL / LANG / LANGUAGE: en_US.UTF-8 щоб stdout/stderr коректно
@@ -52,7 +53,7 @@ ENV LC_ALL=en_US.UTF-8
 ENV LANG=en_US.UTF-8
 ENV LANGUAGE=en_US:en
 
-# Passwordless sudo для dev-контейнера: зручно для apt install на ходу,
+# sudo без пароля для dev-контейнера: зручно для apt install на ходу,
 # debug tools, etc. У прод-образах ніколи - там контейнер має жорстко
 # визначений набір прав.
 RUN echo "ALL ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers

.devcontainer/apt-packages.in

@@ -1,3 +1,4 @@
+# Базові пакети для стабільної роботи Ubuntu image.
 ca-certificates
 curl
 locales
@@ -6,9 +7,26 @@ tzdata
 ssh
 git
 
+# C++ toolchain і language server для редактора.
 gcc
 clang
 clangd
+clang-tidy
+
+# Runtime-бібліотеки Clang sanitizer-ів і symbolizer для читабельного ASan/UBSan output.
+libclang-rt-18-dev
+llvm-18
+
+# Крос-тулчейн для ARM64-пристроїв: RPi4, Radxa ROCK 5B+, Jetson.
+g++-aarch64-linux-gnu
+
+# Інструменти для заняття 2.4: локальний і remote debug, memory diagnostics.
+gdb
+gdbserver
+gdb-multiarch
+valgrind
+
+# Інструменти збірки і форматери, які використовуються в лекціях та CI.
 make
 cmake
 clang-format

.devcontainer/devcontainer.json

@@ -1,43 +1,72 @@
 {
+  // Назва, яка показується у VS Code Dev Containers UI.
   "name": "CPP MilTech",
+  // Image збирається з локального Dockerfile. Аргументи потрібні, щоб
+  // container user і workspace path збігалися з host-сесією.
   "build": {
     "dockerfile": "Dockerfile",
     "args": {
       "WORKSPACE_FOLDER": "${localEnv:HOME}/${localWorkspaceFolderBasename}",
       "CONTAINER_USER": "${localEnv:USER}"
     }
   },
+  // VS Code відкриває контейнер від імені того самого користувача, що й host.
+  // Це зменшує проблеми з ownership файлів у bind mount.
   "remoteUser": "${localEnv:USER}",
+  // Проєкт монтується у домашню директорію користувача всередині контейнера.
+  // Так шляхи виглядають однаково на Linux, macOS і Windows+WSL.
   "workspaceMount": "source=${localWorkspaceFolder},target=${localEnv:HOME}/${localWorkspaceFolderBasename},type=bind",
   "workspaceFolder": "${localEnv:HOME}/${localWorkspaceFolderBasename}",
+  // SSH ключі потрібні для git operations. bash_history винесено на host,
+  // щоб історія команд переживала rebuild контейнера.
   "mounts": [
     "source=${localEnv:HOME}/.ssh,target=/home/${localEnv:USER}/.ssh,type=bind,readonly,consistency=cached",
-    "source=${localEnv:HOME}/.devcontainers/${localWorkspaceFolderBasename}/.bash_history,target=/home/${localEnv:USER}/.bash_history,type=bind,consistency=delegated",
+    "source=${localEnv:HOME}/.devcontainers/${localWorkspaceFolderBasename}/.bash_history,target=/home/${localEnv:USER}/.bash_history,type=bind,consistency=delegated"
   ],
+  // initialize створює host-side директорії для mounts до старту container-а.
+  // Запуск через bash робить команду стійкою до копіювання без executable bit.
   "initializeCommand": [
+    "bash",
     ".devcontainer/scripts/initialize"
   ],
+  // host network спрощує SSH/debug сценарії для занять з target-пристроями.
+  // SYS_PTRACE і seccomp=unconfined потрібні для стабільної роботи GDB
+  // всередині контейнера, особливо коли debug-сесія attach-иться до процесу.
+  // ulimit core=-1 дозволяє процесам у контейнері створювати core dump.
+  // Сам шлях/формат core-файла все одно визначає host kernel через
+  // /proc/sys/kernel/core_pattern; у WSL це налаштовується окремо на host.
   "runArgs": [
     "--network=host",
+    "--cap-add=SYS_PTRACE",
+    "--security-opt=seccomp=unconfined",
+    "--ulimit=core=-1",
     "--hostname=devcontainer",
     "--add-host=devcontainer:127.0.1.1"
   ],
+  // Усе всередині customizations.vscode застосовується саме до VS Code
+  // сесії в контейнері. Це не те саме, що .vscode/extensions.json на host.
   "customizations": {
     "vscode": {
+      // Extensions встановлюються в devcontainer, щоб tooling був однаковий
+      // у всіх студентів незалежно від host VS Code.
       "extensions": [
         "josetr.cmake-language-support-vscode",
         "cheshirekow.cmake-format",
         "ms-vscode.cpptools",
         "llvm-vs-code-extensions.vscode-clangd"
       ],
       "settings": {
+        // clangd читає build/debug/compile_commands.json з debug preset.
+        // clang-tidy конфіг лишається в репозиторії, але автоматичний запуск
+        // через clangd буде увімкнено пізніше, після заняття 2.6.
         "clangd.path": "/usr/bin/clangd",
         "clangd.arguments": [
-          "--compile-commands-dir=ada_ws/build/x86_64/",
-          "--clang-tidy",
+          "--compile-commands-dir=build/debug",
           "--background-index"
         ],
         "clangd.restartAfterCrash": true,
+        // IntelliSense від Microsoft C++ extension вимкнено, щоб не було двох
+        // C++ language server-ів одночасно. Основний engine - clangd.
         "C_Cpp.intelliSenseEngine": "disabled",
         "[cpp]": {
           "editor.defaultFormatter": "llvm-vs-code-extensions.vscode-clangd",
@@ -50,18 +79,21 @@
         "[cmake]": {
           "editor.defaultFormatter": "cheshirekow.cmake-format"
         },
+        // cmake-format читає конфіг, який Dockerfile копіює в /.
         "cmakeFormat.args": [
           "--config-file=/.cmake-format.json"
         ],
-        "cmakeFormat.exePath": "/usr/bin/cmake-format"
-      }
-    },
-    "terminal.integrated.shell.linux": "bash",
-    "terminal.integrated.profiles.linux": {
-      "bash (container default)": {
-        "path": "/bin/bash",
-        "overrideName": true
+        "cmakeFormat.exePath": "/usr/bin/cmake-format",
+        // Єдиний bash profile у container terminal. Історія команд монтується
+        // окремо через mounts вище.
+        "terminal.integrated.defaultProfile.linux": "bash (container default)",
+        "terminal.integrated.profiles.linux": {
+          "bash (container default)": {
+            "path": "/bin/bash",
+            "overrideName": true
+          }
+        }
       }
     }
   }
-}
+}

.devcontainer/scripts/initialize

@@ -1,13 +1,13 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Runs on the host (macOS, Linux, WSL2) before the container starts.
-# Creates a bash history file under the host's home so shell history
-# persists across container rebuilds.
+# Скрипт виконується на host-системі (macOS, Linux, WSL2) до старту
+# контейнера. Тут створюються host-side файли, які потім монтуються
+# у devcontainer.
 DEVCONTAINER_DATA_ON_HOST="${HOME}/.devcontainers/$(basename "${PWD}")"
 mkdir -p "${DEVCONTAINER_DATA_ON_HOST}"
 touch "${DEVCONTAINER_DATA_ON_HOST}/.bash_history"
 
-# Ensure ~/.ssh exists so the bind-mount in devcontainer.json does not fail
-# on fresh machines where the user never generated SSH keys yet.
+# ~/.ssh має існувати до bind mount з devcontainer.json. На свіжих машинах
+# SSH ключів може ще не бути, і без цієї директорії container start падає.
 [ -d "${HOME}/.ssh" ] || mkdir -m 700 "${HOME}/.ssh"

.gitattributes

@@ -1,9 +1,14 @@
+# Нормалізувати текстові файли до LF, щоб приклади однаково працювали на
+# Linux, macOS і Windows+WSL.
 * text=auto eol=lf
 
+# Shell scripts і devcontainer hooks завжди мають LF, інакше bash у Linux
+# контейнері може падати на CRLF.
 *.sh text eol=lf
 .devcontainer/scripts/* text eol=lf
 Dockerfile text eol=lf
 
+# Бінарні assets не проходять text normalization.
 *.png binary
 *.jpg binary
 *.jpeg binary

.github/workflows/build.yml

@@ -39,9 +39,10 @@ jobs:
       # 4. Монтує checkout у workspaceFolder.
       # 5. Виконує runCmd від імені remoteUser.
       #
-      # -G Ninja: явно обираємо Ninja-генератор. ninja-build уже є у
-      # devcontainer-і, швидший за Make на проєктах з багатьма файлами
-      # (кращий паралелізм, менше overhead-у на запуск shell-команд).
+      # CMake preset debug тримає локальну і CI-збірку в одному місці:
+      # build/debug. Це також збігається з clangd compile_commands і
+      # VS Code debug launch config. ARM64 preset додатково перевіряє,
+      # що demo-код можна крос-компілювати для SBC target-а.
       - name: Build inside dev container
         uses: devcontainers/ci@v0.3
         with:
@@ -51,5 +52,7 @@ jobs:
           # на runner-і для runCmd.
           push: never
           runCmd: |
-            cmake -S . -B build -G Ninja
-            cmake --build build
+            cmake --preset debug
+            cmake --build --preset debug
+            cmake --preset aarch64-debug
+            cmake --build --preset aarch64-debug