Стандарты программирования GNU

Содержание
*************

Версия
1 О стандартах программирования GNU
2 Сохранение свободного ПО свободным
2.1 Ссылки на проприетарные программы
2.2 Принятие вкладов
2.3 Товарные знаки
3 Основной дизайн программы
3.1 Какие языки следует использовать
3.2 Совместимость с другими решениями
3.3 Использование нестандартных особенностей
3.4 Стандартный C и до-стандартный C
3.5 Условная компиляция
4 Программное поведение для всех программ.
4.1 Не-GNU стандарты
4.2 Написание качественных программ
4.3 Поведение библиотек
4.5 Стандарты интерфейсов в общем
4.4 Форматирование сообщений об ошибках
4.6 Стандарты графических интерфейсов
4.7 Стандарты интерфейсов командной строки
4.7.1 `--version'
4.7.2 `--help'
4.8 Таблица длинных опций
4.9 Распределения OID
4.10 Использование памяти
4.11 Использование файлов
5 Наилучшее использование C
5.1 Форматирование Вашего исходного кода
5.2 Комментирование вашей работы
5.3 Чистое использование конструкций C
5.4 Обозначение переменных, функций и файлов
5.5 Переносимость между типами систем
5.6 Переносимость между CPU
5.7 Вызов системных функций
5.8 Интернационализация
5.9 Кодировка
5.10 Символы кавычек
5.11 Mmap
6 Документация программ
6.1 Руководство GNU
6.2 Строки документаций и руководства
6.3 Детали структуры руководств
6.4 Лицензия для руководств
6.5 Авторы руководства
6.6 Напечатанные руководства
6.7 Файл НОВОСТЕЙ
6.8 Журналы изменений
6.8.1 Концепции журнала изменений
6.8.2 Стиль журнала изменений
6.8.3 Простые изменения
6.8.4 Условные изменения
6.8.5 Определение изменения части
6.9 Страницы Man
6.10 Чтения других руководств
7 Процесс выпуска
7.1 Как должна работать конфигурация
7.2 Соглашения Makefiles
7.2.1 Общие Соглашения для Makefiles
7.2.2 Утилиты в Makefiles
7.2.3 Переменные для определения команд
7.2.4 'DESTDIR': поддержка пошаговой установки
7.2.5 Переменные для директорий установки
7.2.6 Стандартные цели для пользователей
7.2.7 Категории установочных команд
7.3 Создание выпусков
8 Ссылки на не-Свободное ПО и документацию
Приложение A: Лицензия свободной документации GNU
Индекс

Текст
******

Стандарты программирования GNU, последнее обновление: Декабрь 11, 2009.

Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.

Каждый вправе копировать, распространять и/или изменять этот документ в соответствии с лицензией свободной документации GNU версии 1.3 или любой более поздней версии изданной Фондом свободного программного обеспечения; без Неизменяемых разделов, без текстов передней и задней обложки. Копия лицензии включена в секцию, названную "Лицензия свободной документации GNU".

О стандартах программирования GNU
***************************************

Стандарты программирования GNU были составлены Ричардом Столманом и другими активистами проекта. Их целью было сделать систему GNU понятной, однородной и простой для установки. Данный документ может использоваться также и в качестве инструкции по написанию машинонезависимых, устойчивых и надежных программ. Особое внимание уделено программам на C, но многие из правил и принципов также полезны, если используется другой язык программирования.

Если вы не получили этот файл непосредственно из проекта GNU, пожалуйста, проверьте наличие более новой версии. Вы можете получить Стандарты программирования GNU на сервере GNU в различных форматах, в том числе исходник Texinfo, PDF, HTML, DVI, обычный текст, и другие, по адресу:
`http://www.gnu.org/prep/standards/'.

Если вы поддерживаете официальный пакет GNU, кроме этого документа, пожалуйста, прочтите и следуйте информации для разработчиков GNU.

Для получения списков изменённых строк при каждом изменении данных документов GNU необходимо подключиться к списку рассылки
gnustandards-commit@gnu.org
на веб-странице
http://lists.gnu.org/mailman/listinfo/gnustandards-commit. Предшествующие выпуски также доступны на этой странице.

Исправления или пожелания по данному документу следует отправлять по адресу
<bug-standards@gnu.org>. Если вы делаете предложение, включите, пожалуйста, предлагаемую новую редакцию для этого; наше время ограничено. Мы предпочитаем контекстное построчное сравнение с файлами standards.texi или make-stds.texi, но, если у вас нет этих файлов, пожалуйста, напишите ваше предложение в любом формате.

Эти стандарты охватывают минимум того, что является важным при написании пакета GNU. Вероятно, возникнет необходимость в дополнительных стандартах. Может быть, вы предполагаете, что такие стандарты должны быть добавлены к этому документу. Если вы считаете, что ваши стандарты в целом будут полезными, пожалуйста, предлагайте их.

Вы также должны установить стандарты для вашего пакета по многим вопросам, не адресованным или же нечётко разъяснённым здесь. Наиболее важный момент - быть последовательными: старайтесь придерживаться правил, которые вы выбрали, и пытайтесь их как можно больше задокументировать. Таким образом, ваша программа будет более удобной для обслуживания другими.

Пример использования стандартов программирования GNU для простой программы - программа GNU Hello:
http://www.gnu.org/software/hello/hello.html.

Этот выпуск стандартов программирования GNU был обновлен 11 декабря, 2009.

2 Сохранение свободного ПО свободным
*******************************************

В этом разделе обсуждается то, как вы можете убедиться в том, что программное обеспечение GNU избегает правовых трудностей и других связанных с этим проблем.

2.1 Ссылки на проприетарные программы
=====================================

Ни в коем случае не обращайтесь к исходным кодам Unix во время работы на проект GNU! (Или к любым другим проприетарным программам.)

Если у вас есть смутные воспоминания об устройстве программы для UNIX, это совершенно не означает, что вы не можете писать её имитацию, но постарайтесь внутренне организовать эту имитацию другими путями, так как это может сделать детали версии для UNIX неуместными и отличными от ваших результатов.

Например, утилиты UNIX были, в основном, оптимизированы для уменьшения использования памяти. Если вы, напротив, оптимизируете скорость работы, то ваша программа будет сильно отличаться. Вы можете хранить весь входной файл в памяти и сканировать его вместо использования stdio. Используйте более умный алгоритм, разработанный позже, чем программа для UNIX. Исключите использование временных файлов. Сделайте это в один проход вместо двух (мы это делали на ассемблере).

Или, наоборот, подчеркните простоту, а не скорость. Для некоторых приложений скорость современных компьютеров делает адекватными простые алгоритмы.

Или сделайте ставку на универсальность. Например, программы для Unix часто имеют статичные таблицы или строки фиксированного размера, которые накладывают произвольные ограничения; используйте вместо этого динамичное распределение. Удостоверьтесь, что ваша программа обрабатывает NUL и другие забавные символы во входных файлах. Добавьте язык программирования для расширяемости и напишите часть программы на этом языке.

Или превратите некоторые части программы в пригодные для независимого использования библиотеки. Или используйте простой сборщик мусора вместо точного отслеживания момента для освобождения памяти, или воспользуйтесь новым средством GNU, таким, как obstacks.

2.2 Принятие вкладов
================

Если авторские права на программу, над которой вы работаете, принадлежат Free Software Foundation (Фонд свободного ПО), то, когда кто-нибудь присылает вам фрагмент кода для добавления в программу, нам нужны правовые документы для её использования - также, как мы просили вас подписать документы, на начальном этапе. _Каждое_ лицо, которое делает нетривиальный вклад в программу, должно подписать какие-либо правовые документы, чтобы нам иметь чёткое заглавие программы; одного основного автора недостаточно.

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

Это применимо как до выпуска программы, так и после. Если вы получаете предложения по изменению конкретных строк программы для исправления ошибок, и они вносят значительные изменения, то нам нужны правовые документы для этого.

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

Мы знаем, что это неприятно просить правовые документы; это неприятно и для нас тоже. Но, если вы не ждёте, то рискуете. Например, что, если работодатель вкладчика не подпишет отказ от прав? Возможно, вам придётся изымать этот код обратно!

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

Самое худшее, если Вы забудете сообщить нам о другом
вкладчике. В результате, в суде мы будем в очень неловком положении.

У нас есть более подробные рекомендации для разработчиков программ. Если вы созрели для того, чтобы действительно участвовать в разработке программы для GNU (неважно, выпущенной или нет), пожалуйста, обратитесь к нам за копией. Она также доступна для ознакомления онлайн: http://www.gnu.org/prep/maintain/.

2.3 Торговые марки
==============

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

Уведомления о товарных знаках - это утверждения, что что-то там является товарным знаком кого-то там. Проект GNU не возражает против самой идеи товарных знаков, но эти уведомления производят впечатление какого-то раболепия, и нет никаких юридических требований для них, поэтому мы их не используем.

Что требуется по закону в отношении товарных знаков других людей, так это избегать использования их таким образом, что читатель может обоснованно их принять за наименование или маркировку наших собственных программ или мероприятий. Например, поскольку Objective C является (или, по крайней мере, являлся) товарным знаком, мы непременно говорили, что мы предоставляем "компилятор для Objective C", а не "компилятор Objective C". Последняя фраза могла бы подразумеваться, как краткий вариант для предыдущей, но она неточно выражает отношения, и поэтому может быть неверно истолкована, как использование слов "Objective C" в качестве названия для компилятора, а не для языка.

Пожалуйста, не используйте "win" как аббревиатуру для Microsoft Windows в программном обеспечении или документации GNU. В хакерской терминологии, назвать что-то "win" - это форма похвалы. Если вы хотите похвалить Microsoft Windows, высказывая своё мнение, конечно, делайте это, но не в программном обеспечении GNU. Обычно мы пишем название "Windows" полностью, но, когда краткость очень важна (как в именах файлов, а иногда и в именах символов), мы сокращаем его до "w". Например, файлы и функции в Emacs, которые работают с Windows, начинаются с 'w32'.

3 Основной дизайн программы
****************************

Раздел обсуждает некоторые проблемы, которые Вы должны принимать во внимание при проектировании Вашей программы.

3.1 Какие языки следует использовать.
===============================

Если вы хотите использовать компилируемый язык, программы на котором выполняются быстро, то лучшим выбором будет использовать язык C. Использование другого языка - сродни использованию нестандартной возможности: это вызовет проблемы у пользователей. Даже если GCC поддерживает этот другой язык, пользователи могут посчитать неудобством необходимость установки компилятора для этого языка для того, чтобы скомпилировать вашу программу. К примеру, если вы напишете свою программу на C++, пользователям придется устанавливать компилятор GNU C++, чтобы скомпилировать ее.

У языка C есть и другое преимущество перед С++ и другими компилируемыми языками: язык С знает большее количество людей, а значит для большего числа людей не составит труда читать и модифицировать программу, написанную на C.

Таким образом, в общем случае намного предпочтительнее использовать С, нежели другие сравнимые альтернативы.

Но есть два исключения из этого вывода:

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

* Если приложение интересно только узкому кругу людей, то вопрос языка, на котором написан исходный код, затронет других людей в меньшей степени, а значит, вы можете следовать своим предпочтениям.

Многие программы специально разработанны так, чтобы быть расширяемыми. Они включают в себя интерпретатор более высокоуровневого языка, чем С. Часто большая часть программы сама написана на этом языке. Редактор Emacs был пионером в использовании данной техники.

Стандартный интерпретатор расширений для GNU - это Guile (`http://www.gnu.org/software/guile/'). Он реализует язык Scheme (исключительно чистый и простой диалект языка Lisp). Guile также предоставляет привязки к GTK+ и GNOME, что делает его исключительно практичным для реализации современной функциональности графического интерфейса. Мы не отвергаем программы, написанные на других "скриптовых" языках, таких как Perl или Python, но использование Guile очень важно для поддержания общей целостности системы GNU.

3.2 Совместимость с другими реализациями
============================================

За редкими исключениями, утилиты и библиотеки для GNU должны быть обратно совместимы с аналогами в BSD, со стандартом С, если стандарт С определяет их поведение, и с POSIX, если POSIX определяет их поведение.

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

Стандарт С и POSIX запрещает многие виды расширений. Тем не менее не стесняйтесь делать расширения, и добавляйте опции '--ansi ', '--posix', или '--compatible' , для их отключения. Однако, если расширение имеет значительный шанс сломать какие-нибудь реальные программы или скрипты, то это нарушает обратную совместимость. Таким образом, вы должны попытаться перестроить его интерфейс чтобы сделать его обратно совместимым.

Многие GNU программы подавляют расширения, которые конфликтуют с POSIX, если переменная среды 'POSIXLY_CORRECT' определена (даже если она определена нулевым значением). Пожалуйста убедитесь, что Ваша программа распознает эту переменную, если нужно.

Если какая-то особенность применяется только пользователями (а не программами или командными файлами) и плохо реализована под Unix, Вы можете полностью заменить ее чем-то совсем другим и лучшим. (Например, vi заменяется на Emacs.) Но желательно также предложить совместимую особенность. (Есть бесплатный клон vi, и мы предлагаем его).

Дополнительные полезные функции приветствуются независимо от того, имеют ли они прецедент.

3.3 Использование нестандартных особенностей
===================================

Многие существующие средства GNU поддерживают несколько удобных расширений над соответствующими средствами Unix. Стоит ли использовать эти расширения при реализации Вашей программы - вопрос сложный.

С одной стороны, использование расширений может сделать программу понятнее.
С другой стороны, чтобы построить программу, людям понадобится доступ к другим инструментам GNU. Возможно, из-за этого программа сможет работать на меньшем количестве типов машин.

Для некоторых расширений может быть легко предоставить обе альтернативы.
Например, Вы можете определить функции с ключевым словом 'INLINE' и определить их как макрос, расширяющийся либо в 'inline', либо в ничто, в зависимости от компилятора.

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

Исключением из этого правила являются большие, оформившиеся программы (например, Emacs), работающие на огромном множестве разных платформ. Применение расширений GNU в таких программах сделает многих пользователей недовольными, поэтому мы этого не делаем.

Другое исключение - программы, используемые как часть компилятора: что угодно, что должно быть скомпилировано другими компиляторами для того, чтобы загрузить средства компиляции GNU. Если такие программы будут требовать наличия компилятора GNU, то никто не сможет их скомпилировать, не имея их уже установленными. Это было бы крайне проблематично в определенных случаях.

3.4 Стандартный C и до-стандартный C
=================================

Стандарт C 1989 года сейчас достаточно широко распространен, чтобы было нормальным использовать его возможности в новых программах. Есть одно исключение: никогда не используйте особенность "trigraph" стандарта C.

Стандарт C 1999 года ещё не достаточно распространён, поэтому не требуйте его возможности в программах. Нормально использовать его особенности, если они всё же присутствуют.

Однако, это просто поддержать достандартные компиляторы в большинстве программ, поэтому, если Вы знаете, как это сделать, то не стесняйтесь. Если программа, которую Вы разрабатываете, имеет такую поддержку, то Вы должны попытаться сохранить ее работоспособной.

Чтобы поддерживать достандартный C, вместо того, чтобы писать определения функций в стандартной форме прототипа,

int
foo (int x, int y)
...

cоздайте определение в достандартном стиле, как здесь,

int
foo (x, y)
int x, y;
...

и используйте отдельное определение, чтобы указать прототип аргумента :

int foo (int, int);

Вам нужно такое определение во всяком случае, в заголовочном файле, чтобы получить преимущество прототипов во всех файлах, где вызвана функция. А когда у вас есть определение, вы обычно ничего не теряете, написав объявление функции в достандартном стиле.

Эта методика не работает для целочисленных типов, которые "уже", чем 'int'.
Если вы считаете, что аргумент будет типом более "узким", чем 'int', тогда объявляйте его как 'int'.

Есть несколько особых случаев, в которых эту методику трудно использовать. Например, если аргумент функции должен хранить тип системы `dev_t', то у вас проблемы, т.к. `dev_t' короче, чем `int', на некоторых компьютерах, но тем не менее вы не можете использовать `int', т.к. `dev_t' длиннее, чем `int', на некоторых компьютерах. Нет типа данных, который вы можете безопасно использовать на всех компьютерах в нестандартном определении. Единственный способ поддерживать нестандартный С и передавать подобные аргументы – это проверять длину `dev_t' с помощью Autoconf и выбирать тип аргумента в соответствии с ней. Это не должно составить проблемы.

Для целей поддержки до-стандартных компиляторов, не распознающих прототипы, вы можете захотеть использовать макрос препроцессора, например такой:

/*Объявите прототип для обобщённой внешней функции. */
#if defined (__STDC__) || defined (WINDOWSNT)
#define P_(proto) proto
#else
#define P_(proto) ()
#endif

3.5 Условная компиляция
===================

При поддержке параметров настроек, уже известных на момент компоновки вашей программы, мы предпочитаем использовать `if (... )', нежели условную компиляцию, поскольку это позволяет компилятору произвести более тщательную проверку всех возможных путей кода.

Например, напишите, пожалуйста:

if (HAS_FOO)
...
else
...

взамен:

#ifdef HAS_FOO
...
#else
...
#endif

Современный компилятор вроде GCC сгенерирует абсолютно одинаковый код в обоих случаях, и мы использовали подобные методики в нескольких проектах с хорошими результатами. Конечно, первый из указанных вариантов кода предполагает, что `HAS_FOO' определена как 0 или 1.

Хотя это не серебряная пуля, решающая все проблемы переносимости, и не всегда применимо, но следование этой политике может сэкономить разработчикам GCC много часов, а то и дней, в году.

В случае макросов, подобных функции, вроде `REVERSIBLE_CC_MODE' в GCC, которые нельзя просто так использовать в утверждениях `if( ...)', есть лёгкий обходной путь. Просто введите другой макрос `HAS_REVERSIBLE_CC_MODE', как в следующем примере:

#ifdef REVERSIBLE_CC_MODE
#define
HAS_REVERSIBLE_CC_MODE 1
#else
#define
HAS_REVERSIBLE_CC_MODE 0
#endif

4 Поведение всех программ

Эта глава описывает соглашения при написании больших программ. Также здесь описаны общие стандарты для сообщений об ошибках, интерфейса командной строки и библиотек.

4.1 Не-GNU стандарты
================

Проект GNU рассматривает стандарты других организаций как рекомендательные, но не обязательные. Мы оглядываемся на них, но не следуем безусловно. При разработке GNU-программ стоит использовать другие стандарты только если они объективно улучшат систему. В ином случае внедрять их не стоит.

В большинстве случаев следование стандартам удобно для пользователей – это означает, что их программы и скрипты будут более переносимыми. К примеру, GCC реализует почти все возможности из Стандарта C, как определено в стандарте. Иначе программисты на C были бы недовольны. А GNU утилиты по большей части следуют спецификациям POSIX.2; авторы скриптов и пользователи были бы недовольны, если бы наши программы были несовместимы.

Но мы не слепо следуем этим спецификациям – есть пункты, которые мы решили не выполнять, чтобы сделать систему GNU лучше для пользователей.

Например, стандарт С говорит, что почти все расширения С запрещены. Как глупо! GCC поддерживает множество расширений, некоторые из которых позже были включены в стандарт. Если вы хотите при их использовании получать сообщения об ошибке, как "положено" стандартом, то вы должны указать флаг '--pedantic', который нужен лишь затем, чтобы мы могли говорить, что "GCC следует стандарту на 100%".

POSIX.2 определяет, что 'df' и 'du' должны по умолчанию выводить размер в 512-байтных блоках. Но пользователи хотят 1-килобайтные блоки, поэтому мы сделали их по умолчанию. Если же вам нужно нелепое, но требуемое стандартом POSIX поведение, вы должны установить переменную окружения 'POSIXLY_CORRECT' (которую сначала хотели назвать 'POSIX_ME_HARDER').

GNU утилиты также отступают от спецификации POSIX.2, когда поддерживают длинные имена опций командной строки и смешивают опции с обычными параметрами. Эта маленькая несовместимость с POSIX не вызывает никаких проблем на практике, но очень удобна в использовании.

В частности, никогда не отказывайтесь от новой особенности и не удаляйте старую только потому, что стандарт говорит о ней как о "запрещенной" или "нерекомендуемой".

4.2 Написание качественных программ
=============================