5. Для разработчика
5.1. Cборка программы из исходников
Программа имеет 2 режима сборки ZCAD и ZCADELECTROTECH, в первом только базовые CAD функции, во втором плюсом чуток электрической специфики. Советую пробовать собрать ZCADELECTROTECH, т.к. я его сам всегда использую, соответственно он более стабилен.
Простая компиляция исходников даст вам только файл zcad.exe, но для для работы нужны некоторые другие файлы, без которых программа не работает (не говоря о allgeneratedfiles.inc, zcadversion.inc и buildmode.inc без которых даже не скомпилируется)
Для автоматизации процесса сборки был написан скрипт на основе системы сборки make. Опишу его использование применительно к тридцати двух битным Lazarus2.2 и fpc3.2.2 под управлением ОС Windows
Итак:
5.1.1. Установка Lazarus
Устанавливаем последний релизный Lazarus (2.2 на момент написания текста). Гарантированно ZCAD компилится в транковом Lazarus транковом fpc, с релизами бывают нюансы, но они решаемы.
Запускаем, проверяем работоспособность Lazarus - собираем тестовый пустой проект. тут проблем быть не должно.
Ищем идущую в комплекте fpc утилиту make, она скорее всего лежит тут lazarus\fpc\3.2.2\bin\i386-win32\make.exe но, мало ли. В дальнейшем я считаю что Lazarus установлен на диск C, и путь для запуска make соответственно C:\lazarus\fpc\3.2.2\bin\i386-win32\make.exe если что - уточнить по месту)).
Также еще понадобятся такие пути:
-
путь к Lazarus C:\lazarus
-
путь к первичному файлу настроек Lazarus, по умолчанию он C:\Users\<ИМЯПОЛЬЗОВАТЕЛЯ>\AppData\Local\lazarus
Если имя пользователя у вас на кириллице, примите мои поздравления! Требуются дополнительные действия, пользователи с нормальными именами спокойно переходят к пункту 2.
Кириллица в путях не поддерживается утилитой make, или я с этим не разобрался. Придется "перенастроить" Lazarus чтоб настройки хранились по 'нормальным' путям. Для этого в папке C:\lazarus создаем файл runlazarus.bat следующего содержания:
startlazarus.exe --pcp=C:\lazarus\mylazcfg
и далее всегда используем его для запуска Lazarus IDE, все что написано ниже вам следует отредактировать из расчета что путь к настройкам Lazarus будет C:\lazarus\mylazcfg
5.1.2. Получение ZCAD
Клонируем исходники зкада (или скачиваем архивом, но это плохо, лучше клонировать git ом). Некоторые части исходников оформлены субмодулями git , поэтому:
| субмодули git используемые ZCAD нужно инициализировать и обновить. |
По описанным выше причинам путь до папки zcad не должен содержать не латинские символы Тут будет много файлов\папок, но основные:
-
zcad\cad_source - папка с исходниками зкад
-
zcad\environment - папка с файлами окружения программы и исходник небольшой программы typeexporter настраивающей исходники зкад для компиляции
-
zcad\Makefile - файл с скриптами установки
-
zcad\cad - данной папки изначально нет, будет создана в пункте 4 и содержит скомпилированный дистрибутив zcad со всеми нужными файлами
5.1.3. Установка пакетов от которых зависит ZCAD
Для облегчения я приложил пакеты от которых зависит ZCAD в дистрибутив исходников (за исключением идущих в составе Lazarus). Открываем командную строку в папке zcad, там где лежит файл Makefile
Нужно установить в Lazarus пакеты требуемые для компиляции ZCAD, данный пункт выполняется только один раз, для свеже установленного Lazarus, если пакеты установлены, пропускаем данный пункт (но если что, то повторное выполнение ничего страшного не несет). Выполняем:
C:\lazarus\fpc\3.2.2\bin\i386-win32\make installpkgstolaz LP=C:\lazarus PCP=C:\Users\<ИМЯПОЛЬЗОВАТЕЛЯ>\AppData\Local\lazarus
installpkgstolaz это пропишет в конфигах Lazarus требуемые пакеты из zcad\cad_source\other и zcad\cad_source\components и пересобирет Lazarus. По неясным причинам пересборка в данном пункте иногда завершается ошибкой, но ничего страшного, просто идем дальше, Lazarus докомпилирует все нужное в 4.
5.1.4. Компиляция ZCAD
Собственно запускаем компиляцию зкад, запустив следующее:
[.shell]C:\lazarus\fpc\3.2.2\bin\i386-win32\make cleanzcadelectrotech LP=C:\lazarus PCP=C:\Users\<ИМЯПОЛЬЗОВАТЕЛЯ>\AppData\Local\lazarus#
cleanzcadelectrotech - данная цель выполнит сборку программы в режиме ZCADELECTROTECH, замените на cleanzcad - если желаете режим ZCAD
Скрипт выполнит следующее:
-
СОТРЕТ папки zcad\cad и zcad\cad_source\autogenerated если они присутствует СО ВСЕМ ИХ СОДЕРЖИМЫМ ничего не спрашивая
-
создаст папки zcad\cad и zcad\cad_source\autogenerated
-
скопирует нужные для работы файлы из zcad\environment\runtimefiles в zcad\cad
-
создаст файл zcad\cad_source\zcadversion.inc
-
создаст файл zcad\cad_source\autogenerated\buildmode.inc
-
скомпилирует zcad\cad_source\cad_source\utils\typeexporter.lpi и запустит его с нужными параметрами, typeexporter в свою очередь наполнит zcad\cad_source\autogenerated в том числе создаст zcad\cad_source\autogenerated\allgeneratedfiles.inc (только после этого шага зкад может быть собран)
-
скомпилирует ZCAD
Если все прошло нормально, имеем наполненную как надо папку zcad\cad, в том числе свежесозданный запускаемый бинарник zcad\cad\bin\i386-win32\zcad.exe В дальнейшем можно просто открыть в Lazarus файл zcad\cad_source\zcad.lpi и смотреть-собирать исходники как обычно в IDE
| Lazarus, FPC и ZCAD развивающиеся проекты, информация устаревает и бывают нюансы. В частности на данный момент из-за бага FPC https://gitlab.com/freepascal.org/fpc/source/-/issues/39387 в IDE работает только полная пересборка зкада, т.е. в Lazarus если просто нажать F9 зкад не соберется с вылетом компилятора, при любых изменениях надо всегда выполнять полную пересборку shift-F9 |
5.2. Локализация программы
Для локализации ZCAD используется система интернационализации на основе Gettext и *.po файлов встроенная в Lazarus. Локализации подлежат как тексты прописанные в исходниках программы, так и заданные в файлах загружаемых во время работы программы - например файл zcad\menu\menuscontent.xml содержит наполнение палитр программы, его содержимое неизвестно в момент компиляции программы, он будет прочитан только при запуске. Обычный подход предполагает разные копии загружаемых в рантайм файлов для каждой локализации. Но в ZCAD принят несколько другой подход - перевод содержимого данных файлов в момент их загрузки.
Прежде всего стоит заметить, как описано в (Структура директорий) файлы локализаций используемые программой лежат в папке cad/languages, данная папка создается в процессе (Cборка программы из исходников) в нее копируются файлы из соответствующих мест environment. Поэтому работа с локализацией осуществляется в cad/languages, но для коммита файлы нужно скопировать в папку environment.
Тексты прописанные в исходниках программы и оформленные как resourcestring при компиляции программы автоматически собираются в файле zcad.po и разносятся по файлам локализаций zcad.XX.po где XX - идентификатор языка. Файлы zcad.XX.po можно непосредственно переводить используя предназначенные для этого программы например Poedit и подобные. На данный момент ZCAD имеет только русскую локализацию zcad.ru.po. добавить локализацию можно просто создав соответствующий файл, например zcad.de.po для немецкой.
Также в cad/languages лежат файлы перевода пакетов используемых в ZCAD:
-
anchordockstr.XX.po перевод пакета докинга окон AnchorDocking
-
lclstrconsts.XX.po перевод LCL
Тексты получаемые из рантайм файлов собираются в файле rtzcad.po, переводы находятся в zcad.XX.po также как и описано выше новую локализацию можно получить созданием соответствующего файла. Актуализация rtzcad.po и zcad.XX.po не производится автоматически, для этого нужно выполнить описанные ниже действия.
Запускаем программу с ключом командной строки (Переключатели командной строки) updatepo. При этом локализация программы не будет выполняться, будет работать оригинальный английский интерфейс. Создаем новый чертеж и вводим команду UpdatePO (UpdatePO) будет показано окно с информацией сколько обнаружено неактуальных строк и сколько добавлено новых. При нажатии Ok будет перезаписан файл rtzcad.po, неактуальные строки будут удалены, новые добавлены.
Далее из rtzcad.po строки нужно обновить в файлах локализаций rtzcad.XX.po, это можно сделать с помощью команды
C:\lazarus\fpc\3.2.2\bin\i386-win32\make updatelocalizedpofiles LP=C:\lazarus PCP=C:\Users\<ИМЯПОЛЬЗОВАТЕЛЯ>\AppData\Local\lazarus
Образование путей смотри (Cборка программы из исходников), сценарий updatelocalizedpofiles выполняет обновление файлов локализации.
После этого файлы rtzcad.XX.po можно переводить в специализированной программе
5.3. Написание документации ZCAD
Документация программы разрабатывается в формате AsciiDoc. Исходники данного руководства лежат в папке cad_source/docs/userguide/. AsciiDoc - простой текстовый формат, но для генерации pdf и html из него потребуются дополнительные манипуляций
5.3.1. Установка AsciiDoctor для Windows
Т.к. AsciiDoc написан на языке Ruby, придется установить средства разработки этого языка:
Идем на сайт https://rubyinstaller.org/downloads/ Скачиваем и устанавливаем последний Ruby+Devkit (на момент написания это 3.2.2-1) В процессе установки нужно будет указать какой вариант MSYS использовать, выбираем базовый 1, затем для завершения установки просто жмем enter
После установки Ruby в командной строке можно будет использовать gem - пакетный менеджер Ruby, с помощью его собственно устанавливает AsciiDoctor и требуемые расширения. Открываем командную строку и вводим эти три команды последовательно:
gem install asciidoctor
gem install asciidoctor-pdf
gem install asciidoctor-diagram
Дополнительно для работы asciidoctor-diagram требуется наличие в системе Java версии не ниже 11, если необходимо идем и устанавливаем по ссылке https://www.oracle.com/java/technologies/downloads/#jdk21-windows
5.3.2. Установка GraphViz
Также понадобятся средства визуализации графов из состава Graphviz. Идем на https://graphviz.org/download/ и качаем установщик для Windows на момент написания это graphviz-9.0.0 (64-bit) EXE installer при установке выбираем вариант Add Graphviz to the system PATH for all users чтоб графвиз был доступен из командной строки.
5.3.3. Генерация руководства пользователя
| Описанное выше нужно произвести один раз, это установит на компьютер необходимые программы и их зависимости |
После всех установок запускаем новую командную строку (рекомендую Far) чтобы все изменения системной переменной PATH вступили в силу. Идем в корневую директорию zcad (там где лежит makefile) и вводим
make documentation
Ждем выполнения скриптов, по завершению в папке zcad\cad_source\docs\userguide\ находим сгенерированные файлы userguide.ru.pdf и userguide.ru.html