Xbuild MCU

Xbuild MCU — это расширение для VSCode, превращающее его в IDE для разработки на STM32. Это современная, легковесная альтернатива STM32CubeIDE, основанная на системе сборки Xmake.

Расширение автоматизирует рутину: создает структуру проекта, импортирует код из CubeMX, настраивает сборку через GCC и прошивку через JLink, а также интегрирует отладку.

✨ Возможности

• 🚀 Быстрый старт: Генерация структуры проекта из готовых шаблонов.
• ⚙️ Интеграция с CubeMX: Импорт системных файлов и конфигурации.
• 🔧 GUI Конфигурация: Редактирование xmake.lua через удобный интерфейс VSCode.
• 🎯 Пресеты MCU: Готовые настройки для STM32F1, F4, H7 и других серий.
• ⚡ Сборка и Прошивка: Команды Build/Rebuild/Flash прямо в VSCode.
• 🐞 Отладка: Автоматическая генерация launch.json для Cortex-Debug.
• 📚 Doxygen: Генерация документации одной командой.

📋 Требования

Перед началом работы убедитесь, что установлены следующие инструменты:

📥 Установка

1. Откройте VSCode.
2. Перейдите в раздел Extensions (Ctrl+Shift+X).
3. Введите в поиске Xbuild MCU.
4. Нажмите Install.

🏃 Быстрый старт

1. Создание проекта

Откройте пустую папку в VSCode.

Открыть расширение -> Project Configuration -> Create xmake.lua

Если добавлены шаблоны, то используйте команду палитры (Ctrl+Shift+P) -> Xmake: Apply Template либо интерфейс расширения, чтобы создать структуру папок. Обратите внимание, что шаблоны обязательно должны быть внутри папки templates в корне проекта.

2. Импорт из CubeMX (если есть проект)

Если вы сгенерировали код в STM32CubeMX:

1. Выполните команду Xmake: Import from CubeMX.
2. Укажите путь к папке проекта CubeMX.
3. Расширение скопирует startup, linker script и драйверы.

3. Настройка проекта

В Project Configuration настройте:

• MCU Series & Core: Например, STM32F103xB и cortex-m3.
• Paths: Пути к JLink и ARM GCC.
• Sources/Includes: Управляйте файлами проекта через список.

Нажмите Save Configuration. Это обновит xmake.lua.

4. Сборка и прошивка

• Выберите режим сборки (настройки оптимизации можно найти в Project Configuration).
• Нажмите Build для сборки в выбранном режиме, либо вызовите Xmake: Build Debug / Xmake: Build Release.
• Нажмите Flash via JLink (Ctrl+Alt+F) для прошивки.

📁 Структура проекта

Расширение использует (и рекомендует) следующую структуру:

my_project/
├── xmake.lua           # Движок сборки (generic-шаблон расширения)
├── .lua/
│   ├── config.json     # Общие настройки проекта (GUI-панель)
│   ├── targets/        # По одному JSON на цель сборки
│   │   └── firmware.json
│   └── tasks/          # Задачи xmake (flash/docs/cubemx/template + свои)
├── app/                # Ваш прикладной код
├── board/              # Инициализация платы и периферии
├── Core/               # Startup файлы и системный код (из CubeMX)
│   ├── startup_*.s
│   ├── Inc/
│   │   └── stm32_assert.h
│   └── Src/
│       ├── syscalls.c
│       └── system_*.c
├── Drivers/            # HAL/CMSIS библиотеки
├── *.ld                # Linker script
├── .vscode/
│   └── launch.json     # (Автогенерация) Настройки отладки
└── templates/          # (Опционально) Шаблоны для разных MCU

🎯 Мультисборка (targets)

Один репозиторий может собирать несколько прошивок (bootloader + application, разные ревизии платы, master/slave узлы). Каждая цель — отдельный JSON-файл в .lua/targets/, аддитивный поверх общих настроек из .lua/config.json:

// .lua/targets/bootloader.json
{
    "name": "MyDevice-Bootloader",   // имя выходного файла
    "defines":     ["ROLE_BOOTLOADER"],   // ДОБАВЛЯЮТСЯ к общим
    "sources":     ["boot/*.cpp"],
    "includedirs": ["boot"]
}

• Общие поля (mcu_core, ld_script, arm_gcc_path, ...) наследуются из config.json; defines/includedirs/sources дополняют общие списки, скалярные поля переопределяют.
• postbuild у цели переопределяет общий. Используйте токены {target}, {bin}, {elf} — они подставляются с реальными путями текущей сборки, поэтому одна строка в конфиге работает и в debug, и в release.

⚠️ Важно: идентификатор цели — это имя файла без расширения (bootloader.json → цель bootloader). Поле name задаёт только имя артефакта. Передача имени артефакта в xmake — тихий no-op: команда «успешно» завершается и ничего не собирает. Расширение всегда адресует цели по имени файла.

Выбор активной цели: статус-бар, боковая панель или Xmake: Select Build Target (Ctrl+Alt+T). Сборка, пересборка, очистка и прошивка действуют только на выбранную цель. Новая цель добавляется командой Xmake: Add Build Target.

Обратная совместимость: если .lua/targets/ отсутствует, проект собирается как одна цель firmware из config.json — старые проекты работают без изменений.

🛠 Свои задачи (tasks)

Любая задача, объявленная в .lua/tasks/*.lua и не входящая в стандартный набор, автоматически попадает в подкатегорию Project Tasks панели «Actions» (обновляется без перезагрузки окна). Например audit.lua:

task("audit")
    set_menu {
        options = { {nil, "target", "kv", nil, "target whose artifact to audit"} }
    }

Если задача объявляет опцию target, расширение запускает её с --target=<выбранная цель>. Задача без такой опции запускается как есть — xmake отклоняет незаявленные опции. Запуск из палитры: Xmake: Run Project Task.

⚙️ Конфигурация (GUI)

Расширение предоставляет графический интерфейс для редактирования xmake.lua без необходимости вручную править Lua-код.

Основные поля:

Пресеты MCU

Расширение содержит готовые пресеты:

Сброс к стандартным путям

Кнопка Reset to STM32F103 Defaults устанавливает типичные пути для проекта Blue Pill:

Defines:     USE_FULL_LL_DRIVER
Includes:    app, board, board/peripherals, Core/Inc, Drivers/...
Sources:     app/*.cpp, board/*.cpp, Core/Src/*.c, Drivers/...

⚙️ Настройка шаблонов (Templates)

Расширение позволяет управлять Git-сабмодулями. Вы можете подключать/удалять свои репозитории с шаблонами кода.

1. Глобальные настройки

Откройте настройки пользователя: Ctrl+Shift+P → "Preferences: Open User Settings (JSON)".

Добавьте секцию xmake.submoduleRepos, указав свои репозитории:

{
    "xmake.submoduleRepos": [
        {
            "name": "templates",
            "url": "https://github.com/USERNAME/stm32-templates.git",
            "description": "My MCU Project Templates",
            "path": "templates"
        },
        {
            "name": "mcu_libs",
            "url": "https://github.com/USERNAME/stm32-libs.git",
            "description": "My MCU Libraries Collection"
        }
    ]
}

2. Проектные настройки

Если вы хотите переопределить список сабмодулей для конкретного проекта, создайте файл .vscode/settings.json в папке проекта с аналогичной структурой.

🛠 Команды и задачи

Все команды доступны через палитру (Ctrl+Shift+P) или боковую панель:

🐞 Отладка

Расширение автоматически генерирует .vscode/launch.json для работы с плагином Cortex-Debug. Для отладки:

1. Установите расширение Cortex-Debug.
2. Соберите проект.
3. Перейдите во вкладку "Run and Debug" и выберите конфигурацию "JLink Debug".

Создание своих шаблонов (на примере STM32F103)

Структура репозитория шаблонов:

templates/
├── stm32f1/
│   ├── template.lua          # Метаданные
│   ├── app/
│   │   ├── app_main.cpp
│   │   └── app_main.hpp
│   └── board/
│       ├── board.cpp
│       ├── board.hpp
│       ├── board_config.hpp
│       └── pin_config.hpp
├── stm32f4/
│   └── ...
└── README.md

template.lua:

return {
    name = "stm32f1",
    description = "STM32F1xx BluePill template",
    dirs = {
        "app",
        "board/peripherals",
        "Core/Inc",
        "Core/Src",
        "Drivers",
        ".vscode"
    },
    variables = {
        MCU_SERIES = "STM32F103xB",
        MCU_CORE = "cortex-m3",
        MCU_DEVICE = "STM32F103C8"
    }
}

🏗 Разработка и сборка расширения

Если вы хотите модифицировать расширение или собрать его из исходников:

Требования для разработки:

• Node.js JavaScript runtime (v16+)
• npm Package manager
• vsce VSCode Extension Manager (npm install -g @vscode/vsce)

Сборка:

# Установка зависимостей
npm install

# Компиляция (режим разработки)
npm run compile

# Упаковка в .vsix
vsce package

📜 Лицензия

Этот проект распространяется под лицензией MIT. См. файл LICENSE для подробностей.

В проекте используется система сборки Xmake, распространяемая под лицензией Apache 2.0.