Стандартные цели для пользователей

Все программы GNU должны иметь следующие цели в своих файлах Make:

‘all’

Компилирует всю программу. Это должна быть целевая установка по умолчанию. Эта цель не должна перестраивать файлы документации; файлы Info обычно должны быть включены в дистрибутив, а файлы DVI (и другие форматы документации) должны создаваться только при явном запросе.

По умолчанию правила Make должны компилировать и линковать с ‘-g’, чтобы исполняемые программы имели символы отладки. В противном случае вы оказываетесь беззащитными перед ошибками, а воспроизведение с чистой сборкой часто бывает непростым.

‘install’

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

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

Если возможно, напишите правило цели install, чтобы оно не изменяло ничего в каталоге, где была построена программа, при условии, что ‘make all’ только что было выполнено. Это удобно для построения программы под одним именем пользователя и установки под другим.

Команды должны создавать все каталоги, в которых должны быть установлены файлы, если они еще не существуют. Это включает в себя каталоги, указанные как значения переменных prefix и exec_prefix, а также все необходимые подкаталоги. Один из способов сделать это — с помощью цели installdirs, как описано ниже.

Используйте ‘-’ перед любой командой для установки страницы руководства, чтобы make игнорировал любые ошибки. Это в случае, если на системах нет установленной системы документации Unix man page.

Способ установки файлов Info — скопировать их в $(infodir) с помощью $(INSTALL_DATA) (см. Переменные команд), а затем запустить программу install-info, если она есть. install-info — программа, которая редактирует файл Info dir, чтобы добавить или обновить запись в меню для данного файла Info; она является частью пакета Texinfo.

Вот пример правила установки файла Info, который также пытается обрабатывать некоторые дополнительные ситуации, такие как install-info отсутствует.

do-install-info: foo.info installdirs
        $(NORMAL_INSTALL)
# Prefer an info file in . to one in srcdir.
        if test -f foo.info; then d=.; \
         else d="$(srcdir)"; fi; \
        $(INSTALL_DATA) $$d/foo.info \
          "$(DESTDIR)$(infodir)/foo.info"
# Run install-info only if it exists.
# Use 'if' instead of just prepending '-' to the
# line so we notice real errors from install-info.
# Use '$(SHELL) -c' because some shells do not
# fail gracefully when there is an unknown command.
        $(POST_INSTALL)
        if $(SHELL) -c 'install-info --version' \
           >/dev/null 2>&1; then \
          install-info --dir-file="$(DESTDIR)$(infodir)/dir" \
                       "$(DESTDIR)$(infodir)/foo.info"; \
        else true; fi

При написании цели install, вы должны разделить все команды на три категории: обычные, предварительные команды и послеустановочные команды. См. Категории команд установки.

‘install-html’

‘install-dvi’

‘install-pdf’

‘install-ps’

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

Когда у вас много файлов документации для установки, мы рекомендуем избегать коллизий и беспорядка, организовав установку этих целей в подкаталогах соответствующего каталога установки, например, htmldir. Например, если ваш пакет имеет несколько руководств, и вы хотите установить HTML-документацию с множеством файлов (например, выходной режим «split» от makeinfo --html), вы обязательно захотите использовать подкаталоги, иначе два узла с одинаковым именем в разных руководствах перезапишут друг друга.

Пожалуйста, сделайте эти цели install-format вызовут команды для цели format, например, сделав format зависимостью.

‘uninstall’

Удаляет все установленные файлы — копии, созданные целями ‘install’ и ‘install-*’.

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

Команды удаления делятся на три категории, как и команды установки. См. Категории команд установки.

‘install-strip’

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

install-strip:
        $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
                install

Но если пакет устанавливает скрипты наряду с реальными исполняемыми файлами, цель install-strip не может просто обратиться к цели install; она должна удалять исполняемые файлы, но не скрипты.

install-strip не должен удалять исполняемые файлы в каталоге сборки, которые копируются для установки. Он должен удалять только копии, которые установлены.

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

‘clean’

Удаляет все файлы в текущем каталоге, которые обычно создаются при построении программы. Также удаляются файлы в других каталогах, если они созданы этим файлом make. Однако не удаляются файлы, которые записывают конфигурацию. Также сохраняются файлы, которые могли быть созданы при построении, но обычно не создаются, поскольку они поставляются с дистрибутивом. Нет необходимости удалять родительские каталоги, которые были созданы с помощью ‘mkdir -p’, так как они могли существовать и раньше.

Удалите файлы .dvi, если они не входят в дистрибутив.

‘distclean’

Удаляет все файлы в текущем каталоге (или созданные этим файлом make), созданные при конфигурации или построении программы. Если вы распаковали исходный код и построили программу без создания других файлов, ‘make distclean’ должно оставить только файлы, которые были в дистрибутиве. Однако нет необходимости удалять родительские каталоги, которые были созданы с помощью ‘mkdir -p’, так как они могли существовать и раньше.

‘mostlyclean’

Как ‘clean’, но может отказаться от удаления нескольких файлов, которые обычно пользователи не хотят перекомпилировать. Например, цель ‘mostlyclean’ для GCC не удаляет libgcc.a, потому что его перекомпиляция редко необходима и занимает много времени.

‘maintainer-clean’

Удаляет почти всё, что можно восстановить с помощью этого файла Make. Это обычно включает в себя всё, что удаляется с помощью distclean, плюс больше: файлы исходного кода C, сгенерированные Bison, таблицы тегов, файлы Info и так далее.

Причина, почему мы говорим «почти всё» состоит в том, что выполнение команды ‘make maintainer-clean’ не должно удалять configure, даже если configure можно пересоздать, используя правило в файле Makefile. Более общим образом, ‘make maintainer-clean’ не должно удалять ничего, что должно существовать для запуска configure и последующей сборки программы. Также нет необходимости удалять родительские каталоги, созданные с помощью ‘mkdir -p’, так как они могли существовать и раньше. Это единственные исключения; maintainer-clean должно удалять все остальное, что можно перестроить.

Цель ‘maintainer-clean’ предназначена для использования системным администратором пакета, а не обычными пользователями. Вам могут понадобиться специальные инструменты для восстановления некоторых файлов, которые удаляет ‘make maintainer-clean’. Поскольку эти файлы обычно включаются в дистрибутив, мы не заботимся о том, чтобы сделать их легкими для восстановления. Если вам нужно повторно распаковать весь дистрибутив, не вините нас.

Чтобы помочь пользователям понять это, команды для специальной цели maintainer-clean должны начинаться с этих двух:

@echo 'This command is intended for maintainers to use; it'
@echo 'deletes files that may need special tools to rebuild.'

‘TAGS’

Обновляет таблицу тегов для этой программы.

‘info’

Генерирует необходимые файлы Info. Лучший способ написания правил — следующий:

info: foo.info

foo.info: foo.texi chap1.texi chap2.texi
        $(MAKEINFO) $(srcdir)/foo.texi

Вы должны определить переменную MAKEINFO в файле Makefile. Она должна запускать программу makeinfo, которая входит в дистрибутив Texinfo.

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

‘dvi’

‘html’

‘pdf’

‘ps’

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

Вот пример правила генерации файлов DVI из Texinfo:

dvi: foo.dvi

foo.dvi: foo.texi chap1.texi chap2.texi
        $(TEXI2DVI) $(srcdir)/foo.texi

Вы должны определить переменную TEXI2DVI в файле Makefile. Она должна запускать программу texi2dvi, которая входит в дистрибутив Texinfo. (texi2dvi использует TeX для реальной работы по форматированию. TeX не входит в дистрибутив Texinfo.) В качестве альтернативы, запишите только зависимости и позвольте GNU make предоставить команду.

Вот другой пример, этот для генерации HTML из Texinfo:

html: foo.html

foo.html: foo.texi chap1.texi chap2.texi
        $(TEXI2HTML) $(srcdir)/foo.texi

Опять же, вы бы определили переменную TEXI2HTML в файле Makefile; например, она могла бы запустить makeinfo --no-split --html (makeinfo входит в дистрибутив Texinfo).

‘dist’

Создайте архивный файл tar для этой программы. Файлы в архиве должны начинаться с подкаталога, имя которого совпадает с именем пакета, для которого он предназначен. Это имя может включать номер версии.

Например, распакованный архив tar для GCC версии 1.40 находится в подкаталоге gcc-1.40.

Самый простой способ сделать это — создать соответствующим образом названный подкаталог, использовать ln или cp для установки нужных файлов в него, а затем tar этот подкаталог.

Архив tar сжимается с помощью gzip. Например, фактический дистрибутивный файл для GCC версии 1.40 называется gcc-1.40.tar.gz. Также можно поддерживать и другие свободные форматы сжатия.

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

‘check’

Выполнить самотестирование (если оно имеется). Пользователь должен скомпилировать программу перед запуском тестов, но устанавливать её необязательно; вы должны написать самотесты так, чтобы они работали при компиляции программы, но без её установки.

Ниже приведены рекомендуемые условные имена для программ, в которых они полезны.

installcheck

Выполнить тесты установки (если они имеются). Пользователь должен скомпилировать и установить программу перед запуском тестов. Не следует полагать, что $(bindir) находится в пути поиска.

installdirs

Полезно добавить цель с именем ‘installdirs’ для создания каталогов, куда устанавливаются файлы, и их родительских каталогов. Для этого удобен скрипт mkinstalldirs, который можно найти в пакете Gnulib. Можно использовать правило такого вида:

# Make sure all installation directories (e.g. $(bindir))
# actually exist by making them if necessary.
installdirs: mkinstalldirs
        $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
                                $(libdir) $(infodir) \
                                $(mandir)

или, если вы хотите поддерживать DESTDIR (настоятельно рекомендуется),

# Make sure all installation directories (e.g. $(bindir))
# actually exist by making them if necessary.
installdirs: mkinstalldirs
        $(srcdir)/mkinstalldirs \
            $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
            $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
            $(DESTDIR)$(mandir)

Это правило не должно изменять каталоги, в которых выполняется компиляция. Оно должно только создавать каталоги установки.