Это руководство описывает, как настроить полноценную среду разработки CubicLauncher, внутреннюю организацию репозитория и ожидаемый процесс работы над кодом.
Требованияредактировать
| Инструмент | Версия / примечания |
|---|---|
| Git | Любая современная версия |
| Bun | Для установки зависимостей и запуска скриптов проекта |
| Node.js | Актуальная LTS-версия (резервный вариант для Bun) |
| Rust | >= 1.85, с поддержкой редакции 2024, а также Cargo, rustfmt и Clippy |
| Tauri v2 | Системные зависимости для вашей платформы (официальное руководство) |
Tauri CLI входит в зависимости проекта и устанавливается автоматически вместе с bun install; отдельно устанавливать его не нужно.
Локальная средаредактировать
git clone https://github.com/CubicLauncherDevs/CubicLauncher.git
cd CubicLauncher
bun install --frozen-lockfile
bun run tauri devbun run tauri dev параллельно запускает настольное приложение и сервер разработки фронтенда с горячей перезагрузкой. Чтобы работать только с интерфейсом, bun run dev запускает один Vite; учитывайте, что функции, зависящие от бэкенда (инстансы, загрузки, аутентификация), в этом режиме будут недоступны.
Среда Nixредактировать
В NixOS или при установленном Nix flake репозитория включает devShell со всеми необходимыми зависимостями (Bun, Rust, cargo-tauri, GTK3, WebKitGTK, GStreamer и другие):
nix develop
bun install --frozen-lockfile
bun run tauri devПодробнее об упаковке и устранении неполадок см. в руководстве по Nix.
Основные командыредактировать
Все команды выполняются из корня репозитория.
| Команда | Описание |
|---|---|
bun run tauri dev | Запускает настольное приложение в режиме разработки. |
bun run dev | Запускает сервер фронтенда Vite. |
bun run tauri build | Собирает и упаковывает приложение для текущей платформы. |
bun run build | Создаёт production-сборку фронтенда. |
bun run lint | Запускает ESLint для фронтенда. |
bun run check | Проверяет типы и диагностику Svelte. |
bun run test:frontend | Запускает тесты фронтенда с помощью Bun. |
bun run test:rust | Запускает тесты и doctests рабочего пространства Rust. |
bun run test:all | Запускает наборы тестов фронтенда и Rust. |
cargo fmt --all --check | Проверяет форматирование кода Rust. |
cargo clippy --workspace -- -D warnings | Запускает статический анализ рабочего пространства Rust. |
Если вы хотите только проверить изменения в Rust без упаковки установщиков, cargo build в каталоге src-tauri/ создаёт отладочный бинарный файл гораздо быстрее, чем bun run tauri build.
Структура репозиторияредактировать
src/ # Frontend interface, state and services
src-tauri/ # Tauri application, commands and native services
src/tests/ # Unit tests for the application backend
crates/ # Internal Rust workspace libraries
<crate>/src/tests/ # Unit tests for each library with their own suites
tests/frontend/ # Frontend tests grouped by area
static/ # Frontend static assets
dist/ # Packaging files for distributions
.github/ # Continuous integration and release workflowsБэкенд организован как рабочее пространство внутренних крейтов, которые инкапсулируют независимые домены (инстансы, загрузки, управление Java, аутентификация и т. д.). Это позволяет тестировать каждый сервис изолированно и переиспользовать его в разных бинарниках.
Тестированиередактировать
Проект поддерживает отдельные наборы тестов для фронтенда и бэкенда:
- Фронтенд (
tests/frontend/): модульные и интеграционные тесты, выполняемые с Bun. Руководство по тестированию описывает требования к Chromium для браузерных тестов, измерения производительности и сценарии ручной проверки. - Rust (
src-tauri/src/tests/иcrates/<crate>/src/tests/): модульные тесты и doctests для каждого крейта, выполняемые через Cargo.
Перед открытием pull request запустите bun run test:all, чтобы проверить оба набора.
Рекомендуемый процессредактировать
- Форк и ветка: сделайте форк репозитория и создайте описательную ветку от
develop:bashgit checkout develop git pull git checkout -b feat/name-of-the-change - Атомарные коммиты: делайте изменения небольшими и целенаправленными, а сообщения коммитов — описывающими суть изменения.
- Локальная проверка: перед открытием PR убедитесь, что все проверки проходят:bash
bun run lint bun run check bun run test:all cargo fmt --all --check cargo clippy --workspace -- -D warnings - Pull request: откройте PR в
develop, чётко описав решаемую проблему и, если применимо, сославшись на связанный issue. - Ревью: сопровождающий рассмотрит изменение. Отвечайте на комментарии новыми коммитами в той же ветке; избегайте force-push, если об этом не попросят.
Соглашения о кодередактировать
- Rust: форматирование применяется через
rustfmt, статический анализ — через Clippy; оба запускаются в CI с-D warnings, поэтому любое предупреждение блокирует интеграцию. - TypeScript / Svelte: фронтенд следует правилам ESLint и конфигурации
svelte-checkрепозитория. - Комментарии и именование: идентификаторы и комментарии рекомендуется писать на английском языке, следуя стилю, уже принятому в кодовой базе.
Проверки форматирования, линтов и тестов выполняются в непрерывной интеграции GitHub Actions. PR не перейдёт к полному ревью, пока все проверки не станут зелёными.
Ресурсы для участниковредактировать
- CONTRIBUTING.md — соглашения проекта и процесс участия.
- TESTING.md — руководство по тестированию, требования к Chromium и ручная проверка.
- Кодекс поведения — правила участия в сообществе.
- Репозиторий переводов — инструкции по интернационализации.
- Статус сервисов — доступность API проекта.
- Статус зависимостей Rust — отчёт о зависимостях бэкенда.
Устранение неполадокредактировать
bun run tauri dev не запускаетсяредактировать
Убедитесь, что вы установили системные зависимости Tauri v2 для вашей платформы. В Linux это обычно пакеты разработки WebKitGTK и GTK3; в Windows — Visual Studio Build Tools и WebView2 Runtime.
Ошибки компиляции Rust после обновления инструментовредактировать
Убедитесь, что вы используете стабильный канал с поддержкой редакции 2024, и обновите зависимости lockfile:
rustup update stable
bun install --frozen-lockfileИнтерфейс не показывает данные бэкендаредактировать
Если вы запустили только фронтенд с помощью bun run dev, функции, зависящие от Tauri (IPC), недоступны. Запустите приложение целиком с bun run tauri dev.