Записи по тегу "bash" ⋆ Журнал Эмбеддед-Инженера

Автовставка истории изменений в техническую документацию на AsciiDoc

Задача

При написании технической документации является хорошим тоном включать секцию с историей изменений (т.н. Revision History). Как правило, сама документация также хранится в гите и имеет свою историю изменений, поэтому грех этим не воспользоваться, чтобы автоматизировать процесс.

Решение

Рассмотрим решение задачи на базе стандарта AsciiDoc, который в последнее время набирает всё большую популярность среди прогрессивно настроенных инженеров и причастных к их результатам деятельности тех.писателей.

Примем, что для истории ревизий нам необходима следующая информация:

дата изменения
имя автора изменения
суть изменения

Для формирования таблицы с историей ревизий используем замечательную команду git log:

$ git log --max-count=10 --no-merges --date=short --pretty=format:"| %ad | %an | %s"

| 2017-04-05 | Dmitry Murzinov | [ipxact2verilog] minor changes

| 2017-04-04 | Dmitry Murzinov | minor changes

| 2017-04-04 | Dmitry Murzinov | First scatch for verilog CSR generator

| 2017-04-03 | Dmitry Murzinov | Was added Make to build translate files (*.mo) for gettext

| 2017-04-03 | Dmitry Murzinov | Was added multilingual support to AsciiDoc Register Overview table

| 2017-04-03 | Dmitry Murzinov | First try to multilingual support

| 2017-04-03 | Dmitry Murzinov | an AsciiDoc Register Overview table now data width independent

| 2017-04-03 | Dmitry Murzinov | Was added dimension of fields for Regs Overview table

| 2017-04-03 | Dmitry Murzinov | Ability to generate an AsciiDoc Register Overview table

| 2017-04-03 | Dmitry Murzinov | Was added an example config file

— как видим на выходе отличная заготовка для asciidoc-таблицы.

Подробнее об опциях команды:

—max-count= — указываем желаемое число последних коммитов
—branches= — если интересуют только конкретные ветки (например release/production), указываем тут
—tags= — аналогично с тегами, можно задавать паттерн типа rev*.*, v?.?.? и т.п.
—no-merges — не выводить в лог слияния веток

У меня установлен гит довольно старый (v1.8), в новых версиях появилась кудо более гибкая кастомизация даты. Тонкую настойку на славянский формат даты «19.2.2015» в новом гите можно осуществить следующей командой:

1	git log -n 10 --date=format:'%d.%m.%Y' --pretty=format:"\| %cd \| %cn \| %s"

Также в зависимости от того хранится ли документация отдельно либо является частью репозитария СФ-блока будет различаться git log, возмодно потребуется указывать конкретный исходник документа или группу исходников, например:

1	git log -n 10 --pretty=format:"\| %ad \| %an \| %s" doc/src/IP-core.adoc

или:

1	git log -n 10 --pretty=format:"\| %ad \| %an \| %s" doc/src/*.adoc

Итоговый скрипт

Получившийся скрипт выглядит следующим образом:

#!/bin/bash

echo ".Revision History" > $1

echo "[cols=\"^2s,^8,^26\",options=\"header\"]" >> $1

echo "|===================================================" >> $1

echo "| Date | Author | Comments" >> $1

git log --max-count=10 --date=short --pretty=format:"| %ad | %an | %s" doc/src/*.adoc >> $1

echo "|===================================================" >> $1

Вызов скрипта:

1	./generate-revision-history.sh revhist.adoc

В сборочном .adoc-файле включаем сгенерированный файл в соответствующую секцию:

[abstract]

== История изменений документа / Revision Changes

include::revhist.adoc[leveloffset=+1]

<<<<

Также будет полезно добавить revhist.adoc в .gitignore (как файл, генерируемый автоматически); и в мейкфайл — как зависимость при сборке конечного PDF.

[opensource]: Мои скрипты для EDA/CAE/CAD

Приведенное ниже — описание к коллекции моих EDA-скриптов для работы с тулами для ASIC и FPGA

Конвертор из UCF в XDC

Конвертирует для ПЛИС Xilinx привязки ножек и стандартов из формата ucf (Xilinx ISE) в новый формат xdc (Xilinx Vivado). Использование:

1	./ucf-to-xdc.sh FILENAME.ucf

В текущей директории появится файл FILENAME.xdc.

Пример входного ucf-файла

1 2	NET "DDR_DQ[0]" LOC = "AY12" \| IOSTANDARD = SSTL15_T_DCI \| VCCAUX_IO = NORMAL \| SLEW = FAST; NET "DDR_DQ[1]" LOC = "AW12" \| IOSTANDARD = SSTL15_T_DCI \| VCCAUX_IO = NORMAL \| SLEW = FAST;

Пример сгенеренного утилитой xdc-файла

set_property PACKAGE_PIN AY12 [get_ports DDR_DQ[0]]

set_property IOSTANDARD SSTL15_T_DCI [get_ports DDR_DQ[0]]

set_property VCCAUX_IO NORMAL [get_ports DDR_DQ[0]]

set_property SLEW FAST [get_ports DDR_DQ[0]]

set_property PACKAGE_PIN AW12 [get_ports DDR_DQ[1]]

set_property IOSTANDARD SSTL15_T_DCI [get_ports DDR_DQ[1]]

set_property VCCAUX_IO NORMAL [get_ports DDR_DQ[1]]

set_property SLEW FAST [get_ports DDR_DQ[1]]

(далее…)

bash: советы и шпаргалки

Архивация в несколько потоков

Понадобилось по работе делать снапшоты несколько-GB-тных логов и нетлистов прогонов синтеза под ПЛИС, есть несоклько архиваторов использующих многопоточность/многоядерность, попробовал pbzip2, установим:

1	sudo yum install -y pbzip2.x86_64

Сама строка из мейкфайла:

1	tar -cpS syn/out/* syn/log/*.rpt $(LOG) \| pbzip2 -7 --compress --force --read -m2000 -p16 > ~/work/$(shell date +%Y%m%d%H%M%S)-$(FPGA_TARGET)-$(shell git rev-parse --abbrev-ref HEAD).tar.bz2

тут делаем tar’ом из нескольких файлов один и передаем в pbzip2, конечный файл называем текущей датой, именем проекта и текущей веткой гита, подробнее про опции pbzip2:

7 — степень компрессии 1..9(лучше,медленне), по факту — размер блока 7 = 700 КБ
force — перезаписать если файл уже существует
read — означает зачитать входной файл в ОЗУ и там разбить по процессорам
m2000 — сколько оперативки в МБ использовать. 2ГБ — это практический максимум
p16 — принудительное задание сколько ядер юзать

(далее…)