हेडर फाइलें या फ्रीबी प्रलेखन संकलन

यह लेख किसके लिए है?

शायद ही अनुभवी C ++ डेवलपर्स को इस लेख में कुछ नया और दिलचस्प मिलेगा। अधिकतम केले की टीम
gcc -c -x c++ -I ./ */*/*/*/*.h
जो वे पहले से ही जानते हैं।
लेकिन अगर आप एक शुरुआती डेवलपर हैं, या सिर्फ पहली बार अपनी परियोजना के लिए प्रलेखन का निर्माण करते हैं, या इसे एक बार आज़माएं, लेकिन जब आप उस बकवास को देखते हैं जो उत्पन्न हुआ, तो इसे हटा दें और इसे एक बुरे सपने की तरह भूल जाएं, बिल्ली का स्वागत करें, सबसे अधिक आपको मिलेगा। फिर उपयोगी विचारों के एक जोड़े।

परिचय

C ++ प्रोग्रामिंग मुख्य रूप से मौजूदा कोड का विश्लेषण है।
अब कई वर्षों से, मैं एक सिमुलेशन प्रणाली के विकास में भाग ले रहा हूं। विकास महान और शक्तिशाली पर किया जाता है। और, मुझे कहना होगा कि, यह परियोजना लंबे समय से सी ++ में नहीं लिखी गई है क्योंकि मैक्रोज़ की अपनी बोली में (नीचे यह स्पष्ट हो जाएगा कि यह क्यों महत्वपूर्ण है)। मुझे लगता है कि यह स्थिति कई सी ++ डेवलपर्स से परिचित है।

जब मैं इस परियोजना का अध्ययन करना शुरू कर रहा था, तो उन्होंने तुरंत मुझे डॉक्सीजन का उपयोग करके इस पर प्रलेखन बनाने की सलाह दी। लेकिन किसी कारण से, इस उपकरण के साथ दोस्ती से काम नहीं चला, और अगली बार मुझे इसके बारे में पहले से ही वर्षों बाद याद आया।

प्रागितिहास

समय बीतता गया, मेरा व्यावसायिकता (जैसा कि मुझे आशा है) बढ़ता गया, परियोजना विकसित हुई और मैं पुस्तकालय में व्यवस्था बहाल करना चाहता था, जिस पर सक्रिय रूप से शासन किया गया था। यहाँ आदेश से मतलब है कि एक हेडर फ़ाइल = एक इकाई (या कई छोटी और बारीकी से संबंधित) की अवधारणा, साथ ही सभी फ़ाइलों को तीन प्रकारों - हेडर, आंतरिक और स्रोत - क्रमशः * .h, * .inl, * .cpp में अलग करना। इसके अलावा, अलगाव को इस तरह से किया जाना चाहिए कि हेडर फ़ाइलों में वर्ग के एक भी सदस्य फ़ंक्शन की कोई परिभाषा नहीं है, और उन सभी को या तो सीपीपी फ़ाइलों या इनएल फ़ाइलों में किया गया था। इसके अलावा, सभी मॉड्यूल कोड को एक एकल मानक के अनुसार स्वरूपित किया जाना चाहिए, और, सबसे दिलचस्प बात यह है कि अधिकांश संस्थाओं को विशेष डॉक्सिजन कमांड (\ इंटरफ़ेस, \ वर्ग, \ todo, \ संक्षिप्त, \ enum और अन्य) का उपयोग करके टिप्पणी की जानी चाहिए। ।

समस्या

जल्दी से नहीं कहा। मारे गए शाम के कुछ हफ्तों के बाद, पागल काम पूरा हो गया है! कोड सुंदर है ताकि थोड़ा आंसू आए।
और सिस्टम के मेरे (उस समय पहले से ही प्रिय) मॉड्यूल के विवरण के साथ मेरे लिए सबसे सुंदर और सही दस्तावेज बनाने के लिए डॉक्सीजेन का इंतजार करते हुए कुर्सी पर बैठने का समय आ गया है। और डूबते दिल के साथ
cd Project/doc
doxygen project-doxyfile
cd html/
./index.html
हालांकि, जो मुझे दिखाई दिया, उसे हल्के ढंग से, कचरा डालने के लिए। Doxygen ने खुलकर धोखा दिया: आरेख अधूरे हैं, namepace'empty, मैक्रोज़ मुझे फ़ंक्शन देने की कोशिश कर रहे हैं, सामान्य तौर पर, सब कुछ नहीं गिन सकते ... लेकिन प्रारंभिक विश्लेषण से पता चला कि उन्हें मैक्रोज़ (सभी पर्पस ', स्मार्ट पॉइंटर्स (खुद का उत्पादन, वैसे) समझ नहीं आया था) और बहुत कुछ एक और मैक्रोज़ का उपयोग करके सेट किया गया था)।

विकल्प में समाधान PREDEFINED?

पहली चीज जो संदेह के घेरे में आई, वह थी डॉक्सीजन सेटिंग्स। ENABLE_PREPROCESSING, MACRO_EXPANSION, EXPAND_ONLY_PREDEF, SEARCH_INCLUDES और INCLUDE_PATH जैसे विकल्पों की दोबारा जाँच की गई है। लेकिन सेटिंग्स तार्किक लग रही थीं, और मैक्रोज़ को सही ढंग से माना नहीं जाना शुरू हुआ। तब PREDEFINED विकल्प चलन में आया, हालाँकि इसने इस सवाल का जवाब नहीं दिया कि "डॉक्सीजन गड़बड़ क्यों करता है?", लेकिन इसने उसे आवश्यक मैक्रो की व्याख्या करने की अनुमति दी। थोड़ी देर के लिए समस्या का समाधान था। लेकिन यह तथ्य कि इस विकल्प में लगातार नए मैक्रो को जोड़ना आवश्यक था, बहुत निराशाजनक था और डॉक्स ऑक्सीजन का अध्ययन जारी रखने के लिए मजबूर किया गया था।

समस्या कोड में है!

मैंने लंबे समय तक डॉक्सिजन के व्यवहार के बारे में सोचा और इसे गूगल किया। और एक बार उसने भी खुद को ज़न्नत के पवित्र स्थान को खोजने और उसे ठीक करने के बारे में सोचा था, जिसने उसे इरोस के प्रसंस्करण से रोका था :)

लेकिन समय में मैं रुक गया, क्योंकि मैंने इसके और संकलक के बीच अंतर को समझा। उनके लक्ष्य बहुत अलग हैं (और डॉक्सिजेन किसी भी तरह से अधिक जटिल है), क्योंकि उन्हें न केवल सीपीपी फाइलों को समझने की जरूरत है, बल्कि हेडर फाइलों के साथ भी ऐसा ही करना है, ताकि वह इसे सभी को सुंदर रूप से उपयोगकर्ता को दिखा सकें, अर्थात फ़ाइल द्वारा। और यहाँ कुछ दिलचस्प है जो मैंने पहले नहीं सोचा था: कम्पाइलर को हेडर फ़ाइलों में कोई दिलचस्पी नहीं है, यह एक "अनुवाद इकाई" प्राप्त करता है, या पहले से काम किए गए #include निर्देशों के साथ एक प्रीप्रोसेसर का आउटपुट। मैं अपने आप को इस तरह से इसे फिर से लिखने की अनुमति देता हूं - कंपाइलर केवल एक इकाई के संदर्भ में, अप्रत्यक्ष रूप से हेडर फ़ाइलों से संबंधित है। और इसे इसी संदर्भ में संकलित करता है। इसलिए निराशाजनक निष्कर्ष - हेडर फ़ाइल अपने आप में गलत हो सकती है, लेकिन इसके उपयोग के संदर्भ में सही हो जाएगी, और संकलक आपको इसके बारे में कुछ भी नहीं बताएगा!

लेकिन doxygen के साथ, यह काम नहीं करता है - हेडर फ़ाइल का विश्लेषण स्रोत कोड के साथ एक स्टैंड-अलोन, आत्मनिर्भर दस्तावेज़ के रूप में किया जाता है। और अगर इसमें इस्तेमाल की गई संस्थाओं की घोषणाओं का अभाव है (जो इस हेडर फ़ाइल का उपयोग करने के संदर्भ में दिखाई देती है), तो डॉक्सीजन को गलत माना जाएगा। और यह बहुत संभावना है कि यह इस बीमारी थी जो हमारी परियोजना को प्रभावित करती है।

तो कम्पाइलर के लिए मायावी, हेडर फाइल में किस तरह की त्रुटि है? यह उन फ़ाइलों का #include निर्देश नहीं है जहां कुख्यात मैक्रोज़ को परिभाषित किया गया है। यानी cpp-files को संकलित करते समय, सभी परिभाषाएँ कुछ राउंडअबाउट तरीके से वर्तमान अनुवाद इकाई में गिर गईं, और "समस्या" हेडर फ़ाइल के माध्यम से नहीं। इस खोज के बाद, हमारी टीम में एक बैठक आयोजित की गई थी, जिसमें मुख्य एजेंडा पर सवाल था "और वास्तव में इसके साथ क्या करना है?" सवाल इस तथ्य के पक्ष में हल किया गया था कि इस तरह के व्यवहार - सभी आवश्यक समावेशन की अनुपस्थिति - एक गलती है। मुख्य तर्क काफी सरल है - हेडर फ़ाइल को संभवतः कहीं भी शामिल किया जा सकता है, और इसलिए यह इतना आत्मनिर्भर होना चाहिए कि यह संकलित हो।

समाधान "हेडर फ़ाइलों का संकलन" है

यह वह जगह है जहाँ "हेडर फ़ाइलों को संकलित करने" का सवाल आया था।
इस घटना का बिंदु संकलक को सभी हेडर फ़ाइलों का विश्लेषण करके उन्हें स्रोत (* .cpp) फ़ाइलों के संदर्भ में जोड़े बिना और त्रुटियों की रिपोर्ट करना है। और फिर, यदि वे तय हो गए हैं, तो सभी आरेखों और अधिक के साथ प्रोजेक्ट प्रलेखन को ठीक से बनाने के लिए डॉक्सीजन के पास कोई बहाना नहीं होना चाहिए।

अब हमारी टीम में उपयोग किए गए कंपाइलर के बारे में सीधे बात करने का समय है।
ऐतिहासिक कारणों से, यह एमएस विज़ुअल स्टूडियो है, यह मानक 2008 जितना है। लेकिन इस कहानी के अंत से ठीक पहले, GNU / Linux के तहत सिस्टम के कंप्यूटिंग कोर के अनुवाद की परियोजना सफलतापूर्वक पूरी हो गई थी। और स्वाभाविक रूप से, इस वातावरण में, मुझे जीसीसी संकलक, संस्करण 4.6 के रूप में चुना गया था।
और मैंने उन्हें अनुरोधों के साथ पीड़ा देना शुरू कर दिया, वे कहते हैं कि मुझे सुर्खियों में लाना है। और उसने लंबे समय तक विरोध किया ... जब तक वह अंदर नहीं गया।
उनके आदमी के एक विचारशील पढ़ने ने मुझे -I विकल्प दिखाया, जिसके साथ जीसीसी आप उन मार्गों को निर्दिष्ट कर सकते हैं जहां से उद्धरणों के लिए खोज की जा सकती है।
यहां, एक महत्वपूर्ण तथ्य पर ध्यान दिया जाना चाहिए, हमारी परियोजना में हमारे पास लंबे समय तक (और बहुत सफलतापूर्वक) नियम का पालन किया गया है "परियोजना की जड़ से समावेशन में फ़ाइल का पथ इंगित करें।" इस अनुशासन ने एकल -I विकल्प के साथ दूर करना संभव बना दिया।
फिर यह सभी प्रोजेक्ट हेडर फ़ाइलों में gcc इनपुट के लिए सबमिट करना शेष है। लेकिन यहाँ इनपुट के रूप में पाइपलाइन के माध्यम से ls कमांड के आउटपुट को स्वीकार करने के लिए gcc की अनिच्छा के कारण कुछ अड़चन थी। लेकिन समाधान और भी अधिक तुच्छ हो गया, हस्तांतरित मुखौटा द्वारा पहले से ही इनपुट फ़ाइलों के लिए खोजा गया।
तो टीम
g++ -I ./ */*/*/*/*.h */*/*/*.h */*/*.h
पूरी तरह से सभी पुस्तकालय हेडर फ़ाइलों को मान्य करता है।
अगली बार जीसीसी ने विरोध करना शुरू किया, अगर इसे इनपुट के रूप में * .inl फाइलें दी गईं। विकल्प -c (लिंक किए बिना केवल संकलन) और -x c ++ (स्पष्ट रूप से प्रोग्रामिंग भाषा सेट करना) ने मदद की।
अंतिम कमांड हेडर को सत्यापित करने के लिए प्रयोग किया जाता है (* .inl फाइलें जो हमने अकेले छोड़ने का फैसला किया है) फाइलें:
gcc -c -x c++ -I ./ */*/*/*/*.h */*/*/*.h */*/*.h

खैर, यह त्रुटियों को ठीक करने और डॉक्सीजेन का उपयोग करने के लिए बना हुआ है।

और, सामान्य तौर पर, निश्चित रूप से, आप कुछ सुधार कर सकते हैं, उदाहरण के लिए, यहाँ पेंच सेंकें, लेकिन इस पोस्ट का मुख्य विचार यह है कि डॉक्सीजन के प्रतीत होने वाले अजीब व्यवहार का मुकाबला करने के लिए "हेडर फाइलें संकलित करें"। इसलिए मैं यहां रुकूंगा जब तक कि मैं अंतिम सबसे मेहनती पाठक का टायर नहीं;)

निष्कर्ष के बजाय

और वास्तव में, पोस्ट को "... या फ्रीबी प्रलेखन" क्यों कहा जाता है।
हां, यह सिर्फ इतना है कि कोड में डॉक्सिज़न की टिप्पणी की एक पंक्ति नहीं हो सकती है, लेकिन फिर भी आप इस पर सभी प्रकार के आरेखों के साथ दस्तावेज़ बना सकते हैं, जो एक नई परियोजना का अध्ययन करते समय बहुत सहायक हो सकते हैं। अर्थात्, प्रलेखन का सुविधाजनक निर्माण (सुविधाजनक नेविगेशन और आरेख के साथ) नए छात्रों (और यह सब एक तकनीकी विश्वविद्यालय में होता है) को बहुत बड़े और जटिल प्रणाली का अध्ययन करने के लिए आसान बनाने के लिए माना जाता था और हमारी परियोजना में डॉक्सीजीन का उपयोग करने का मूल लक्ष्य था।

स्वाभाविक रूप से, टिप्पणियों में मुझे रचनात्मक आलोचना, सुधार, मेरी मामूली टेढ़ी टीमों के जोड़ और प्रश्नों की प्रतीक्षा है।