Добавил:
ivanov666
Опубликованный материал нарушает ваши авторские права? Сообщите нам.
Вуз:
Предмет:
Файл:Система построения проектов CMake. Учебник.pdf
3.5. Инструменты разработки
честве выхода можно указывать в настройках только имена
файлов, перечисляя пути к ним в переменной окружения PATH
в системе, которая используется для разработки. Такой подход
не работает в случае использования Perl, для которого нужно
указывать полный путь. С другой стороны, использовать Perl
совместно с Doxygen приходится нечасто.
Другая похожая проблема заключается в том, что относительные пути ко входным файлам и каталогам, как и выходной каталог для системы Doxygen, интерпретируются по отношению к рабочему каталогу, в котором запускается инструмент.
Это затрудняет следование концепции построения вне каталога
проекта (файлы документации генерируются внутри каталога
исходных файлов). Можно указать путь к выходному каталогу
в настройках, однако это опять-таки приведёт к проблеме непереносимости проекта.
Выход из этой ситуации, который обычно рекомендуется в случае использования инструмента CMake, заключается
в том, что в файле настроек Doxygen вместо путей к инструментам и выходным файлам указываются конструкции вида
«@hимя_переменнойi@». Далее в описании проекта применяется
команда configure_file() (п. 2.10.1), которая, используя файл
настроек Doxygen в качестве шаблона, генерирует его окончательный вариант в каталоге построения. Для поиска инструментов используются модули CMake, описание которых приведено
далее.
Хотя этот метод работает, его использование не совсем
удобно: в каждом создаваемом файле настроек Doxygen нужно
381
3. Примеры использования пакетов
найти все места, где указываются пути, и записать туда конструкции с переменными CMake. Ниже будет продемонстрирован альтернативный способ решения проблемы. Его смысл заключается в копировании файла настроек в выходной каталог
и дозаписи в его конец нескольких строк с необходимыми путями. Файл настроек Doxygen (кроме комментариев) состоит
из строк следующего формата:
hимя_настройкиi = hзначениеi
Например, настройка с именем OUTPUT_DIRECTORY содержит путь к каталогу выходных файлов. В документации к системе Doxygen говорится о том, что из нескольких настроек с одинаковым именем в одном файле она учитывает только самую
последнюю. На этом и основан представленный здесь метод. Сами настройки каталогов в файле Doxygen можно вообще не заполнять.
Для реализации взаимодействия с системой Doxygen будут
необходимы следующие модули поиска CMake:
find_package(Doxygen)
Эта команда выполняет поиск пути к консольному генератору Doxygen, а также вспомогательной программе dot (если значение переменной DOXYGEN_SKIP_DOT не установлено в истину).
Результаты записываются в следующие переменные (табл. 3.8).
382
3.5. Инструменты разработки
Таблица 3.8
Переменные, заполняемые модулем поиска Doxygen
Переменная Значение
DOXYGEN_FOUND Истина, если исполняемый файл
Doxygen найден
DOXYGEN_EXECUTABLE Путь к программе Doxygen
DOXYGEN_VERSION Версия Doxygen
DOXYGEN_DOT_FOUND Истина, если исполняемый файл
dot найден
DOXYGEN_DOT_EXECUTABLE Путь к программе dot
find_package(HTMLHelp)
Этот модуль предназначен для поиска консольного компилятора hhc.exe, а также пути к заголовочному файлу и библиотеке HTMLHelp, которые используются в приложениях с поддержкой справки в этом формате. Результаты поиска записываются в следующие переменные (табл. 3.9).
Таблица 3.9
Переменные, заполняемые модулем поиска HTMLHelp
Переменная Значение
HTML_HELP_COMPILER Путь к программе hhc.exe
HTML_HELP_INCLUDE_PATH Путь к каталогу с заголовочным
файлом htmlhelp.h
383
3. Примеры использования пакетов
Окончание табл. 3.9
Переменная Значение
HTML_HELP_LIBRARY Путь к библиотеке htmlhelp.lib
find_package(
LATEXfCOMPONENTS hкомпонент1i ... hкомпонентnig)
Этот модуль предназначен для поиска инструментов,
используемых для подготовки документов в системе LaTeX.
Из комментариев в тексте модуля (FindLATEX.cmake) можно
сделать вывод, что, если в команде не указывать дополнительных компонент, будет найден только путь к инструменту latex.
На самом же деле текущая реализация этого модуля находит все
инструменты независимо от дополнительных аргументов команды find_package(). Возможные значения этих компонент
приведены в табл. 3.10.
Таблица 3.10
Дополнительные компоненты модуля поиска LaTeX
PDFLATEX XELATEX LUALATEX BIBTEX BIBER
MAKEINDEX XINDY DVIPS DVIPDF PS2PDF
PDFTOPS LATEX2HTML HTLATEX
Результаты поиска записываются модулем в следующие
переменные (табл. 3.11).
384
3.5. Инструменты разработки
Таблица 3.11
Переменные, заполняемые модулем поиска LaTeX
Переменная Значение
LATEX_FOUND Истина, если исполняемый
файл LaTeX и остальных инструментов найдены
LATEX_hкомпонентi_FOUND Истина, если файл компо-
нента найден
LATEX_COMPILER Путь к компилятору LaTeX
hкомпонентi_COMPILER Путь к файлу инструмента
find_package(Perl)
Этот модуль выполняет поиск интерпретатора Perl. Резуль-
таты записываются в следующие переменные (табл. 3.12).
Таблица 3.12
Переменные, заполняемые модулем поиска Perl
Переменная Значение
PERL_FOUND Истина, если исполняемый файл Perl
найден
PERL_EXECUTABLE Путь к файлу Perl
PERL_VERSION_STRING Версия найденного интерпретатора
(поддерживается в CMake начиная
с версии 2.8.8)
385
3. Примеры использования пакетов
ПРИМЕР
Пусть требуется реализовать поддержку создания документации приведённым выше способом.
Файл doxygen.cmake:
if(NOT DOXYGEN_EXECUTABLE)
find_package(Doxygen)
if(NOT DOXYGEN_FOUND)
message(
WARNING
"Could not find Doxygen on this system. You "
"can manually assign a path to it to "
"DOXYGEN_EXECUTABLE variable.")
return()
endif()
endif()
if(NOT HTML_HELP_COMPILER)
find_package(HTMLHelp)
if(NOT HTML_HELP_COMPILER)
message(
WARNING
"Could not find HTMLHelp compiler on this "
"system. You can manually assign a path to it "
"to HTML_HELP_COMPILER variable.")
endif()
endif()
386
if(NOT QHG_EXECUTABLE)
find_package(Qt5Core QUIET)
if(Qt5Core_FOUND)
get_property(
MOC_PATH
TARGET Qt5::moc
PROPERTY IMPORTED_LOCATION)
get_filename_component(
MOC_DIR "${MOC_PATH}" DIRECTORY)
find_program(
QHG_EXECUTABLE
3.5. Инструменты разработки
"qhelpgenerator"
HINTS "${MOC_DIR}"
DOC
"Qt help generator (qhelpgenerator) exec. path")
if(NOT QHG_EXECUTABLE)
message(
WARNING
"Found Qt5, but failed to find "
"qhelpgenerator program. You can manually "
"assign a path to it to QHG_EXECUTABLE "
"variable.")
endif()
else()
message(
WARNING
"Could not find Qt help generator on this "
387
3. Примеры использования пакетов
"system. If you have a Qt installation you can "
"add a path to it to CMAKE_PREFIX_PATH "
"variable. You can also manually assign "
"a path to qhelpgenerator program to "
"QHG_EXECUTABLE variable.")
endif()
endif()
if(NOT LATEX_COMPILER AND NOT MAKEINDEX_COMPILER)
find_package(LATEX COMPONENTS MAKEINDEX)
if(NOT LATEX_FOUND)
message(
WARNING
"Could not find LATEX on this system. You can "
"manually assign a path to latex executable to "
"LATEX_COMPILER variable and a path to "
"makeindex executable to MAKEINDEX_COMPILER "
"variable.")
endif()
endif()
if(NOT PERL_EXECUTABLE)
find_package(Perl)
if(NOT PERL_FOUND)
message(
WARNING
"Could not find Perl interpreter on this "
388
3.5. Инструменты разработки
"system. You can manually assign a path to it "
"to PERL_EXECUTABLE variable.")
endif()
endif()
set(DOC_DIR "${CMAKE_BINARY_DIR}/doc")
set(
VARS
# Doxygen name CMake name
OUTPUT_DIRECTORY DOC_DIR
HHC_LOCATION HTML_HELP_COMPILER
DOT_PATH DOXYGEN_DOT_EXECUTABLE
QHG_LOCATION QHG_EXECUTABLE
LATEX_CMD_NAME LATEX_COMPILER
MAKEINDEX_CMD_NAME MAKEINDEX_COMPILER
PERL_PATH PERL_EXECUTABLE
)
set(
CMDS
COMMAND
"${CMAKE_COMMAND}" -E copy
"${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile"
"${CMAKE_CURRENT_BINARY_DIR}/doc/Doxyfile")
list(LENGTH VARS N)
389
3. Примеры использования пакетов
foreach(I2 RANGE 1 ${N} 2)
math(EXPR I1 "${I2} - 1")
list(GET VARS ${I1} VAR_DOXYGEN)
list(GET VARS ${I2} VAR_CMAKE)
set(VALUE_CMAKE "${${VAR_CMAKE}}")
if(VALUE_CMAKE)
list(
APPEND CMDS
COMMAND
"${CMAKE_COMMAND}"
-E echo
"${VAR_DOXYGEN} = \"${VALUE_CMAKE}\"" >>
"${CMAKE_CURRENT_BINARY_DIR}/doc/Doxyfile")
endif()
endforeach()
add_custom_command(
OUTPUT
doc/Doxyfile
${CMDS}
MAIN_DEPENDENCY
Doxyfile
VERBATIM)
add_custom_target(
doc
390