===== Первые шаги =====

Перед тем как начать что-то кодировать, почитайте исходники и определите область, которая вас заинтересует для разработки. У нас есть очень широкий круг задач и, очень возможно, одна из них вас заинтересует. Только помните, что наша текущая главная задача -- реализовать более или менее полный набор OS/2 API поверх микроядра L4.

==== Инструменты разработки ====

^Язык программирования      ^Компилятор         ^
|C                    |Open Watcom |
|C++               |Open Watcom  |
|FORTRAN     |Open Watcom  |
|Pascal           |FreePascal       |
|REXX             |ReginaREXX     |

Другие языки тоже могут быть использованы для разработки частей ОС. Но они тоже должны быть Open Source и использовать OS/2 API. Использование платных и shareware (то есть, которые могут быть скачаны с многих мест, но стоят денег и лицензия которых имеет много ограничений) не рекомендуется. Желательно использовать инструменты из поставки OpenWatcom для сборки ваших исходников.

Когда существуют аналогичные инструменты (например NMAKE и WMAKE), всегда используйте инструменты из поставки OpenWatcom. 

==== Получение и сборка исходных кодов ====

Сначала, вы должны загрузить нижеперечисленные инструменты для вашей платформы с соответствующих сайтов:

  * [[http://www.openwatcom.org/]] для OpenWatcom
  * [[http://www.freepascal.org/]] для FreePascal
  * [[http://regina-rexx.sf.net/]] для ReginaREXX

Вы можете [[ru:download|загрузить]] нерегулярно обновляемые снапшоты исходников с этого сайта, или самые последние версии из Git. Исходники osFree находятся на [[https://github.com/osfree-project/osfree/|GitHub]]. GitHub также позволяет скачать любую ревизию в виде .tar.gz архива.

Перед сборкой проверьте файлы setvars-<somename>.cmd и <somename>.conf, И поменяйте настройки (в основном, пути к инструментам разработки). После этого откройте сеанс командной строки и запустите setvars-<somename>.cmd и введите

<code>wmake</code>

начнется процесс сборки. Для очистки дерева исходников от созданных при сборке файлов наберите

<code>wmake clean</code>

Для более подробной информации о системе сборки см. документ [[en:develop:bldenv|Система сборки]].

==== Дерево каталогов ====

Посмотрите на код в Git-репозитории, для понимания принципа размещения файлов. Обратите внимание, что дерево файлов в SVN osFree состоит из исходных кодов операционной системы и инструментов тулкита. Пожалуйста, НЕ помещайте сюда приложения и инструменты, не соответствующие назначению тулкита. Тулкит это вспомогательные утилиты, собираемые под ту систему, под которой ведется сборка и необходимые для сборки файлов ОС.

==== Глобальные/Общие/Приватные файлы заголовков ====

Каждый уровень дерева исходных текстов содержит два стандартных каталога: <code>FIX THIS! Сейчас это немного не так!</code>

|//shared//   |Содержит код, общий для данного и более глубокого уровней вложенности каталогов |
|//include//  |Содержит заголовки для всего выше перечисленного |

Каждая часть/уровень ОС должен иметь отдельный префикс, позволяющий разработчику легко найти часть ОС, к которой заголовочный/библиотечный файл принадлежит. Например, код, общий для всего дерева исходников, должен включать:

<code c>#include <all_shared.h></code>

и код общий для утилит командной строки должен вклюачть:

<code c>#include <cmd_shared.h></code>

Старайтесь создавать чем меньше общих заголовочных файлов, тем лучше. Кадждый “shared” каталог должен содержать один (1) библиотечный (.lib) файл (xxx_shared.lib) со всем общим кодом и каждая “include” директория должна содержать один главный заголовочный файл, включабщий все другие (xxx_shared.h).

Пример использования общих файлов:

<code c>// Use the normal OS/2 INCL_ since our toolkit is the OS/2 toolkit
#define INCL_DOSERROR

// Do NOT include os2.h, use osfree.h instead
#include <osfree.h>

// Include any needed normal C library
#include <malloc.h>
#include <string.h>

// Include all shared code and shared code for command line tools
#include <all_shared.h>
#include <cmd_shared.h>
</code>

==== Документация ====

  * Приватный код (не разделяемый ни с каким другим кодом) должен быть документирован только внутри исходника.
  * Разделяемый код (разделяемый на одном уровне, или же разделяемый со всеми уровнями) должен быть документирован в исходнике и в документе “[[en:develop:bldenv|Разработка и сборка исходников]]”.
  * ОС API и документация к утилитам тулкита НЕ должна находиться в дереве исходников, а должна быть в тулките и в комплекте каждого релиза.
  * Исходный код должен быть документирован в нем самом (но не во включаемых файлах).
  * Каждая функция должна предваряться специальным комментарием с описанием того, что она делает, какие параметры она использует (входные и выходные) и прочие внешние ссылки, которые она использует.
  * Размещайте комментарии в исходном коде таким образом, чтобы тот, кто его читает, легко мог разобраться в логике, но не переусердствуйте в деталях.

==== В процессе разработки ====

  * Используйте статическую линковку, не используйте динамических библиотек (LIBC style) или динамических рантаймов.
  * Пользуйтесь мейкфайлами из дерева исходников, не изобретайте свои собственные “велосипеды”.
  * На текущий момент разработка osFree происходит в среде OS/2 (как минимум, Warp 4), но в будущем разработка будет производиться в самой osFree ("self-hosting").
  * Мы используем Git для совместной разработки.
  * Мы пользуемся Doxygen и Wiki для документирования своей работы.

==== Присылая патчи с исправлениями (ИСПРАВИТЬ!!!) ====

  * Убедитесь, что ваши патчи удовлетворяют правилам, описанным выше.
  * Убедитесь, что у вас исходники последней версии,чтобы ваши патчи соответствовали текущей головной ветви (master).
  * Создавайте ваш патч используя git diff если вы используете Git) или diff -u original-file changed-file (если вы используетсе архив с исходниками, или просто изменения к целому дереву файлов, используйте diff -r). В последнем случае, исходный код указывайте первым параметром, и измененный -- вторым.  Тогда все ваши изменения будут добавлены в патч с префиксом "+".
  * Удаляйте из патча все несущественные строки.
  * Присылайте патчи в виде прикрепленного к письму файла. Не вставляйте его прямо в тело письма.
  * Мейнтейнеры могут ответить вам на ваш патч, указав необходимые исправления, и др. перед тем, как патч будет принят. Всегда внимательно относитесь к замечаниям мейнтейнера и в ответ присылайте исправенные патчи. Пожалуйста, не считайте, что мейнтейнеры должны сами дорабатывать ваши патчи, вы должны быть уверены в правильности ваших изменений, чтобы по праву требовать благодарности за ваши замечательные патчи с нашей стороны!

~~DISCUSSION~~