OSFree Build

Версия 1.0 (проект черновика)

Данный документ описывает устройство и использование системы сборки проекта osFree. Целевая платформа проекта — OS/2 (а также DOS и Win16 в составе подсистем). Сборка выполняется с помощью Open Watcom (wmake) и вспомогательных скриптов.

Подразумевается, что исходный код уже получен согласно инструкциям из README.md.

---

1. Архитектура и основные компоненты

Система сборки состоит из:

• Скриптов запуска (_wcc.cmd, _wcc.sh), располагающихся в каждом каталоге с исходным кодом.
• Платформенных скриптов (build.cmd, build-os2.cmd, build-w32.bat, build-w64.bat, build-lnx.sh), отвечающих за определение ОС и настройку окружения.
• Make-файлов ядра в tools/mk/:
  • all.mk – главный make-файл, подключаемый всеми локальными makefile.
  • dirs.mk – вычисление рабочих путей (корень, каталог сборки, назначения).
  • site.mk – определение ОС, инструментов, разделителей.
  • genrules.mk – автоматическая генерация промежуточного makefile в каталоге сборки.
  • port.mk – поддержка внешних зависимостей (портов).
• Специализированных make-файлов:
  • loader.mk – сборка загрузчиков, microFSD, stage0 со сдвигом (shifted).
  • libsdos.mk – сборка библиотек DOS-подсистемы.
  • bootseq.mk – вероятно, для компонентов загрузочной последовательности.
• Локальных makefile в каждом подкаталоге, определяющих состав компонента.
• Вспомогательных скриптов (setenv.cmd, setvars-*.bat, updwcc.cmd, _setup и т.д.).

Цепочка запуска:

1. _wcc.cmd определяет корень проекта (ищет tools\mk\all.mk) и вызывает build %*.
2. build.cmd по наличию os2_shell и PROCESSOR_ARCHITECTURE запускает нужный build-*.cmd/.bat/.sh.
3. Платформенный скрипт настраивает переменные окружения (через setenv.cmd или setvars-*.bat) и вызывает wmake -h с переданными целями.
4. wmake обрабатывает корневой makefile, который включает all.mk и рекурсивно обходит подсистемы.

---

2. Поддерживаемые платформы хоста и целевые типы

Хост-системы (на чём запускается сборка):

• OS/2 (родная среда)
• Windows 32-бит (x86)
• Windows 64-бит (x86_64, кросс-сборка)
• Linux / FreeBSD (кросс-сборка, может потребоваться эмулятор)

Целевые типы компонентов (что собирается):

• 16-разрядные приложения OS/2 (.exe, .dll, .lib)
• 32-разрядные приложения OS/2 (.exe, .dll, .lib)
• 16-разрядные DOS-приложения
• 16-разрядные Windows 3.x-приложения
• Хостовые утилиты (инструменты сборки, например mkmsgf, exehdr)

Основной компилятор: Open Watcom (C/C++, ассемблер, компоновщик, библиотекарь). Дополнительно: Free Pascal (некоторые компоненты), JWasm (ассемблер), утилиты OS/2 Toolkit.

---

3. Необходимое окружение

3.1. Базовые зависимости

• Open Watcom (рекомендуемая версия из osFreeBE).
• Ожидаемые пути:
  • Windows: C:\osFreeBE\watcom
  • OS/2: переменная окружения %WATCOM%
  • Linux: переменная WATCOM, бинарники, возможно, через эмулятор (см. INTERP)
• Free Pascal (FPC) – C:\osFreeBE\fpc или FPPATH.
• Regina REXX (или другой REXX-интерпретатор) – для скриптов setenv.cmd, updwcc.cmd. На Windows обычно C:\osFreeBE\REXX\binnt.
• OS/2 Toolkit (os2tk45) – заголовки, библиотеки, утилиты (wrc, wipfc, mapsym, mkmsgf и т.д.).

Они должны находиться в %root%\build\bin\host\<host>\os2tk45 (автоматически подготавливается скриптами).

• Дополнительные утилиты в PATH: wget, unzip, patch, git, sed, awk (часто используются в правилах сборки).

3.2. Автоматическая установка (Windows)

При первом запуске _wcc.cmd на Windows, если утилита wmake не найдена, срабатывает скрипт _setup.cmd (или _setup.bat), который:

• Скачивает osFreeBE.zip с FTP-сервера проекта.
• Распаковывает его в C:\osFreeBE.
• После этого повторно настраивает окружение и ищет wmake.

3.3. Ручная настройка

Если автоустановка невозможна, можно вручную задать переменные, ориентируясь на файлы:

• tools/conf/scripts/setvars-w32.bat (образец для Windows)
• tools/conf/scripts/setenv.cmd (для OS/2)
• tools/conf/scripts/build-lnx.sh + setvars-lnx.sh (Linux)

---

4. Быстрый старт (после клонирования)

rem Из корня проекта:
_wcc.cmd             # на OS/2 или Windows
./_wcc.sh            # на Linux

Будет выполнена полная сборка всех подсистем (tools, msg, bootseq, DOS, OS2, dual, SOM) и установка результатов в build/bin.

Для сборки отдельного компонента можно перейти в его каталог и выполнить тот же _wcc.cmd:

cd OS2\CMD
..\_wcc.cmd

---

5. Основные переменные управления сборкой

Значения могут задаваться в среде перед запуском _wcc или в локальных makefile.

Переменная	Назначение	Пример
ROOT	Корень проекта	$(%ROOT)
WATCOM	Каталог Open Watcom	C:\WATCOM
OS2TK	OS/2 Toolkit	$(ROOT)build/bin/host/os2/os2tk45
HOST	Тип хостовой системы	win32, linux, os2
ENV / OS	Целевая среда сборки (для условной компиляции)	OS2, WIN32, LINUX
INTERP	Префикс эмулятора (пусто или qemu-i386)	qemu-i386
VERBOSE	Подробный вывод команд (yes/пусто)	yes
LOG	Перенаправление вывода в файл (при непустом значении)	1
DEST	Каталог установки относительно $(FILESDIR)	os2, boot, none
DEBUG	Добавление отладочной информации (yes/пусто)	yes
SHIFT	Базовый сдвиг для перемещаемых модулей (используется в loader.mk)	0x100
PLATFORM	Подкаталог в build/ для целевой платформы	host$(SEP)$(%HOST)$(SEP)
FILESDIR	Корень установки (обычно $(ROOT)build$(SEP)bin$(SEP))
BLD	Каталог для объектных файлов ($(ROOT)build$(SEP))
PATH (make)	Путь сборки текущего компонента ($(BLD)$(PLATFORM)$(RELDIR))

Полный список можно увидеть в цели print_vars при сборке.

---

6. Структура каталогов (важнейшие)

Корень проекта:

├── tools/
│   ├── mk/                  # Ядро make-файлов
│   ├── conf/scripts/        # Скрипты запуска и настройки
│   ├── scripts/             # Копируемые скрипты
│   └── makefile             # Сборка инструментов
├── DOS/
│   ├── makefile             # Подсистема DOS
│   └── shared/makefile      # Пример библиотеки
├── OS2/                     # Подсистема OS/2
├── SOM/                     # SOM/WPS классы
├── bootseq/                 # Загрузочная последовательность
├── msg/                     # Сообщения
├── makefile                 # Корневой makefile (порядок DIRS)
├── build/                   # Все результаты сборки
│   ├── host/<host>/         # Хостовые инструменты
│   ├── <platform>/          # Объектные файлы целевой платформы
│   └── bin/
│       ├── host/<host>/bin/ # Готовые хостовые утилиты
│       ├── os2/             # Бинарники для OS/2
│       └── boot/            # Загрузочные образы
├── contrib/                 # Внешние порты (при выгрузке)
└── _wcc.cmd, _wcc.sh        # Локальные запускатели (генерируются)

---

7. Процесс сборки (обобщённо)

1. precopy – копирование хостовых скриптов (.cmd, .awk, .cfg) в build/bin/host/<host>/bin (однократно, отслеживается по флагу).
2. Для каждого подкаталога в порядке, заданном в DIRS, выполняется:
   • prereq:
     • Создание иерархии выходных каталогов (dirhier).
     • Генерация _wcc.cmd/_wcc.sh (через updwcc.cmd).
     • Генерация makefile в $(PATH) с включением исходного makefile и автоматическими правилами для объектных файлов и компоновки (genrules.mk).
   • prep – для компонентов-портов: загрузка исходников, распаковка, патчинг.
   • Компиляция по суффиксным правилам (.c.obj, .asm.obj, .c.sob и т.д.).
   • Компоновка (.lnk.exe, .lnk.dll, специфичные правила для загрузчиков).
   • Постобработка (для загрузчиков: RIP, GENREL).
   • install – копирование результатов в $(DEST) (обычно build/bin/os2 или build/bin/boot).
3. Параллельная сборка между подсистемами не предусмотрена.

---

8. Как добавить новый компонент

1. Создайте подкаталог (например, MyApp) и в нём файл makefile.
2. Определите обязательные переменные:
   • PROJ – имя проекта.
   • Если это библиотека: TRGT = $(PROJ).lib, TARGETS = $(PATH)$(TRGT).
   • Если программа: можно указать files = ... или srcfiles = ..., TARGETS (используя суффиксные правила из all.mk).
   • ADD_COPT, ADD_ASMOPT – дополнительные флаги компиляции/ассемблирования.
   • DEST – куда устанавливать (по умолчанию os2, можно указать none для отладки).
   • Если компонент содержит подкаталоги, перечислите их в DIRS.
3. Включите ядро: !include $(%ROOT)tools/mk/all.mk или специализированный файл (libsdos.mk, loader.mk).
4. При необходимости переопределите gen_compile_rules_wrapper и gen_deps_wrapper для нестандартных расширений или shifted-файлов (см. примеры в loader.mk).
5. Добавьте каталог в DIRS родительского makefile.

---

9. Специализированные make-файлы

9.1. loader.mk

Используется для сборки загрузчиков и microFSD. Особенности:

• Определяет дополнительные расширения: .sob, .lob, .bin, .sbi, .mdl, .mds, .rel.
• Вводит переменную SHIFT (по умолчанию 0x100) для создания перемещаемых образов.
• Переопределяет правила компиляции для .c.$(SO), .c.$(LO), .asm.$(SO) и т.д.
• Постобработка: утилиты RIP (создание .mdl/.mds) и GENREL (таблица релокаций).
• Специфичное правило link генерирует .lnk-файл с фиксированным адресом output raw offset=0x10000 и библиотекой ldr_shared.lib.
• Устанавливает DEST = boot, если не задан иной.

9.2. libsdos.mk

Используется для сборки библиотек DOS-подсистемы (например, dos_shared.lib). Детали зависят от реализации, но, как правило, добавляет правило library для вызова wlib.

9.3. port.mk

Добавляет цель prep для автоматической загрузки и подготовки внешних зависимостей. Переменные, которые должны быть определены в локальном makefile:

• PORT_NAME – имя порта,
• PORT_TYPE – wget, git или svn,
• PORT_URL – адрес для загрузки,
• PORT_PATCHES – список патчей (если есть),
• PORT_FLAG – путь к флаговому файлу (обычно $(CONTRIB)$(PORT_NAME).flg).

Пример использования см. в компонентах, использующих порты (каталоги contrib).

---

10. Устранение неполадок

Проблема	Вероятная причина	Решение
wmake: command not found	Не настроен Open Watcom	Запустить _setup (Windows) или установить Open Watcom и прописать WATCOM в окружении
Error: os2tk45 not found	Отсутствуют заголовки OS/2 Toolkit	Скопировать OS/2 Toolkit в build/bin/host/<host>/os2tk45 или проверить переменную OS2TK
Сборка останавливается с неясной ошибкой	Подавлен вывод	Задать VERBOSE=yes перед запуском _wcc
Не подхватываются изменения в заголовках	Кэширование авто-зависимостей	Выполнить wmake clean в проблемном каталоге и пересобрать
Порты не обновляются после смены патчей	Флаговый файл уже существует	Удалить файл *.flg и перезапустить сборку
На Linux не запускаются бинарники Watcom	Требуется эмулятор	Установить qemu-i386 и задать INTERP=qemu-i386

---

11. Внутреннее устройство (справочно)

11.1. Генерация make-файла в каталоге сборки

Для каждого компонента в build/<platform>/<relative_path>/makefile создаётся файл, который:

• Содержит !include $(%ROOT)<relative_path>/makefile (исходный makefile).
• Дополняется списками объектных файлов (<target>_OBJS) и правилами компоновки для каждого file из переменной files.
• Правила компиляции добавляются через gen_compile_rules_wrapper, которая обычно определена в локальном makefile или специальном .mk.
• Для обычных программ достаточно стандартных суффиксных правил из all.mk.

11.2. Shifted-компиляция

В loader.mk и, возможно, других местах каждый исходный файл компилируется дважды:

• Обычная версия (без сдвига) с суффиксом .obj (или .$(O)).
• Сдвинутая версия с суффиксом .sob (shifted object), для которой добавляется -dSHIFT=$(SHIFT).

Полученный бинарный образ затем сдвигается по адресу $(SHIFT) для релокации. Это необходимо для загрузчиков, работающих с перемещением кода.

11.3. Переменная INTERP

Если установлена (например, qemu-i386), все вызовы компилятора, компоновщика и других инструментов оборачиваются в этот интерпретатор. Позволяет на Linux запускать 32-битные Windows-бинарники Watcom.

---

12. Важные замечания

• Не удаляйте файлы _wcc.cmd / _wcc.sh в исходных каталогах. Они необходимы для сборки.
• При добавлении новых файлов в компонент достаточно обновить переменную files или srcfiles в его makefile – генератор сам добавит правила.
• Для ускорения повторных сборок можно не очищать каталог build/ целиком, а удалять только отдельные объектные файлы.
• При возникновении конфликтов имён в разных подсистемах можно использовать !ifndef some_mk и !define some_mk для предотвращения двойного включения (как в loader.mk).

---

(c) osFree project, 2002–2022. Документация по системе сборки.

Источник: Официальный чат Telegram