CMake में Doxygen के साथ काम करें

हाल ही में मैंने स्रोत कोड के लिए प्रलेखन बनाए रखने और Doxygen और CMake का उपयोग करके इसे बनाने के बारे में सोचा। एक अप्रिय समस्या का तुरंत सामना करना पड़ा। तथ्य यह है कि मेरी परियोजनाओं में मैं निम्नलिखित संरचना का उपयोग करता हूं:

  निर्माण /
   src /
   CMakeLists.txt
   Doxyfile 

असेंबली, मेरे मामले में, बिल्ड डायरेक्टरी में होती है। लेकिन विधानसभा कहीं से भी की जा सकती है। इसलिए, यदि आप असेंबली डायरेक्टरी बदलते हैं, तो डॉक्यूमेंटेशन एकत्र नहीं किया जाएगा, क्योंकि Doxygen को वह स्रोत नहीं मिलेगा जिसके लिए आपको यह बहुत दस्तावेज़ीकरण एकत्र करने की आवश्यकता है। तब मैंने सोचा कि सीएमके और डॉकजीन के साथ मिलकर असेंबली असेंबली का प्रबंधन कैसे किया जाए? क्या होगा यदि मुझे कई प्रकार के प्रलेखन प्राप्त करने की आवश्यकता है: उपयोगकर्ता और डेवलपर? Doxygen के लिए दो विन्यास फाइल रखें? मुझे यह विकल्प पसंद नहीं है, क्योंकि फाइलें केवल एक ENABLED_SECTIONS चर के मूल्य में भिन्न होंगी। नीचे मैं इस बारे में बात करूंगा कि आप वहां असेंबली ऑफ मैनेजमेंट का प्रबंधन कैसे कर सकते हैं।

विधि एक (CONFIGURE_FILE)

इंटरनेट पर और CMake स्रोत में, आप CMake में Doxygen के साथ काम करने के लगभग निम्नलिखित तरीके पा सकते हैं।

FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .

1. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .
2. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .
3. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .
4. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .
5. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .
6. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .
7. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .
8. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .

FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .

ट्रिक ऊपर कोड की लाइनों 3 और 4 में है। आइए देखें कि उनमें क्या होता है ADD_CUSTOM_TARGET कमांड, फ़ाइल को पहले पैरामीटर द्वारा दूसरे पैरामीटर द्वारा स्थानांतरित फ़ाइल में कॉपी करती है, स्रोत पाठ में फॉर्म @ VAR @ या $ {VAR} के चर की जगह लेती है, जो आपके सीएमके फाइलों में परिभाषित संबंधित चर के मूल्यों के साथ है ( प्रलेखन दस्तावेज में ADD_CUSTOM_TARGET के बारे में और पढ़ें)। यानी यदि doxygen.conf.in फ़ाइल में हमारे पास INPUT = @ DOXYGEN_INPUT @ की एक पंक्ति है, तो doxygen.conf फ़ाइल में इसे प्रतिस्थापित किया जाएगा और @ DOXYGEN_INPUT के बजाय चर CMAKE_SOURCE_DIR के मान को प्रतिस्थापित किया जाएगा (देखें पंक्ति में देखें)

उपरोक्त विधि किसी भी तरह से दस्तावेज़ीकरण कोडांतरण की प्रक्रिया का प्रबंधन करना संभव बनाती है और अधिकांश परियोजनाओं के लिए काफी उपयुक्त है। फिर भी, मेरी विनम्र राय, कमियों में कई गंभीर हैं:

1. वे सभी चर जिन्हें हम नियंत्रित करना चाहते हैं उन्हें पहले से @ VAR @ या $ {VAR} फॉर्म में सेट करना होगा।
2. हम इसके लिए Doxywizard का उपयोग नहीं कर सकते। सामान्य तौर पर, आप Doxywizard के बारे में भूल सकते हैं, क्योंकि फ़ाइल प्रारूप इसके साथ असंगत हो जाता है। Doxywizard से फ़ाइल को फिर से सहेजना हमारी सभी सेटिंग्स को तोड़ देगा ।
3. अच्छी तरह से और सबसे महत्वपूर्ण बात यह है कि इस तरह की कॉन्फ़िगरेशन फ़ाइल स्वयं Doxygen के साथ असंगत हो जाती है और CMake के बिना हम इसका उपयोग नहीं कर पाएंगे और सही दस्तावेज प्राप्त कर पाएंगे।

दूसरा तरीका (मेरा विकल्प)

ऊपर सूचीबद्ध कमियों के बारे में जानने के लिए, मैंने प्रलेखन असेंबली प्रक्रिया को नियंत्रित करने के लिए अपना मैक्रोज़ लिखने का फैसला किया।

1. मैक्रो (CONFIGURE_DOXYGEN_FILE DOXYGEN_CONFIG_FILE FILE_NAME_SUFFIX)
2. IF (EXISTS $ {PROJECT_SOURCE_DIR} / $ {DOXYGEN_CONFIG_FILE})
3. फ़ाइल (REMOVE $ {CMAKE_CURRENT_BINARY_DIR} / doxy - $ {FILE_NAME_SUFFIX} .conf
4. फ़ाइल (पढ़ें $ {PROJECT_SOURCE_DIR} / $ {DOXYGEN_CONFIG_FILE} DOXYFILE_CONTENTS)
5. STRING (REGEX REPLACE ";" " \\\\ ;" DOXYFILE_CONTENTS "$ {DOXYFILE_CONTENTS}" )
6. STRING (REGEX REPLACE "\ n" "; DOXYFILE_LINES " $ {DOXYFILE_CONTENTS} " )
7. सूची (LENGTH DOXYFILE_LINES ROW)
8. MATH (EXOW ROW "$ {ROW} - 1" )
9. FOREACH (I RANGE $ {ROW})
10. सूची (DOXYFILE_LINES $ {I} LINE प्राप्त करें)
11. IF (LINE STRGREATER "" )
12. STRING (REGEX MATCH "^ [a-zA-Z] ([^]) +" DOXY_PARAM $ {LINE})
13. IF (निर्धारित बॉक्स _ _ $ {DOXY_PARAM})
14. STRING (REGEX REPLACE "= ([^ \ n]) + " = "$ {DOXY _ $ {DOXY_PARAM}}" LINE $ {LINE})
15. ENDIF (निर्धारित बॉक्स _ $ {DOXY_PARAM})
16. ENDIF ()
17. फ़ाइल (APPEND $ {CMAKE_CURRENT_BINARY_DIR} / doxy - $ {FILE_NAME_SUFFIX} .conf "$ {LINE} \ n" )।
18. ENDFOREACH ()
19. ELSE ()
20. संदेश (SEND_ERROR "Doxygen कॉन्फ़िगरेशन फ़ाइल '$ {DOXYGEN_CONFIG_FILE}' नहीं मिली। प्रलेखन उत्पन्न नहीं होगा" )
21. ENDIF ()
22. ENDMACRO (CONFIGURE_DOXYGEN_FILE)

* इस सोर्स कोड को सोर्स कोड हाइलाइटर के साथ हाइलाइट किया गया था।

1. मैक्रो (ADD_DOCUMENTATION TARGET DOXYGEN_CONFIG_FILE)
2. FIND_PACKAGE (Doxygen)
3. यदि (DOXYGEN_FOUND)
4. CONFIGURE_DOXYGEN_FILE ($ {DOXYGEN_CONFIG_FILE} $ {TARGET})
5. ADD_CUSTOM_TARGET ($ {TARGET} COMMAND $ {DOXYGEN_EXECUTABLE} $ {CMAKE_CURRENT_BINARY_DIR} / doxy - $ [TARGET} .conf)
6. ELSE (DOXYGEN_FOUND)
7. MESSAGE (स्थिति "Doxygen नहीं मिला। प्रलेखन उत्पन्न नहीं होगा" )
8. ENDIF (DOXYGEN_FOUND)
9. ENDMACRO (ADD_DOCUMENTATION)

* इस सोर्स कोड को सोर्स कोड हाइलाइटर के साथ हाइलाइट किया गया था।

उपयोग करने का सबसे आसान तरीका

1. सेट (DOXY_OUTPUT_LANGUAGE "रूसी" )
2. सेट (DOXY_INPUT $ {PROJECT_SOURCE_DIR})
3. ADD_DOCUMENTATION (डॉक्टर Doxyfile)

* इस सोर्स कोड को सोर्स कोड हाइलाइटर के साथ हाइलाइट किया गया था।

गौर कीजिए कि यहां क्या हो रहा है। CONFIGURE_DOXYGEN_FILE मैक्रो कुछ हद तक CMake config_file कमांड के समान है। यह Doxygen कॉन्फ़िगरेशन फ़ाइल की एक प्रति बनाता है, लेकिन इसके लिए किसी विशेष परिवर्तन की आवश्यकता नहीं होती है। वह विन्यास फाइल लाइन को लाइन से पढ़ती है, Doxygen पैरामीटर की तलाश करती है और जांचती है कि क्या CMake में समान नाम और DOXY_ उपसर्ग (लाइन 13) के साथ कोई पैरामीटर है। यदि ऐसा कोई पैरामीटर मौजूद है, तो इसका मान Doxygen पैरामीटर (लाइन 14) के मान के रूप में प्रतिस्थापित किया जाता है।

इस प्रकार हम CMake में किसी भी Doxygen के मापदंडों में हेरफेर कर सकते हैं और साथ ही Doxygen और Doxywizard के साथ स्रोत कॉन्फ़िगरेशन फ़ाइल की संगतता को नहीं खो सकते हैं । फ़ाइल की परिणामी प्रतिलिपि पूरी तरह से मूल की संरचना को संरक्षित करती है।

खैर, निष्कर्ष में, उपयोग का मामला अधिक जटिल है। उपयोगकर्ता और डेवलपर प्रलेखन की एक साथ असेंबली कैसे दिख सकती है, इसका एक प्रकार। इसके लिए, स्रोत कोड में आपको \ if कमांड का उपयोग करके उपयुक्त अनुभागों को चिह्नित करना चाहिए

1. सेट (DOXY_OUTPUT_LANGUAGE "रूसी" )
2. सेट (DOXY_INPUT $ {PROJECT_SOURCE_DIR})
4. सेट (DOXY_ENABLED_SECTIONS "user_sec" )
5. सेट (DOXY_OUTPUT_DIRECTORY "$ {CMAKE_CURRENT_BINARY_DIR} / doc-user" )
6. ADD_DOCUMENTATION (user_doc Doxyfile)
8. सेट (DOXY_ENABLED_SECTIONS "developer_sec" )
9. सेट (DOXY_OUTPUT_DIRECTORY "$ {CMAKE_CURRENT_BINARY_DIR} / doc-developer" )
10. ADD_DOCUMENTATION (developer_doc Doxyfile)
12. ADD_CUSTOM_TARGET (doc DEPENDS user_doc developer_doc)

* इस सोर्स कोड को सोर्स कोड हाइलाइटर के साथ हाइलाइट किया गया था।