From b61f23ba4c08cf281c48eb3d2f6fbe1899fd4cd4 Mon Sep 17 00:00:00 2001 From: Arseniy Obolenskiy Date: Sun, 27 Jul 2025 12:54:19 +0200 Subject: [PATCH 1/2] Add .devcontainer/devcontainer.json --- .devcontainer/devcontainer.json | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 .devcontainer/devcontainer.json diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 000000000..95b44a342 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,18 @@ +{ + "name": "Parallel Programming Course", + "image": "ghcr.io/learning-process/ppc-ubuntu:latest", + "customizations": { + "vscode": { + "extensions": [ + "ms-vscode.cpptools-extension-pack", + "ms-vscode.cmake-tools", + "ms-python.python" + ], + "settings": { + "cmake.configureOnOpen": true, + "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" + } + } + }, + "postCreateCommand": "python3 -m pip install -r requirements.txt" +} From dcdf1ea4518eb4d02793ba8303f891ed13a15433 Mon Sep 17 00:00:00 2001 From: Arseniy Obolenskiy Date: Sun, 27 Jul 2025 12:58:34 +0200 Subject: [PATCH 2/2] devcontainder docs --- docs/locale/ru/LC_MESSAGES/user_guide/ci.po | 91 ++++++++++- .../ru/LC_MESSAGES/user_guide/environment.po | 145 +++++++++++++++--- .../user_guide/environment_variables.po | 37 +++-- docs/user_guide/environment.rst | 28 ++++ 4 files changed, 260 insertions(+), 41 deletions(-) diff --git a/docs/locale/ru/LC_MESSAGES/user_guide/ci.po b/docs/locale/ru/LC_MESSAGES/user_guide/ci.po index a3ba0e476..23bf304f1 100644 --- a/docs/locale/ru/LC_MESSAGES/user_guide/ci.po +++ b/docs/locale/ru/LC_MESSAGES/user_guide/ci.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: Parallel Programming Course \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-01-25 16:54+0100\n" +"POT-Creation-Date: 2025-07-27 12:32+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: ru\n" @@ -19,7 +19,7 @@ msgstr "" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" -"Generated-By: Babel 2.16.0\n" +"Generated-By: Babel 2.17.0\n" #: ../../user_guide/ci.rst:2 msgid "Continuous Integration (CI)" @@ -32,9 +32,11 @@ msgid "" "checkout, build ans testing stages. Each integration is verified by an " "automated build and automated tests." msgstr "" -"Студенты должны пройти все проверки в конвейере CI, прежде чем" -" начнется проверка работы студентами и преподавателями. Это включает в себя успешную проверку кода, " -" а также стадии построения и тестирования. Каждая интеграция проверяется автоматизированной сборкой и автоматизированными тестами." +"Студенты должны пройти все проверки в конвейере CI, прежде чем начнется " +"проверка работы студентами и преподавателями. Это включает в себя " +"успешную проверку кода, а также стадии построения и тестирования. Каждая" +" интеграция проверяется автоматизированной сборкой и автоматизированными " +"тестами." #: ../../user_guide/ci.rst:9 msgid "CI Pipeline" @@ -47,3 +49,82 @@ msgstr "CI конвейер для данного проекта выражае #: ../../user_guide/ci.rst:13 msgid "CI Pipeline Diagram" msgstr "Схема CI конвейера" + +#: ../../user_guide/ci.rst:18 +msgid "Running ``scripts/run_tests.py``" +msgstr "" + +#: ../../user_guide/ci.rst:20 +msgid "" +"Automated tests are executed through the ``scripts/run_tests.py`` helper." +" The script requires several environment variables to be defined:" +msgstr "" + +#: ../../user_guide/ci.rst:23 +msgid "``PPC_NUM_THREADS``" +msgstr "" + +#: ../../user_guide/ci.rst:24 +msgid "" +"Number of threads to use. The value is also exported as " +"``OMP_NUM_THREADS``." +msgstr "" + +#: ../../user_guide/ci.rst:27 +msgid "``PPC_NUM_PROC``" +msgstr "" + +#: ../../user_guide/ci.rst:28 +msgid "Number of MPI processes to launch." +msgstr "" + +#: ../../user_guide/ci.rst:30 +msgid "``PPC_ASAN_RUN``" +msgstr "" + +#: ../../user_guide/ci.rst:31 +msgid "" +"Set to ``1`` when sanitizers are enabled to skip ``valgrind`` runs " +"(optional, default ``0``)." +msgstr "" + +#: ../../user_guide/ci.rst:34 +msgid "``PPC_IGNORE_TEST_TIME_LIMIT``" +msgstr "" + +#: ../../user_guide/ci.rst:35 +msgid "Set to ``1`` to disable test time limits (optional, default ``0``)." +msgstr "" + +#: ../../user_guide/ci.rst:37 +msgid "" +"The execution mode is selected with ``--running-type``. The most common " +"modes are ``threads`` for shared-memory backends and ``processes`` for " +"MPI based tests. ``performance`` mode runs performance benchmarks." +msgstr "" + +#: ../../user_guide/ci.rst:41 +msgid "Example usage:" +msgstr "" + +#: ../../user_guide/ci.rst:57 +msgid "" +"Additional MPI arguments can be supplied with ``--additional-mpi-args`` " +"when running in ``processes`` mode." +msgstr "" + +#: ../../user_guide/ci.rst:60 +msgid "" +"The ``--counts`` option allows sequential execution of tests with several" +" thread/process counts. When specified, the script will iterate over the" +" provided values, updating ``PPC_NUM_THREADS`` or ``PPC_NUM_PROC`` " +"accordingly before each run." +msgstr "" + +#: ../../user_guide/ci.rst:65 +msgid "" +"Use ``--verbose`` to print every command executed by ``run_tests.py``. " +"This can be helpful for debugging CI failures or verifying the exact " +"arguments passed to the test binaries." +msgstr "" + diff --git a/docs/locale/ru/LC_MESSAGES/user_guide/environment.po b/docs/locale/ru/LC_MESSAGES/user_guide/environment.po index cef16acba..7560743d8 100644 --- a/docs/locale/ru/LC_MESSAGES/user_guide/environment.po +++ b/docs/locale/ru/LC_MESSAGES/user_guide/environment.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: Parallel Programming Course \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-05-19 16:44+0200\n" +"POT-Creation-Date: 2025-07-27 12:55+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: ru\n" @@ -19,35 +19,131 @@ msgstr "" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" -"Generated-By: Babel 2.16.0\n" +"Generated-By: Babel 2.17.0\n" #: ../../user_guide/environment.rst:2 msgid "Set Up Your Environment" msgstr "Настройка окружения" #: ../../user_guide/environment.rst:5 +msgid "Development Container (Recommended)" +msgstr "Контейнер разработки (Рекомендуется)" + +#: ../../user_guide/environment.rst:6 +msgid "" +"The easiest way to set up your development environment is using the " +"provided ``.devcontainer`` configuration with VS Code and Docker." +msgstr "" +"Самый простой способ настроить среду разработки - использовать " +"предоставленную конфигурацию ``.devcontainer`` с VS Code и Docker." + +#: ../../user_guide/environment.rst:8 +msgid "**Prerequisites:**" +msgstr "**Требования:**" + +#: ../../user_guide/environment.rst:10 +msgid "`Visual Studio Code `_" +msgstr "`Visual Studio Code `_" + +#: ../../user_guide/environment.rst:11 +msgid "`Docker Desktop `_" +msgstr "`Docker Desktop `_" + +#: ../../user_guide/environment.rst:12 +msgid "" +"`Dev Containers extension " +"`_" +msgstr "" +"`Расширение Dev Containers " +"`_" + +#: ../../user_guide/environment.rst:14 +msgid "**Setup:**" +msgstr "**Настройка:**" + +#: ../../user_guide/environment.rst:16 +msgid "Clone the repository and open it in VS Code" +msgstr "Клонируйте репозиторий и откройте его в VS Code" + +#: ../../user_guide/environment.rst:17 +msgid "" +"When prompted, click \"Reopen in Container\" or use Command Palette: " +"``Dev Containers: Reopen in Container``" +msgstr "" +"При появлении запроса нажмите \"Reopen in Container\" или используйте " +"палитру команд: ``Dev Containers: Reopen in Container``" + +#: ../../user_guide/environment.rst:18 +msgid "" +"VS Code will automatically build the container with all dependencies pre-" +"installed" +msgstr "" +"VS Code автоматически соберет контейнер со всеми предустановленными " +"зависимостями" + +#: ../../user_guide/environment.rst:19 +msgid "The container includes:" +msgstr "Контейнер включает:" + +#: ../../user_guide/environment.rst:21 +msgid "Ubuntu environment with gcc-14, CMake, MPI, OpenMP" +msgstr "Окружение Ubuntu с gcc-14, CMake, MPI, OpenMP" + +#: ../../user_guide/environment.rst:22 +msgid "Pre-configured C++ and Python development tools" +msgstr "Предварительно настроенные инструменты разработки C++ и Python" + +#: ../../user_guide/environment.rst:23 +msgid "All project dependencies ready to use" +msgstr "Все зависимости проекта готовы к использованию" + +#: ../../user_guide/environment.rst:25 +msgid "" +"This provides a consistent development environment across all platforms " +"without manual dependency installation." +msgstr "" +"Это обеспечивает единообразную среду разработки на всех платформах без " +"ручной установки зависимостей." + +#: ../../user_guide/environment.rst:28 +msgid "Manual Setup" +msgstr "Ручная настройка" + +#: ../../user_guide/environment.rst:30 +msgid "" +"If you prefer manual setup or cannot use containers, follow the " +"instructions below." +msgstr "" +"Если вы предпочитаете ручную настройку или не можете использовать " +"контейнеры, следуйте инструкциям ниже." + +#: ../../user_guide/environment.rst:33 msgid "Build prerequisites" msgstr "Требования к сборке" -#: ../../user_guide/environment.rst:6 +#: ../../user_guide/environment.rst:34 msgid "" "**Windows**: Download and install CMake from https://cmake.org/download " "(select the Windows installer) or install using Chocolatey:" -msgstr "**Windows**: Загрузите и установите CMake с https://cmake.org/download (выберите установщик для Windows) или установите с помощью Chocolatey:" +msgstr "" +"**Windows**: Загрузите и установите CMake с https://cmake.org/download " +"(выберите установщик для Windows) или установите с помощью Chocolatey:" -#: ../../user_guide/environment.rst:12 +#: ../../user_guide/environment.rst:40 msgid "**Linux (Ubuntu/Debian)**: Install using package manager:" msgstr "**Linux (Ubuntu/Debian)**: Установите с помощью менеджера пакетов:" -#: ../../user_guide/environment.rst:19 +#: ../../user_guide/environment.rst:47 msgid "**macOS**: Install using Homebrew:" msgstr "**macOS**: Установите с помощью Homebrew:" -#: ../../user_guide/environment.rst:27 +#: ../../user_guide/environment.rst:55 msgid "Code Style Analysis" msgstr "Анализ стиля кодирования" -#: ../../user_guide/environment.rst:28 +#: ../../user_guide/environment.rst:56 msgid "" "Please follow the `Google C++ Style Guide " "`_." @@ -55,25 +151,27 @@ msgstr "" "Пожалуйста пройдите по ссылке для изучения стиля кодирования - `Google " "C++ Style Guide `_." -#: ../../user_guide/environment.rst:30 +#: ../../user_guide/environment.rst:58 msgid "" "Code style is checked using the `clang-format " "`_ tool." -msgstr "Проверка стиля кода выполняется с помощью инструмента `clang-format `_." +msgstr "" +"Проверка стиля кода выполняется с помощью инструмента `clang-format " +"`_." -#: ../../user_guide/environment.rst:33 +#: ../../user_guide/environment.rst:61 msgid "Parallel Programming Technologies" msgstr "Технологии параллельного программирования" -#: ../../user_guide/environment.rst:36 +#: ../../user_guide/environment.rst:64 msgid "``MPI``" msgstr "``MPI``" -#: ../../user_guide/environment.rst:37 +#: ../../user_guide/environment.rst:65 msgid "**Windows (MSVC)**:" msgstr "**Windows (MSVC)**:" -#: ../../user_guide/environment.rst:39 +#: ../../user_guide/environment.rst:67 msgid "" "`Installers link `_. You have to install " @@ -83,20 +181,19 @@ msgstr "" "us/download/details.aspx?id=105289>`_. Вы должны установить 2 файла - " "``msmpisdk.msi`` и ``msmpisetup.exe``." -#: ../../user_guide/environment.rst:41 -#: ../../user_guide/environment.rst:57 +#: ../../user_guide/environment.rst:69 ../../user_guide/environment.rst:85 msgid "**Linux (gcc and clang)**:" msgstr "**Linux (gcc and clang)**:" -#: ../../user_guide/environment.rst:47 +#: ../../user_guide/environment.rst:75 msgid "**MacOS (apple clang)**:" msgstr "**MacOS (apple clang)**:" -#: ../../user_guide/environment.rst:54 +#: ../../user_guide/environment.rst:82 msgid "``OpenMP``" msgstr "``OpenMP``" -#: ../../user_guide/environment.rst:55 +#: ../../user_guide/environment.rst:83 msgid "" "``OpenMP`` is included in ``gcc`` and ``msvc``, but some components " "should be installed additionally:" @@ -105,15 +202,15 @@ msgstr "" "``msvc``, но ряд компонент все равно должны быть установлены " "дополнительно:" -#: ../../user_guide/environment.rst:63 +#: ../../user_guide/environment.rst:91 msgid "**MacOS (llvm)**:" msgstr "**MacOS (llvm)**:" -#: ../../user_guide/environment.rst:71 +#: ../../user_guide/environment.rst:99 msgid "``TBB``" msgstr "``TBB``" -#: ../../user_guide/environment.rst:72 +#: ../../user_guide/environment.rst:100 msgid "" "**Windows (MSVC)**, **Linux (gcc and clang)**, **MacOS (apple clang)**: " "Build as 3rdparty in the current project." @@ -122,10 +219,10 @@ msgstr "" "Данная библиотека строится как внешняя в составе текущего проекта и не " "требует дополнительных операций." -#: ../../user_guide/environment.rst:76 +#: ../../user_guide/environment.rst:104 msgid "``std::thread``" msgstr "``std::thread``" -#: ../../user_guide/environment.rst:77 +#: ../../user_guide/environment.rst:105 msgid "``std::thread`` is included in STL libraries." msgstr "``std::thread`` включена в состав STL библиотек." diff --git a/docs/locale/ru/LC_MESSAGES/user_guide/environment_variables.po b/docs/locale/ru/LC_MESSAGES/user_guide/environment_variables.po index a192129fe..1b18ecf8f 100644 --- a/docs/locale/ru/LC_MESSAGES/user_guide/environment_variables.po +++ b/docs/locale/ru/LC_MESSAGES/user_guide/environment_variables.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: Parallel Programming Course \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-05-29 19:31+0200\n" +"POT-Creation-Date: 2025-07-27 12:32+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: ru\n" @@ -19,13 +19,13 @@ msgstr "" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" -"Generated-By: Babel 2.16.0\n" +"Generated-By: Babel 2.17.0\n" -#: ../../../../docs/user_guide/environment_variables.rst:2 +#: ../../user_guide/environment_variables.rst:2 msgid "Environment Variables" msgstr "Переменные окружения" -#: ../../../../docs/user_guide/environment_variables.rst:4 +#: ../../user_guide/environment_variables.rst:4 msgid "" "The following environment variables can be used to configure the " "project's runtime behavior:" @@ -33,15 +33,16 @@ msgstr "" "Следующие переменные окружения могут использоваться для настройки " "поведения программы во время выполнения:" -#: ../../../../docs/user_guide/environment_variables.rst:6 +#: ../../user_guide/environment_variables.rst:6 +#, fuzzy msgid "" "``PPC_NUM_PROC``: Specifies the number of processes to launch. Default: " -"``1``" +"``1`` Can be queried from C++ with ``ppc::util::GetNumProc()``." msgstr "" "``PPC_NUM_PROC``: задаёт количество запускаемых процессов. По умолчанию: " "``1``" -#: ../../../../docs/user_guide/environment_variables.rst:9 +#: ../../user_guide/environment_variables.rst:10 msgid "" "``PPC_NUM_THREADS``: Specifies the number of threads to use. Default: " "``1``" @@ -49,7 +50,7 @@ msgstr "" "``PPC_NUM_THREADS``: задаёт количество используемых потоков. По " "умолчанию: ``1``" -#: ../../../../docs/user_guide/environment_variables.rst:12 +#: ../../user_guide/environment_variables.rst:13 msgid "" "``PPC_ASAN_RUN``: Specifies that application is compiler with sanitizers." " Used by ``scripts/run_tests.py`` to skip ``valgrind`` runs. Default: " @@ -59,14 +60,26 @@ msgstr "" "Используется в ``scripts/run_tests.py`` для пропуска запусков под " "``valgrind``. По умолчанию: ``0``" -#: ../../../../docs/user_guide/environment_variables.rst:15 +#: ../../user_guide/environment_variables.rst:16 #, fuzzy msgid "" "``PPC_IGNORE_TEST_TIME_LIMIT``: Specifies that test time limits are " "ignored. Used by ``scripts/run_tests.py`` to disable time limit " "enforcement. Default: ``0``" msgstr "" -"``PPC_IGNORE_TEST_TIME_LIMIT``: указывает, что ограничения по времени выполнения тестов игнорируются. " -"Используется в ``scripts/run_tests.py`` для отключения контроля ограничений по времени. " -"По умолчанию: ``0``" +"``PPC_IGNORE_TEST_TIME_LIMIT``: указывает, что ограничения по времени " +"выполнения тестов игнорируются. Используется в ``scripts/run_tests.py`` " +"для отключения контроля ограничений по времени. По умолчанию: ``0``" + +#: ../../user_guide/environment_variables.rst:18 +msgid "" +"``PPC_TASK_MAX_TIME``: Maximum allowed execution time in seconds for " +"functional tests. Default: ``1.0``" +msgstr "" + +#: ../../user_guide/environment_variables.rst:20 +msgid "" +"``PPC_PERF_MAX_TIME``: Maximum allowed execution time in seconds for " +"performance tests. Default: ``10.0``" +msgstr "" diff --git a/docs/user_guide/environment.rst b/docs/user_guide/environment.rst index 9c85f32b6..67b5233c4 100644 --- a/docs/user_guide/environment.rst +++ b/docs/user_guide/environment.rst @@ -1,6 +1,34 @@ Set Up Your Environment ======================== +Development Container (Recommended) +------------------------------------ +The easiest way to set up your development environment is using the provided ``.devcontainer`` configuration with VS Code and Docker. + +**Prerequisites:** + +- `Visual Studio Code `_ +- `Docker Desktop `_ +- `Dev Containers extension `_ + +**Setup:** + +1. Clone the repository and open it in VS Code +2. When prompted, click "Reopen in Container" or use Command Palette: ``Dev Containers: Reopen in Container`` +3. VS Code will automatically build the container with all dependencies pre-installed +4. The container includes: + + - Ubuntu environment with gcc-14, CMake, MPI, OpenMP + - Pre-configured C++ and Python development tools + - All project dependencies ready to use + +This provides a consistent development environment across all platforms without manual dependency installation. + +Manual Setup +------------ + +If you prefer manual setup or cannot use containers, follow the instructions below. + Build prerequisites ------------------- - **Windows**: Download and install CMake from https://cmake.org/download (select the Windows installer) or install using Chocolatey: