19.2.4.1. Убедитесь, что архивы всегда распаковываются в один новый каталог
Наиболее досадной ошибкой неопытных соавторов является сборка архивов, которые распаковывают файлы и каталоги дистрибутива в текущий каталог, что связано с потенциальной возможностью перезаписи имеющихся в нем файлов. Такой подход не рекомендуется.
Вместо этого следует убедиться, что все архивные файлы имеют общий каталог, который назван именем проекта, для того чтобы они распаковывались в один каталог верхнего уровня непосредственно в текущем каталоге. Традиционно имя каталога должно быть таким же, как именная часть архива. Например, предполагается, что архив с именем f оо- 0 .23. tar. gz распаковывается в подкаталог f оо- 0.23.
В примере 19.1 демонстрируется решение для make-файла, которое позволяет реализовать указанный принцип в предположении, что каталог дистрибутива называется "foobar", a SRC содержит список файлов дистрибутива.
Пример 19.1. make-правила для tar-архива
foobar-$(VERS).tar.gz:
®ls $(SRC) I sed s:A:foobar-$(VERS)/: >MANIFEST ®(cd ..; In -s foobar foobar-$(VERS))
(cd ..; tar -czvf foobar/foobar-$(VERS).tar.gz "cat foobar /MANIFEST" )
®(cd ..; rm foobar-$(VERS))
19.2.4.2. Включайте в дистрибутив README-файл
В дистрибутив программы следует включать файл README, который является путеводителем по дистрибутиву. Согласно давнему соглашению (созданному самим Деннисом Ритчи до 1980 года, и распространенному в Usenet в начале 1980-х годов), данный файл является первым файлом, который будут читать бесстрашные исследователи, после того как распакуют исходный код.
README-файлы должны быть короткими и легко читаемыми. Они должны быть вводным документом, а не крупным произведением. Рассмотрим пункты, которые рекомендуется включать в README-файлы.
1. Краткое описание проекта.
2. Ссылка на Web-сайт проекта (если он существует).
3. Примечания по среде разработки и потенциальным проблемам переносимости.
4. Схема проекта, описывающая важные файлы и подкаталоги.
5. Инструкции по компиляции/установке или ссылка на файл, содержащий такие инструкции (обычно INSTALL).
6. Список кураторов/благодарностей или ссылка на содержащий его файл (обычно CREDITS).
7. Последние новости проекта или ссылка на содержащий их файл (обычно NEWS).
8. Адреса списков рассылки проекта.
В свое время данный файл обычно назывался READ. ME, однако с таким именем плохо взаимодействуют браузеры, которые слишком склонны интерпретировать файл с суффиксом . ME как нетекстовый и позволяют только загружать его, а не просматривать. Такой подход устарел и уже не рекомендуется.
19.2.4.3. Придерживайтесь стандартной практики именования файлов
Еще до просмотра README-файла бесстрашный исследователь внимательно изучит имена файлов в корневом каталоге распакованного дистрибутива. Имена файлов в нем сами по себе способны нести полезную информацию. Соблюдая определенные стандартные принципы наименования, разработчик может дать исследователю ценную подсказку о том, "куда смотреть дальше".
Ниже приведены некоторые стандартные имена файлов верхнего уровня, а также описания соответствующих файлов. Не каждый дистрибутив нуждается во всех перечисленных файлах.
README
Файл-путеводитель, который прочитывают первым.
INSTALL
Инструкции по конфигурированию, компиляции и установке.
AUTHORS
Перечень участников проекта (GNU-соглашение).
NEWS
Последние новости проекта.
HISTORY
История проекта.
CHANGES
Перечень значительных изменений между различными редакциями.
COPYING
Лицензионные условия проекта (GNU-соглашение).
LICENSE
Лицензионные условия проекта.
FAQ
Текстовый документ с перечнем часто задаваемых вопросов по проекту.
Следует отметить существование общего соглашения, согласно которому имена файлов, набранные в верхнем регистре, содержат метаинформацию о проекте и предназначены для чтения людьми, а не являются компонентами сборки. Данное уточнение файлов README было давно разработано Фондом свободного программного обеспечения.
Наличие файла FAQ может предотвратить множество неприятностей. Когда какой-либо вопрос по проекту встречается часто, его следует поместить в список часто задаваемых вопросов, после чего предложить пользователям прочесть данный файл, прежде чем отправлять свои вопросы или отчеты об ошибках. Хорошо организованный FAQ-файл способен на порядок или больше снизить нагрузку по поддержке, которая лежит на кураторах проекта.
Весьма ценным является наличие файлов HISTORY или NEWS, содержащих временные метки для каждой версии. Кроме всего прочего, такие файлы могут помочь доказать существование предшествующей разработки, если разработчику когда-либо придется столкнуться с судебным процессом по нарушению патентов (такое еще не случалось, но лучше быть готовым).
19.2.4.4. Проектирование с учетом обновлений
По мере выхода новых версий, программы изменяются. Некоторые изменения обратно не совместимы. Соответственно, следует серьезно продумать проектирование схемы инсталляции, для того чтобы несколько установленных версий кода могли сосуществовать в одной системе. Это особенно важно в отношении библиотек — нельзя рассчитывать на то, что все клиентские программы будут обновляться по мере изменения вашего API-интерфейса.
Проекты Emacs, Python и Qt имеют хорошее соглашение для реализации этого принципа: каталоги с номерами версий (другой практический прием, который, вероятно, становится установившейся практикой благодаря FSF). Ниже показано, как выглядит установленная библиотека Qt ($ {ver} — номер версии).
/usr/lib/qt /usr/lib/qt-${ver} /usr/lib/qt-${ver}/bin #
/usr/lib/qt-${ver}/lib #
/usr/lib/qt-${ver}/include #
Распложение moc Распложение .so
Расположение заголовочных файлов
При наличии такой организации сосуществование нескольких версий вполне возможно. Клиентские программы должны указывать необходимую версию библиотеки, однако это небольшая цена, которую приходится уплатить, чтобы не иметь сбоев в интерфейсах. Данная практика позволяет избежать печально известного "ада DLL", характерного для Windows.
19.2.4.5. В Linux создавайте RPM-пакеты
Де-факто стандартным форматом для устанавливаемых бинарных пакетов в Linux является формат, используемый диспетчером пакетов Red Hat Linux, RPM (Red Hat Package manager). Он имеется в большинстве популярных дистрибутивов Linux и поддерживается фактически всеми остальными дистрибутивами (кроме Debian и Slackware; а в Debian можно устанавливать программы из RPM-пакетов). Следовательно, хорошей идеей для сайта проекта будет предоставление устанавливаемых RPM-пакетов наряду с архивами исходных кодов.
Также хорошей идеей будет включение в архив с исходным кодом файл RPM-спецификации, из которого правило в makefile позволяет создавать RPM-пакеты. Файл спецификации должен иметь расширение . spec; по данному расширению команда rpm -t обнаруживает его в архиве.
Для особых целей рекомендуется генерировать файл спецификации с shell-сценарием, который автоматически вставляет корректный номер версии, анализируя файлы makef ile или vers ion. h проекта.
