Как процедирате когато искате в проекта на даден софтуерен продукт да добавите разни странични данни - документация например?
Едното масово срещано явление е анотиране на кода с разни таг-ове, най-често в коментарите (доксиген-а).
Контекстът на питането ми е че искам да мога да закача към определени точки в кода "хиперлинк-ове"/URL-и (примерно) с разгърната информация.
Конкретните ми търсения имат лека връзка с предишната тема "нещо като syslog?" - имаме точка в кода, в която софтуера прави някаква проверка (условие) и реагира - например вдига "аларма". Тази аларма (грешка) трябва да се разпише детайлно и това описание да се "движи" в синхрон с кода - т.е. съзаването на нова ревизия на сорса да може да добави/промени/махне някаква такава грешка. Или с други думи, от кода трябва да може да се "извлече" тази инфомация, и то точно от определен версия на сорса, и определена билд конфифурация "#define EXTENDED_FUNC_ENABLE 1" например.
При доксигена идеята е всичката тази мета-информация да се закачи към сорса директно - в самия хедър или C файл примерно. Това подпомага някой аспекти, но води до други проблеми - не може да се слага UNICODE, кода става нечетим (понякога описанията са в пъти повече от редовете реален код).
Та моето питане е как правим "референция" от ред в кода към външен ресурс (файл, URL, идентификатор, ...)?
Пак покрай лог/трейс темата видях една екстра на gnu инструментите (gcc/gdb) която не познавах досега - и това е "#line" директивата. Даже си мисля че не е gcc специфична понеже е спомената в MISRA правилата... Но идеята на тази директива е че написвайки:
 | | |
| Код: .... if (a>b) { #line 7 "../doc/errors.txt" LOG_ERR("Критично ниво на водата в сондажа!"); } | |
| | |
ще укажем по стандартен начин на инструментариума (гцц/гдб) че в някакъв файл /doc/errors.txt, на ред 7-ми има нещо което е асоциирано с точката в C кода ни тук. Това го ползват когато C кода "if a>b" е генериран от някакво по-високо ниво - т.е. имало е сорс на друг език и някакъв инструмент (код генератор) го е транслирал на C, добавяйки "връзка" откъде е това. Това го пробвах и даже работи - кара еклипса да отвори другия файл и да се мъкне по линиите му докато дебъгвам
Обратно по темата, търся идеи как да "маркирам" определени точки в кода (предполагам че там ще имам макроси) и те да могат да сочат навън. Конкретно това с "#line" не ми е нужно понеже нямам нужда от gdb поддръжка, така че си мисля за нещо custom. Дали специфичен таг от сорта на "\brief" на доксиген-а, или нещо такова.
Малко е неясно защо го правя, но да кажем че в процеса на разработката на кода е имало едно ниво на дизайн преди "кодирането" което е създало някаква информация - модел (UML, математически, ...) или пък документ-спецификация. И целта ми е без да копирам информацията от тези XML/matlab/docx файлове (в доксиген коментари) да мога да покажа причинно-следствената връзка.
Виждането ми е че на местата в кода, където искам да направя тези връзки, трябва да сложа някакъв маркер - идентификатор например, който да е ключа за извличане на информацията от външен ресурс (както е 7-цата в примера за #line).
Мислех доколко __FILE__, __LINE__, __COUNTER__ могат да се ползват, но клоня към идеята че няма да стане - в смисъл редактиране на код някъде из сорса, било то коментар или празен ред, ще смени __LINE__ и ще счупи връзката към връзката... Counter е по-добре, но пак ще е странно когато се редактира и се добави нова грешка в същия файл. Евентуално __FUNCTION__ май е най-малкото като единица, и брояч локален за функцията (__COUNTER__ който се рестартира във всяка функция) може да е най-лекото, но и това някак си не ме грабва като решение.
Друга посока беше да ползвам обратното - т.е. във файла "/doc/errors.txt" да имам парчета код около линията в сорса за която важи дадената грешка - по подобие на patch файловете които чрез един-два реда преди и след мястото описват точката във файла, която ще променят - е, аз не искам да променям а само да намеря линията. Така дори кода да се премести в друга функция има шанс да бъде намерен... може би?
Всичките тия условности май са решени (заобиколени?) с подхода на доксигена - за да не се разместят нещата ще ги сложим заедно и ако някой премести реда с условието и грешката трябва да премести и "мета" данните.
Една от целите на цялото упражнение, макар и не единствена, е да се построи система (инструментариум) който да може да извлече (автоматично) списък и детайлно описание на всички генерирани грешки в определен сорс (версия, проектни настройки - билд конфигурация). Това е ценно понеже от една и съща сорс база може да се правят няколко "артефакта" - elf/hex-ове за различни продукти например. Ако някаква функционалност е изключена в единия билд е полезно да имаме актуална информация - т.е. редуциран списък на грешките.
Пак с препратка към другата тема, lttng имат идея и за това - при тях местата на рапортуване на грешки (трейсове всъщност, викат им tracepoints) се описват декларативно в кода - хедърче със структурата на данните и информация (метаданни) за дадената грешка. Ако това се приложи може да значи че оня идентификатор, за който се чудя, може да е отделен макрос от типа на LOG_ERR_MyError3Crc - та този макрос или частта "MyError3Crc" е ключа/идентификатора и той ще присъства в сорса където е условието за вдигане на грешка, и във текстовия (условно - xml, db, ...) файл или като URL/URI в някаква информационна система.
Имам нужда от отделен макрос за всяка грешка за да мога да променям параметрите. Типичното при логване са variadic макросите с променлив брой аргументи - това е за улеснение, но страда откъм детайлност на информацията и консумация на ресурс. Подходът (пак от lttng...) е дадената "трейс точка" да обявява че и трябва да изплюе един аргумент тип int16_t примерно. Следващата трейс точка може да иска два int16_t, или 5 uint32_t, поради контекста на проверките които прави и данните с които работи.
Та ако макросите са отделни (а не един "централен" LOG_ERR(...) ) имам шанса да постигна красотата на lttng решението (или, с други думи, да се възползвам безцеремонно от техните идеи и реализацията им
... )Същият подход мисля че е подходящ за всякакви "експортирани" неща от софтуерен продукт - тук загатвам за подточката "грешки" или генерирани събития, но логиката трябва да може да се приложи и за входни такива - данни, настройки, конфигурации, методи, входни събития. Т.е. и там бих искал да мога да направя референция към заданието за да се знае защо съм написал "if (a>b) ...".
Edit: Мислейки още малко по темата си правя извода че ако "връзката" която е C сорса е достатъчно ясна (т.е. не е ред във файл а примерно абсолютна локация е някаква йерархия) няма да имам проблемите с разсинхронизирането - тях бих ги имал ако сложа още едно ниво на прехвърляне, т.е. ако има онова "#line 7 "file.txt", което би работило ако на line 7 там има абсолютен линк.
