SCons и Doxygen: первые впечатления

Александр Бельченко
22 мая 2005

Начало работы над новым проектом — пожалуй, лучшее время, чтобы начать освоение каких-нибудь новых инструментов, технологий или методик разработки. Пока работа над проектом не понеслась на всех парах без остановки, есть время для небольших экспериментов и изучения нового. Экспериментировать с существующим проектом, как правило, не очень получается — из-за отсутствия времени или желания. Или того и другого вместе.

Начиная работу над своим проектом «микропитон», я решил потратить время на изучение двух утилит:

SCons — Software Construction Tool (как замена make);
Doxygen — инструмент для генерации документации к исходным текстам программ.

Далее я расскажу о своих первых впечатлениях от использования этих инструментов.

Doxygen

Документация — это наше всё!

Наличие полной и толковой документации к проекту — это не самоцель, но благо для разработчиков по определению. К счастью, в наше время существует множество инструментов для автоматической генерации документации к исходным текстам проекта. Одним из таких инструментов является Doxygen. Он является бесплатным, свободно-распространяемым. Портирован под множество платформ.

Doxygen предназначен для документирования кода C++, C, Java, Objective-C, IDL, PHP, C# и D. К сожалению, он не поддерживает Python, но для питона имеются свои генераторы документации.

Doxygen использует систему специальных обозначений в комментариях к программе, аналогичную системе JavaDoc. При обработке исходных текстов проекта из специально оформленных комментариев извлекается необходимая информация, и на ее основе формируется цельная документация в форматах Html или Latex (или еще в некоторых других, на выбор). Причем полнота и охват такой документации просто поразительны: кроме документирования каждого отдельного файла, Doxygen формирует сводные индексы по именам функций, переменных, определений типов и т.д. Плюс имеется возможность получить поисковую систему по документации (требуется поддержка PHP на сервере).

Изучение системы обозначений Doxygen не займет много времени. А если Вы, как хороший разработчик, имеете привычку комментировать свой код, то привыкнуть к системе Doxygen будет достаточно просто, поскольку она не требует кардинальных изменений привычек. Удобно будет создать файлы-заготовки для C- и H- файлов, из которых потом методом Copy&Paste можно выбирать необходимые заготовки для комментариев.

Дополнительным плюсом является наличие GUI-мастера doxywizard, который поможет настроить все имеющееся множество опций и установок под нужды вашего проекта. Опции сохраняются в конфигурационный файл. Имя такого файла по умолчанию — Doxyfile (по аналогии с Makefile). Запустив doxygen в каталоге, содержащем Doxyfile, вы сформируете требуемую документацию к своему проекту.

Популярность любого инструмента (особенно open-source) я оцениваю по наличию поддержки национальных языков. Чем больше языков поддерживает программа, значит тем больше людей ее используют. Ибо для open-source программ перевод интерфейса программы на другие языки — дело рук «самих утопающих», т.е. пользователей программы, для которых родной язык — не английский.

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

Из недостатков программы: при генерации документации на русском языке доступны только кодировки КОИ-8 и win-cp1251, кодировка ДОС-cp866 не поддерживается.

SCons

SCons относится к make-утилитам нового поколения. Сам scons написан на питоне, и файлы с инструкциями для него (SConscript файлы) также пишутся на питоне. Для меня это огромный плюс, поскольку с одной стороны при написании инструкций для scons можно использовать множество полезных функций самого питона, а с другой, понимать, как работает та или иная функция самого scons, становится очень легко: если документация неясна — достаточно просто посмотреть исходники.

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

Например, классическая программа «Hello, world» будет скомпилирована с помощью gcc под Linux или с помощью MSVC6 под Windows. При этом сам файл SConstruct для обоих случаев будет одинаковый, что очень удобно:

Program('hello.c')

Scons достаточно «умный», чтобы самостоятельно формировать список зависимостей для файлов. Также, для определения того, изменился файл или нет, scons по умолчанию использует достаточно прогрессивный метод — хэш содержимого файла по алгоритму MD5, хотя может использовать и стандартный для make метод — по дате.

Из полезных достоинств scons — возможность простой и удобной работы с различными типами пользовательских опций, которые могут задаваться как из командной строки, так из файла. Причем при определении этих опций в тексте SConstruct имеется возможность указать краткий help к каждой опции. А затем простыми методами получить полную справку по этим опциям, которая будет выводиться при запуске scons с ключом -h.

Вообще среди опций scons встречаются архиполезные, так, например, опция -D. Эта опция позволяет запустить scons из любой поддиректории проекта, при этом scons сам будет идти вверх по дереву каталогов проекта до тех пор, пока не встретит файл SConstruct (удобно его держать в корне проекта), после чего запустит его выполнение. Кто когда-нибудь работал с проектами, содержащими множество файлов, разбитых по поддиректориям, тот оценит удобство этой опции.

Еще одним приятным достоинством scons является встроенная возможность создавать zip-архивы. А поскольку SConstruct-файл пишется на питоне, то создавать список файлов для обработки очень удобно средствами самого питона (которых у него более чем достаточно).

К недостаткам scons я могу отнести лишь некоторую его «задумчивость», которая, впрочем, характерна для большинства питон-приложений. Но я согласен мириться с этим неудобством, получая взамен очень гибкий и мощный инструмент.

Найденные баги

Любые даже самые лучшие программы не лишены недостатков и ошибок. К сожалению.

Один баг в scons нашел и я. Благодаря тому, что он написан целиком на питоне, находить и исправлять ошибки становится достаточно просто.

Баг касается встроенной поддержки компилятора Borland bcc32 v.5.5 (этот компилятор распространяется бесплатно). Для исправления бага необходимо внести изменения в файлы SCons/Tool/bcc32.py и SCons/Tool/ilink32.py, которые находятся в каталоге, куда был установлен scons. На моей машине это каталог «C:\Python24\scons\SCons\Tool». Исправленные версии файлов вы можете взять в архиве.

Примеры

Лучшей иллюстрацией ко всему вышесказанному будет конечно же наглядный пример.

В архиве s_d-example.zip содержится простая программа а-ля «Hello, world», которую можно собрать при помощи scons, и для которой можно сгенерировать документацию при помощи Doxygen.

Рекомендуемые версии утилит:

SCons — v.0.96.90+
Doxygen — v.1.4.3+

Получение справки по доступным целям:

 scons -h

Сборка проекта при помощи компилятора по умолчанию для вашей ОС:

 scons

Сборка при помощи bcc32 в среде Windows (необходимо заменить файлы bcc32.py и ilink32.py, как описано выше):

 scons bcc32

Формирование документации при помощи Doxygen:

 doxygen

или

 scons doc

Полученная документация доступна на сайте (с включенной поддержкой поискового механизма): html/index.html

On Embedding