Настройка окружения и сборка

Содержание

  1. Настройка окружения и сборка
    1. Введение
    2. Предварительные требования
      1. ОС
      2. Инструменты и программное обеспечение
      3. Клонирование репозитория
    3. Настройка окружения
    4. Автоматический процесс сборки
    5. Сборка вручную
      1. Настройка дополнительных зависимостей
      2. Использование бинарников SteamworksPy
      3. Сборка SteamworksPy из исходников
      4. Оптимизация текстур (todds)
      5. Запуск RimSort из исходников
      6. Изоляция данных в dev-режиме
      7. Упаковка RimSort

Введение

RimSort написан на Python с использованием модуля PySide6 и ряда других. Некоторые модули требуют особого внимания при сборке. Компиляция и упаковка выполняются с помощью Nuitka.

Предварительные требования

ОС

RimSort в настоящее время работает на Windows, MacOS и Linux, однако сборки мы создаём только для Ubuntu. Приложение может работать и на других дистрибутивах Linux, но Ubuntu — наша базовая платформа.

Ваша ОС должна поддерживаться PySide6. Например, для сборки релизов мы используем следующие GitHub runner’ы:

  • Linux:
    • ubuntu-22.04
    • ubuntu-24.04
  • Сборки macOS:
    • macos-latest (arm)
  • Windows:
    • windows-latest

Инструменты и программное обеспечение

Обязательно:

  • git
  • Python 3.14 (можно установить через uv, если хотите)
  • uv
  • just — запуск задач разработки

Для проверок качества кода (используются just check и CI):

  • Node.js / npx — нужен для проверки копирования кода JSCPD (just jscpd)
  • shfmt — форматировщик shell-скриптов (just shfmt)

Линтеры Python (ruff, mypy) устанавливаются автоматически командой uv sync — вручную ничего настраивать не нужно.

Клонирование репозитория

RimSort использует сабмодули, размещённые в других репозиториях, которые необходимо клонировать.

  • steamfiles: используется для разбора информации acf/appinfo/manifest из Steam-клиента
  • SteamworksPy: используется для взаимодействия с локальным Steam-клиентом
    • SteamworksPy — это Python-модуль, предназначенный для прямого взаимодействия со Steamworks API
    • Это позволяет инициировать некоторые операции с локальным Steam-клиентом через Steamworks API на Python (например, подписку/отписку от модов Steam через RimSort)

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

git clone --recurse-submodules -j8 https://github.com/RimSort/RimSort

Если нужно обновить сабмодули или вы забыли клонировать с --recurse-submodules, выполните:

git submodule update --init --recursive

Настройка окружения

RimSort использует менеджер пакетов и проектов uv.

Проще всего настроить всё (сабмодули, venv, зависимости dev + build) так:

just dev-setup

Эта команда запускает uv sync --locked --dev --group build, который устанавливает все зависимости времени выполнения, разработки и сборки (включая линтеры ruff и mypy).

После настройки установите общие git-хуки, чтобы just check запускался автоматически перед каждым коммитом:

just install-hooks

Если вы предпочитаете сделать это вручную:

uv sync --dev            # устанавливает зависимости времени выполнения + разработки (линтеры, инструменты тестирования)
uv sync --group build    # дополнительно устанавливает зависимости сборки (nuitka и т. д.)

Автоматический процесс сборки

  • Для (в значительной степени автоматизированной) сборки RimSort запустите предоставленный скрипт:
    • Выполните uv run python distribute.py
      • Это соберёт RimSort для вашей платформы и выдаст сборку для вашей платформы (включая все требования и сабмодули)
      • Дополнительные опции, например отключение отдельных шагов, см. в uv run python distribute.py --help

Сборка вручную

Убедитесь, что зависимости сборки установлены, выполнив uv sync --group build.

Настройка дополнительных зависимостей

RimSort использует Python и зависит от нескольких Python-модулей. Большинство зависимостей можно установить/просмотреть через pyproject.toml. Они были бы установлены на предыдущем шаге настройки окружения. Однако зависимость SteamworksPy — особый случай, требующий специальной обработки.

См. соответствующие разделы ниже о том, как их настроить. В качестве альтернативы используйте distribute.py, чтобы сделать это автоматически. По умолчанию скрипт собирает RimSort, но его можно настроить на включение/отключение различных шагов, включая сборку. Подробнее см. uv run python distribute.py --help.

  • Пользователям Mac следует также помнить, что у Apple есть собственная защита времени выполнения — Gatekeeper
    • Это может вызвать проблемы при запуске RimSort (или исполняемых зависимых библиотек)!
    • Эту проблему можно обойти, добавив файлы в белый список вручную с помощью xattr:
      • xattr -d com.apple.quarantine /path/to/RimSort.app
      • xattr -d com.apple.quarantine /path/to/libsteam_api.dylib
    • Замените /path/to/ фактическим путём, по которому находится файл/папка, например:
      • xattr -d com.apple.quarantine /Users/John/Downloads/RimSort.app

Использование бинарников SteamworksPy

Чтобы RimSort действительно ИСПОЛЬЗОВАЛ модуль SteamworksPy, нужна скомпилированная библиотека для вашей платформы, а также бинарники из steamworks SDK в корне проекта RimSort — вместе с Python-модулем сабмодуля: submodules/SteamworksPy/library.

  • Мейнтейнеры репозитория предоставляют предварительно собранные бинарники библиотеки SteamworksPy, а также распространяемые файлы steamworks-sdk в репозитории и в соответствующих релизах для каждой платформы.
  • На Linux скопируйте SteamworksPy_*.so (где * — ваша архитектура CPU) в SteamworksPy.so
  • На macOS скопируйте SteamworksPy_*.dylib (где * — ваша архитектура CPU) в SteamworksPy.dylib

Сборка SteamworksPy из исходников

На момент написания модуль SteamworksPy можно собрать только с Python 11, в отличие от самого RimSort. Возможно, потребуется окружение Python, отличное от того, что вы используете для RimSort.

  • Модуль можно настроить следующими командами:

    • cd SteamworksPy
    • pip install -r requirements.txt

Это ОПЦИОНАЛЬНЫЙ шаг. Делать это НЕ ОБЯЗАТЕЛЬНО — в репозитории и в релизах для каждой платформы уже есть готовые бинарники. Не отправляйте коммит/PR с обновлением этих бинарников без согласия мейнтейнера — иначе они не будут одобрены.

Справочник: SteamworksPy

  • На Linux нужен g++. На Ubuntu у меня всё заработало «из коробки».
  • На macOS нужны инструменты командной строки Xcode. Затем можно компилировать напрямую скриптом (без полной установки Xcode):
  • На Windows нужно установить Visual Studio & Build Tools for Visual Studio:
    • MSVC
      • При запуске скачанного исполняемого файла обновится и запустится установщик Visual Studio. Чтобы установить только инструменты, необходимые для разработки на C++, выберите рабочую нагрузку «Разработка классических приложений на C++». Кроме того, можно установить VS Community 2022 со стандартным набором.

Выполните: python -c "from distribute import build_steamworkspy; build_steamworkspy()"

Оптимизация текстур (todds)

  • RimSort использует todds как зависимость для оптимизации текстур. Он поставляется с RimSort и сохраняется в архивы бинарных релизов. Если вы собираете/запускаете из исходников, разместите бинарник todds по пути ./todds/todds (для Linux/Mac) или .\todds\todds.exe (для Windows)

Запуск RimSort из исходников

  1. Клонируйте этот репозиторий в локальную папку с сабмодулями.
  2. Убедитесь, что выполнены все шаги предварительных требований выше.
  3. Из корня проекта выполните uv run python -m app

Изоляция данных в dev-режиме

RimSort поддерживает dev-режим, который перенаправляет все пользовательские данные (настройки, логи, базы данных, списки модов, темы, резервные копии) в подкаталог dev/ корня репозитория вместо стандартного каталога данных приложения вашей платформы. Это предотвращает повреждение рабочей конфигурации RimSort при разработке.

Чтобы включить dev-режим, передайте флаг --dev:

uv run python -m app --dev

Что меняется в dev-режиме:

  • Настройки хранятся в dev/data/settings.json
  • Логи записываются в dev/logs/
  • Базы данных, списки модов и резервные копии находятся в dev/data/
  • По умолчанию включён журнал отладки (debug)
  • В заголовке окна выводится суффикс [DEV]

Переопределения через переменные окружения:

ПеременнаяЗначенияЭффект
RIMSORT_DEV1, trueПринудительно включить dev-режим (эквивалентно --dev)
RIMSORT_DEV0, falseПринудительно отключить dev-режим (переопределяет --dev)
RIMSORT_DEV_DIRабсолютный путьПереопределяет корень dev-данных (только когда dev-режим активен)

Чтобы использовать собственный каталог dev-данных:

RIMSORT_DEV_DIR=/tmp/rimsort-test uv run python -m app --dev

Или только через переменные окружения:

RIMSORT_DEV=1 RIMSORT_DEV_DIR=/tmp/rimsort-test uv run python -m app

Каталог dev/ находится в .gitignore и не будет коммититься.

Упаковка RimSort

Упаковка распространения двоичного файла RimSort полностью автоматизирована скриптом distribute.py, который инициализирует сабмодули, (опционально) собирает библиотеку SteamworksPy, загружает последнюю версию todds и компилирует приложение с помощью Nuitka. Из корня проекта выполните:

uv run python distribute.py

Дополнительные опции (пропуск шагов, указание собственного источника Steamworks SDK, включение dev-режима и т. д.), см.:

uv run python distribute.py --help

Если вам нужно работать с Nuitka напрямую (например, для локальной итерации), учтите, что freeze_application() в distribute.py сначала добавляет сабмодуль SteamworksPy в PYTHONPATH, а затем компилирует пакет app/. Для реальных сборок предпочитайте скрипт distribute.py, а не запуск Nuitka вручную.