Andrey
da055c2787
Создай в postcompile CCS и Keil папку по commit исходников и UTC-времени precompile. Сохрани точные образы, manifest, SHA-256 и метаданные, сохраняя прежние выходные файлы. Опиши копирование каталогов в SETGUI и проверь разные даты, целостность и Git-метаданные.
164 lines
13 KiB
Markdown
164 lines
13 KiB
Markdown
# Подключение precompile и postcompile из templates
|
||
|
||
## Новый CCS-проект C2000: локальные версия и SCI8 BIN
|
||
|
||
Используйте обновлённую папку templates целиком. Режим `--identity` добавлен для нового проекта: Windows, Python 3.8+ в PATH и TI C2000 compiler с hex2000.exe. Git в PATH нужен для хеша коммита. Без Git либо без commit в проекте или templates используется `NOGIT000`; сборка и локальная конвертация разрешены. Это явно видно в manifest. SETGUI и доступ к серверу не требуются.
|
||
|
||
### 1. Создайте конфигурацию версии
|
||
|
||
В корне проекта CCS (рядом с `.project`) скопируйте `ccs/firmware_identity.example.json` под именем `firmware_identity.json` (UTF-8):
|
||
|
||
```json
|
||
{
|
||
"product": "MY_CONTROLLER",
|
||
"target": "TMS320F28335",
|
||
"version": [0, 1, 0]
|
||
}
|
||
```
|
||
|
||
Задайте своё изделие, настоящий контроллер и нужную версию. Для TMS320F2812 замените target. Пример версии — 0.1.0; это не номер предыдущих прошивок. Этот JSON — единственное вручную редактируемое место версии в данной схеме.
|
||
|
||
### 2. Добавьте команды в CCS
|
||
|
||
Project Properties → Build → Steps, для нужной конфигурации. Пример предполагает templates в `C:\Projects\templates`. Замените только этот путь своим; макросы CCS оставьте как есть.
|
||
|
||
Pre-build steps → Command, одной строкой:
|
||
|
||
```bat
|
||
cmd /c call "C:\Projects\templates\tools\firmware-build\ccs\precompile.bat" --identity "${PROJECT_LOC}" "${PROJECT_LOC}\firmware_identity.json" "${BuildDirectory}\generated"
|
||
```
|
||
|
||
Post-build steps → Command, одной строкой:
|
||
|
||
```bat
|
||
cmd /c call "C:\Projects\templates\tools\firmware-build\ccs\postcompile.bat" --identity "${CG_TOOL_ROOT}" "${BuildDirectory}" "${BuildArtifactFileBaseName}" "${BuildDirectory}\generated\firmware_identity.json" "${BuildDirectory}\firmware"
|
||
```
|
||
|
||
Нужны оба шага. Precompile создаёт версию, UTC-время и Git-метаданные до компиляции. Postcompile преобразует OUT в SCI8 HEX/BIN, создаёт manifest и SHA-256 для точного BIN. Он не повторяет запрос Git после компиляции. В этом режиме `firmware-release.cmd` не нужен.
|
||
|
||
`BuildArtifactFileBaseName` должен быть именем без пути; OUT должен находиться в BuildDirectory. Если проект кладёт OUT в отдельный каталог, передайте фактический каталог вторым аргументом postcompile вместо BuildDirectory.
|
||
|
||
### 3. Выполните полную сборку
|
||
|
||
Apply and Close → Clean → Build Project. Настройте шаги отдельно для Debug/Release; их generated и firmware находятся внутри своих BuildDirectory.
|
||
|
||
Результаты:
|
||
|
||
```text
|
||
Debug/
|
||
generated/
|
||
firmware_identity.h
|
||
firmware_identity.json
|
||
firmware/
|
||
MyFirmware.hex
|
||
MyFirmware_BUILDID.bin
|
||
MyFirmware_BUILDID.bin.manifest.json
|
||
MyFirmware_BUILDID.bin.sha256
|
||
HASH_YYYY-MM-DD_HH-MM-SS_UTC/
|
||
MyFirmware.hex
|
||
MyFirmware_BUILDID.bin
|
||
MyFirmware_BUILDID.bin.manifest.json
|
||
MyFirmware_BUILDID.bin.sha256
|
||
firmware_identity.json
|
||
```
|
||
|
||
Postcompile автоматически создаёт папку `HASH_YYYY-MM-DD_HH-MM-SS_UTC` для каждой сборки. HASH — первые 8 символов commit прошивки из pre-build JSON; при незакоммиченных изменениях добавляется `+`. Дата и время берутся из `built_at_utc`, в UTC. Если commit исходников неизвестен, используется build ID или NOGIT000. Например: `f5c3654e+_2026-10-08_12-30-00_UTC`. Сохраняются точные байты образа, manifest, SHA-256 и firmware_identity.json; в CCS также HEX и map. Повтор postcompile с теми же метаданными обновляет ту же папку. Файлы непосредственно в firmware сохраняются, поэтому существующие команды копирования продолжают работать.
|
||
Добавьте generated и firmware в игнорируемые Git-каталоги. Обычно вся папка Debug уже игнорируется. Полный Rebuild обязателен для выпуска. BAT сами по себе не подтверждают, что OUT собран именно с этим заголовком.
|
||
|
||
### 4. Копирование результата в каталог SETGUI
|
||
|
||
Чтобы после успешного postcompile скопировать BIN в `K:\git_project\newProject\SETGUI\..periph_28335\firmware\`, добавьте в конец существующей команды Post-build:
|
||
|
||
```bat
|
||
&& copy /Y "${BuildDirectory}\firmware\*.bin" "K:\git_project\newProject\SETGUI\..periph_28335\firmware\"
|
||
```
|
||
|
||
Для копирования BIN вместе с manifest и SHA-256 используйте полную команду ниже. Она соответствует templates в `K:\git_project\newProject\newTEMPL\templates`; при другом расположении замените путь к postcompile.bat.
|
||
|
||
```bat
|
||
cmd /c call "K:\git_project\newProject\newTEMPL\templates\tools\firmware-build\ccs\postcompile.bat" --identity "${CG_TOOL_ROOT}" "${BuildDirectory}" "${BuildArtifactFileBaseName}" "${BuildDirectory}\generated\firmware_identity.json" "${BuildDirectory}\firmware" && copy /Y "${BuildDirectory}\firmware\*.bin" "K:\git_project\newProject\SETGUI\..periph_28335\firmware\" && copy /Y "${BuildDirectory}\firmware\*.bin.manifest.json" "K:\git_project\newProject\SETGUI\..periph_28335\firmware\" && copy /Y "${BuildDirectory}\firmware\*.bin.sha256" "K:\git_project\newProject\SETGUI\..periph_28335\firmware\"
|
||
```
|
||
|
||
В поле CCS вся команда должна быть одной строкой. Папка назначения должна существовать. `&&` запускает следующую операцию только при успешном завершении предыдущей. Маски копируют все соответствующие файлы из каталога firmware, включая результаты прошлых сборок; `/Y` разрешает замену одноимённых файлов. Это локальное копирование, без публикации на сервер.
|
||
|
||
Чтобы скопировать также папки HASH_DATE вместе с их содержимым, вместо трёх команд copy используйте одну команду xcopy в конце post-build:
|
||
|
||
```bat
|
||
&& xcopy /E /I /Y "${BuildDirectory}\firmware" "K:\git_project\newProject\SETGUI\..periph_28335\firmware"
|
||
```
|
||
|
||
Она копирует весь каталог результатов, включая папки предыдущих сборок; при необходимости создаёт папку назначения. В поле CCS добавляйте её к основной команде в той же строке.
|
||
### Версия внутри устройства
|
||
|
||
Это подготовка метаданных сборки и файла. Чтобы версия присутствовала в программе и ответах устройства, подключите заголовок `firmware_identity.h` к модулю версии и обработчику запроса. Include path: `${BuildDirectory}/generated`. Для C2000 с 16-битным char нужна адаптация байтового контракта; обычный 8-битный порт нельзя считать готовым. Смотрите [PORTING.md](../../c/firmware-info/PORTING.md).
|
||
|
||
## Keil: тот же JSON, заголовок и SHA-256
|
||
|
||
Keil использует `firmware_identity.json` и режим `--identity`, как CCS. Дополнительный CMD-файл конфигурации и SETGUI для этой схемы не нужны. Требуется Python 3.8+ в PATH; Git нужен для commit. HEX создаётся штатным компилятором Keil, а BAT создаёт и проверяет manifest и SHA-256 точного HEX/BIN.
|
||
|
||
### 1. Создайте конфигурацию версии
|
||
|
||
Пример расположения:
|
||
|
||
```text
|
||
project/
|
||
firmware_identity.json
|
||
mdk/
|
||
Firmware.uvprojx
|
||
Generated/
|
||
```
|
||
|
||
Скопируйте `keil/firmware_identity.example.json` в корень project под именем `firmware_identity.json`. Исправьте product, target и version:
|
||
|
||
```json
|
||
{
|
||
"product": "MY_CONTROLLER",
|
||
"target": "STM32F407",
|
||
"version": [0, 1, 0]
|
||
}
|
||
```
|
||
|
||
### 2. Настройте Before/After Build
|
||
|
||
В Options for Target → Output включите Create HEX File. Затем откройте User и включите выполнение команд Before Build/Rebuild и After Build/Rebuild. Для обеих команд задайте Stop on Exit Code `>=1`, чтобы ошибка скрипта останавливала сборку. Пример предполагает templates в `C:\Projects\templates`; замените этот путь своим.
|
||
|
||
Before Build/Rebuild, одной строкой:
|
||
|
||
```bat
|
||
cmd /c call "C:\Projects\templates\tools\firmware-build\keil\precompile.bat" --identity "$P.." "$P..\firmware_identity.json" "$PGenerated"
|
||
```
|
||
|
||
After Build/Rebuild, одной строкой:
|
||
|
||
```bat
|
||
cmd /c call "C:\Projects\templates\tools\firmware-build\keil\postcompile.bat" --identity "#H" "$PGenerated\firmware_identity.json"
|
||
```
|
||
|
||
В Keil `$P` обозначает каталог проекта с завершающим разделителем, а `#H` — полный путь к выходному HEX. Официальное описание макросов: [Keil User commands](https://www.keil.com/support/man/docs/uv4cl/uv4cl_dg_user.htm). Макросы раскрываются в IDE; при ручном запуске BAT замените их реальными путями.
|
||
|
||
В примере файл uvprojx находится в mdk, поэтому `$P..` указывает на корень исходников. Если JSON и uvprojx находятся в одном каталоге, используйте `"$P."` для repository и `"$Pfirmware_identity.json"` для config; третий аргумент Generated сохраните.
|
||
|
||
Добавьте Generated в include path и подключите `firmware_identity.h` в модуле версии прошивки. Для параллельных или разных target задавайте отдельные Generated и согласуйте путь во второй команде. Перенос версии в ответ устройства требует подключения модуля и обработчика, как описано в [PORTING.md](../../c/firmware-info/PORTING.md).
|
||
|
||
### 3. Выполните Rebuild
|
||
|
||
Перед выпуском измените только исходный firmware_identity.json и выполните Rebuild. Precompile создаст заголовок и метаданные в Generated. Postcompile создаст рядом с HEX:
|
||
|
||
```text
|
||
Firmware.hex
|
||
Firmware.hex.manifest.json
|
||
Firmware.hex.sha256
|
||
firmware/
|
||
HASH_YYYY-MM-DD_HH-MM-SS_UTC/
|
||
Firmware.hex
|
||
Firmware.hex.manifest.json
|
||
Firmware.hex.sha256
|
||
firmware_identity.json
|
||
```
|
||
|
||
Папка HASH_DATE создаётся в firmware рядом с исходным HEX/BIN. Для неё используются commit и UTC-время из precompile, как в CCS. При успехе Console содержит строки `[firmware-build] Folder`, `Image`, `Manifest`, `SHA-256`. Для готового BIN вместо `#H` передайте его фактический путь; конвертацию AXF в BIN нужно выполнить до postcompile. Сгенерированные файлы исключите через .gitignore.
|
||
|
||
## Совместимость со старыми проектами
|
||
|
||
Вызовы BAT без `--identity` сохранены для уже настроенных проектов: прежний precompile генерирует только build ID, прежний postcompile запускает SETGUI preflight по release-конфигурации. Эта отдельная схема описана в [инструкции публикатора](../firmware-publish/README.md). Для новых CCS и Keil используйте приведённые выше команды с `--identity`.
|