Вводная документация, build-guide, а также reference по ключам командной строки и переменным, доступным из шаблонизатора: http://docs.tibbo.com/doxyrest
Здравствуйте, vovkos, Вы писали:
V>Предлагаю посмотреть и обсудить Doxyrest -- мост между Doxygen и Sphinx.
Зачем это все? Html, тем более Pdf. Кто будет это читать?
IMHO, сейчас для разработчиков поддержки IDE + Google/StackOverflow в большинстве случаев более чем достаточно.
А для пользователей все равно мануал руками пишется.
Здравствуйте, bnk, Вы писали:
bnk>Здравствуйте, vovkos, Вы писали:
V>>Предлагаю посмотреть и обсудить Doxyrest -- мост между Doxygen и Sphinx.
bnk>Зачем это все? Html, тем более Pdf. Кто будет это читать? bnk>IMHO, сейчас для разработчиков поддержки IDE + Google/StackOverflow в большинстве случаев более чем достаточно. bnk>А для пользователей все равно мануал руками пишется.
ИМХО все эти автоматически сгенерированные справки в 99% безполезны. Иногда помимо описания "open — открывает, get — доставляет" требуются минимально рабочие примеры. Даже бывает нет информации почему я немогу два раза подряд вызвать open или поменять end с begion местами неговоря уже о деталях, ограничениях и области применения конкретной реализации.
Пока самая удобная справка это chm написаные вручную остальное довольно унылое зрелище иногда уще и украшенное дизайнерскими изысками ввиде огромных шрифтов бледных оттенков.
Здравствуйте, kov_serg, Вы писали:
bnk>>Зачем это все? Html, тем более Pdf. Кто будет это читать? bnk>>IMHO, сейчас для разработчиков поддержки IDE + Google/StackOverflow в большинстве случаев более чем достаточно.
_>ИМХО все эти автоматически сгенерированные справки в 99% безполезны. Иногда помимо описания "open — открывает, get — доставляет" требуются минимально рабочие примеры. _>Даже бывает нет информации почему я немогу два раза подряд вызвать open или поменять end с begion местами, не говоря уже о деталях, ограничениях и области применения конкретной реализации. _>Пока самая удобная справка это chm написаные вручную остальное довольно унылое зрелище иногда уще и украшенное дизайнерскими изысками ввиде огромных шрифтов бледных оттенков.
У меня такое же мнение, в общем. Комментарии разметки полезны, если они конвертятся в некие хинты внутри IDE.
Идти на какой-то сайт читать описание функции в pdf меня вынудит только полная безысходность.
Наибольшую ценность имеют именно написанные вручную тексты (getting started, tutorial, samples, etc), а не гроссбухи из функций и неймспейсов.
Однако последние все же могут быть полезны при необходимости документирования (для стандартизации например) публичных библиотек и фреймворков.
Для обычных продуктов (не библиотек), или, тем более, заказной разработки, ценность гроссбухов, imho, стремится к нулю.
Грубоватая статья вышла: breathe "парсит XML-выхлоп доксигена", но doxyrest "парсит доксигеновские .xml файлы". Наглядно бы показать, что можно в doxyrest и нельзя в breathe. У меня не было проблем с breathe, было не сложно настроить структуру документации именно так как я хочу в каком мне нужно порядке.
Здравствуйте, vovkos, Вы писали:
V>Предлагаю посмотреть и обсудить Doxyrest -- мост между Doxygen и Sphinx.
когда меня достал убогий и вечно глючный в неожиданных местах Doxygen я посмотрел в его код -- думал, проект с долгой историей, и многими человеко/часами -- наверное написан вменяемо, быстренько щаз разберусь и пофиксю... %)
100500 раз гы-гы ;( -- лучше бы я этого не видел (теперь не могу забыть) ... все мои планы улучшить Doxygen резко улетучились.
в целом начинание с Doxyrest хорошее... я тоже постоянно мучаюсь с ублюдочным HTML выхлопом из него, и тоже подумывал процессить его XML... внезапно с содроганием вспомнил про XSLT (который тоже стараюсь забыть), но так и не решился... у меня был опыт работы с clang API и я бы не сказал, что там сложно все. более того, clang умеет парсить Doxygen-like комменты и есть API для их получения %)
Doxygen уже не исправить -- его проще написать заново. с надеждой было обнаружил standardese, но как уже верно было замечено, проект решительно наступает на те же грабли: еще больший хардкод HTML (причем внутри какой-то "левой" сишной библы) -- т.е. вообще без какой-либо возможности влиять на layout выхлопа.
чего я лично хотел бы видеть от идеального аналога Doxygen:
* полный контроль над HTML layoutом через шаблоны -- по сути от документирующей тулзы нужны только данные, шаблоны в которые их нужно отрендерить я нарисую сам, если стандартные (темы), мне не подойдут.
* не нужно на плюсах переписывать движки для парсинга микроформатов (выходит очень коряво) -- их 100500 уже написано на скриптовых языках и кое-кто из них уже стандарт де-факто. нужно уметь кормить эти движки текстом, и собирать вывод...
* unix way: вместо одной программы делающей все, я бы предпочел делать конвеер из небольших (и чорд подери безглючно выполняющих свою задачу) программ, каждая из которых передает свой вывод дальше... схематично как-то так: поиск файлов для обработки -> парсинг -> рендеринг собранных данных в шаблоны
если ближе к Doxyrest (почему я не буду его использовать, по крайней мере в ближайшей перспективе):
* ни когда не доводилось работать с Lua (я бы предпочел Python
* шаблоны, которые я увидел, показались мне чем-то большим чем то, что я ожидал (после опыта с jinja/django/jade) -- как мне кажется "логика" не до конца отделена от "представления"
* все собираюсь более плотно (не на проектах уровня "Hello World") ознакомиться со sphinx и вряд ли имеет смысл подсаживаться на Doxyrest, не разобравшись с ним и RST (если MD пишу уже на автомате, практически везде, а RST вот как-то не прижился, хотя узнал о нем раньше MD...)
прочие наблюдения в коде:
* раз выбран CMake, почему не используется CPack??? %() -- способ создания пакетов откровенно удивляет (в т.ч. и героизмом автора наваявшего такой велосипет... даже ВЕЛОСИПЕДИЩЕ)
* CMake "код", к слову, тоже "застрял" в где-то в прошлом (причем альтернативном нашей вселенной, глядя на `dependencies.cmake`)... на дворе уже CMake 3.7, exported/imported targetы, compiler features, нормальный way управлять глючиками компилятору/линкеру и зависимостями без головной боли...
почему я не буду контрибютором:
* через 4 дня наступит 2017 год!! (УРА!) через 3-4 месяца С++17 будет официально опубликован... не понимаю, зачем в этом проекте "прогибаться" под старые компиляторы??? где С++14? или хотябы С++11???
* (вкусовщина кэшно), но не люблю ломать себе моск об "необычный" (и чо уж там, чуждый) стиль С++ кода
... но автору всяческих успехов anyway!! -- еще раз повторюсь, в целом одобряю начинание )
Здравствуйте, bnk, Вы писали:
bnk>Здравствуйте, vovkos, Вы писали:
V>>Предлагаю посмотреть и обсудить Doxyrest -- мост между Doxygen и Sphinx.
bnk>Зачем это все? Html, тем более Pdf. Кто будет это читать? bnk>IMHO, сейчас для разработчиков поддержки IDE + Google/StackOverflow в большинстве случаев более чем достаточно. bnk>А для пользователей все равно мануал руками пишется.
Напоминаю, что мы говорим о документации API, а не о мануале для конечных пользователей. Вы спрашиваете, кто будет это читать? Встречный вопрос(ы) -- а вы сами никогда не открывали MSDN или man pages по POSIX функциям? А QT документацию? Нежели исключительно IDE и StackOverflow? Если это и так -- в чём позвольте-таки усомниться -- то как быть с людьми, которые предпочитают получать информацию из официальных источников?
Потом, что делать, если библиотека внутрикорпоративная и на просторах StackOverflow про неё никто не знает?
Здравствуйте, kov_serg, Вы писали:
_>ИМХО все эти автоматически сгенерированные справки в 99% безполезны. Иногда помимо описания "open — открывает, get — доставляет" требуются минимально рабочие примеры. Даже бывает нет информации почему я немогу два раза подряд вызвать open или поменять end с begion местами неговоря уже о деталях, ограничениях и области применения конкретной реализации.
Действительно, смысла в таких чисто механически добавленных комментариях ноль без палочки, а между тем в доксигеновских доках такое видишь сплошь и рядом. В обсуждении статьи на хабре я высказал версию, почему всё так -- ну не хочется тратить время и усилия на написание вдумчивых докси-комментариев, если в итоге документация всё равно будет выглядеть отвратно!
_>Пока самая удобная справка это chm написаные вручную
Имеется мнение и не только моё (c): вручную писать документацию API неправильно, так как вручную написанные объявления методов всегда отстают от эволюционирующего API, а при автогенерации имеется гарантия согласованности объявлений в документации и в исходниках.
_>остальное довольно унылое зрелище иногда уще и украшенное дизайнерскими изысками ввиде огромных шрифтов бледных оттенков.
Примеров второй части тезиса -- про изыски -- пожалуй что и не видел, а вот с первой согласен полностью. Проект как раз и создавался для того, чтобы исправить ситуацию с унылым зрелищем.
Здравствуйте, bnk, Вы писали:
bnk>У меня такое же мнение, в общем. Комментарии разметки полезны, если они конвертятся в некие хинты внутри IDE. bnk>Идти на какой-то сайт читать описание функции в pdf меня вынудит только полная безысходность.
Если IDE умеет показывать документацию, замечательно. Но и самостоятельная документация, доступная из браузера, крайне полезна -- даже если лично вы только StackOverflow пользуетесь, то поверьте, есть на свете люди которые и в QT доки ходят, и на MSDN, и man pages на linux.die.net открывают.
Потом, ещё аргумент почему IDE недостаточно. Неужели у вас не было ни разу ситуации когда IDE затыкались и не могли что-то распарсить в плюсовом проекте, после чего отказывались прыгнуть по Ctrl+Click или показать code-assist? Я пользуюсь Вижуалами под Виндой, NetBeans и QT Creator под Линуксом и Xcode под Маком -- и везде такое периодически случается.
bnk>Наибольшую ценность имеют именно написанные вручную тексты (getting started, tutorial, samples, etc), а не гроссбухи из функций и неймспейсов.
А разве не хочется, чтобы из этих самых Getting Started и Tutorial (которые, безусловно, можно писать только руками), были ссылки на описания функций в гроссбухе? Чтобы хотя бы можно было посмотреть, что за аргументы принимает функция, которую вы демонстрируете в сниппете -- тут ведь IDE-шные Ctrl+Click и mouse-hover не сработают!
bnk>Однако последние все же могут быть полезны при необходимости документирования (для стандартизации например) публичных библиотек и фреймворков. bnk>Для обычных продуктов (не библиотек), или, тем более, заказной разработки, ценность гроссбухов, imho, стремится к нулю.
Для личных библиотек, возможно, и не критично, а вот уже для корпоративных (не публичных!) фреймворков ценность доков далеко не ноль. Да на самом деле и для личных тоже -- процесс документирования помогает разложить всё по полочкам и выявить несуразности в API, которые могут и не замечаться при использовании.
Здравствуйте, Senyai, Вы писали:
S>Грубоватая статья вышла: breathe "парсит XML-выхлоп доксигена", но doxyrest "парсит доксигеновские .xml файлы".
Да я "выхлоп" на самом деле не в негативном смысле использовал.. Как синоним для "выход".
S>Наглядно бы показать, что можно в doxyrest и нельзя в breathe. У меня не было проблем с breathe, было не сложно настроить структуру документации именно так как я хочу в каком мне нужно порядке.
В breathe нет шаблонизатора -- это основная фишка doxyrest, и я на это и делал упор в статье. Breathe же узлы reStructuredText напрямую создаёт, а значит, априори негибок. Просили пример -- пожалуйста. Я всегда хотел, чтобы все объявления функций, полей и т.д. в автосгенерированных доках выглядели как снипетты -- чтоб было monospace и <pre> (а объявления-заголовки с детальной документацией -- monospace, но размером побольше и на другом фоне, например). Ну логичное ведь требование! Объявление -- это ж код!
Здравствуйте, zaufi, Вы писали:
Z>когда меня достал убогий и вечно глючный в неожиданных местах Doxygen я посмотрел в его код -- думал, проект с долгой историей, и многими человеко/часами -- наверное написан вменяемо, быстренько щаз разберусь и пофиксю... %) Z>100500 раз гы-гы ;( -- лучше бы я этого не видел (теперь не могу забыть) ... все мои планы улучшить Doxygen резко улетучились.
Есть такая буква в этом слове =) Тоже решил в переплетённые кишочки Доксигена не лезть, а использовать то, что он умеет выдавать из коробки.
Z>в целом начинание с Doxyrest хорошее... я тоже постоянно мучаюсь с ублюдочным HTML выхлопом из него, и тоже подумывал процессить его XML... внезапно с содроганием вспомнил про XSLT (который тоже стараюсь забыть), но так и не решился...
Чур меня, только не XSLT. Все до единого XML языки это зло и анти-технология. Конкретно про XSLT запомнилась одна цитата: XSLT is an failure wrapped in pain.
Z>у меня был опыт работы с clang API и я бы не сказал, что там сложно все. более того, clang умеет парсить Doxygen-like комменты и есть API для их получения %) Z>Doxygen уже не исправить -- его проще написать заново.
Насколько я знаю, автор Доксигена уже занят прикручиванием Clang. Если у него всё получится, то я бы и не затевал переписывание начисто, а просто продолжал использовал .xml выход доксигена -- просто чтобы оставить совместимость с уже написанной кем-то Доксиген документацией. Вы ведь видели, сколько Доксиген поддерживает тагов (абсолютно, к слову, ненужных)?
Z>с надеждой было обнаружил standardese, но как уже верно было замечено, проект решительно наступает на те же грабли: еще больший хардкод HTML (причем внутри какой-то "левой" сишной библы) -- т.е. вообще без какой-либо возможности влиять на layout выхлопа.
Мне на хабре указали, что в standardese тоже есть движок шаблонизации, но он там для самостоятельных (рукописных) страниц, да ещё и на своём языке с каким-то непотребным синтаксисом (рекомендую глянуть
Z>чего я лично хотел бы видеть от идеального аналога Doxygen: Z>* полный контроль над HTML layoutом через шаблоны -- по сути от документирующей тулзы нужны только данные, шаблоны в которые их нужно отрендерить я нарисую сам, если стандартные (темы), мне не подойдут. Z>* не нужно на плюсах переписывать движки для парсинга микроформатов (выходит очень коряво) -- их 100500 уже написано на скриптовых языках и кое-кто из них уже стандарт де-факто. нужно уметь кормить эти движки текстом, и собирать вывод... Z>* unix way: вместо одной программы делающей все, я бы предпочел делать конвеер из небольших (и чорд подери безглючно выполняющих свою задачу) программ, каждая из которых передает свой вывод дальше... схематично как-то так: поиск файлов для обработки -> парсинг -> рендеринг собранных данных в шаблоны
Всё логично. В Doxyrest, конечно, есть несоответствие пункту два: парсинг Доксигеновского XML сделан на основе libExpat -- что, впрочем, нормально для сишной утилиты. Можно было бы конечно вообще ВСЁ писать на Питоне -- но я профессиональный сишник и наиболее комфортно себя чувствую в си-мире, а на скриптовых языках пишу расширения и код, который должен потом модифицироваться пользователями.
Z>если ближе к Doxyrest (почему я не буду его использовать, по крайней мере в ближайшей перспективе): Z>* ни когда не доводилось работать с Lua (я бы предпочел Python
Принято. Архитектурно ничто не мешает добавить поддержку других языков, в том числе и Питона. А вообще для целей шаблонизации подходит почти любой -- там от скрипта требуются только control-flow и regexp-ы.
Z>* шаблоны, которые я увидел, показались мне чем-то большим чем то, что я ожидал (после опыта с jinja/django/jade) -- как мне кажется "логика" не до конца отделена от "представления"
Как мне кажется, шаблон при любом раскладе будет представлять из себя вермишель логики и представления. Ну и потом, вы смотрели на шаблоны для си-семейства -- не думаю, что можно принципиально упростить форматирование объявлений для [голосом Карлсона] Самого Сложного Языка В Мире Но одно то, что вся генерация вынесена в отдельные файлы шаблонов -- это уже вполне себе неплохое отделение.
Z>* все собираюсь более плотно (не на проектах уровня "Hello World") ознакомиться со sphinx и вряд ли имеет смысл подсаживаться на Doxyrest, не разобравшись с ним и RST (если MD пишу уже на автомате, практически везде, а RST вот как-то не прижился, хотя узнал о нем раньше MD...)
Разбирайтесь с reStructuredText и возвращайтесь
Z>прочие наблюдения в коде: Z>* раз выбран CMake, почему не используется CPack??? %() -- способ создания пакетов откровенно удивляет (в т.ч. и героизмом автора наваявшего такой велосипет... даже ВЕЛОСИПЕДИЩЕ)
Принято. Надо разобраться с CPack да переписать -- руки, как обычно, не доходят. А героизма никакого и не было вроде. Там bash-скрипты на пол-экрана с подстановкой CMake-переменных -- для упаковки нужной части репы таром (7z под Виндами). Но ещё раз -- согласен, по уму это надо делать на CPack.
Z>* CMake "код", к слову, тоже "застрял" в где-то в прошлом (причем альтернативном нашей вселенной, глядя на `dependencies.cmake`)... на дворе уже CMake 3.7, exported/imported targetы, compiler features, нормальный way управлять глючиками компилятору/линкеру и зависимостями без головной боли...
А вот тут не соглашусь -- подход с dependencies.cmake/paths.cmake позволяет гибко переключаться между различными версиями и сборками разных зависимостей на одной и той же билд-машине. Макросы для удобного переключения ключей компиляции через выпадающие списки были написаны, когда в CMake кроме CMAKE_C_FLAGS/CMAKE_CXX_FLAGS никаких аналогичных средств не было. Это же касается precompiled headers (они кстати появились уже в новом CMake? у меня там макросы precompiled headers для большой тройки: MSVC, GCC, Clang) и много другого.
Z>почему я не буду контрибютором: Z>* через 4 дня наступит 2017 год!! (УРА!) через 3-4 месяца С++17 будет официально опубликован... не понимаю, зачем в этом проекте "прогибаться" под старые компиляторы??? где С++14? или хотябы С++11???
Принимается. Уход от поддержки Visual Studio 2010 (в котором нет C++11) в планах на ближайшее время.
Z>* (вкусовщина кэшно), но не люблю ломать себе моск об "необычный" (и чо уж там, чуждый) стиль С++ кода
Да вроде обычный Java/QT-style. По-моему, любому сишному программисту в течение карьеры приходится постоянно переключаться между разными coding-styles -- главное, чтобы внутри проекта всё было consistent. Тут это есть. Или вам принципиально, чтобы в плюсовом проекте был именно C/STL/Boost-style?
Z>... но автору всяческих успехов anyway!! -- еще раз повторюсь, в целом одобряю начинание )
Здравствуйте, zaufi, Вы писали:
Z>* через 4 дня наступит 2017 год!! (УРА!) через 3-4 месяца С++17 будет официально опубликован... не понимаю, зачем в этом проекте "прогибаться" под старые компиляторы??? где С++14? или хотябы С++11??? Z>* (вкусовщина кэшно), но не люблю ломать себе моск об "необычный" (и чо уж там, чуждый) стиль С++ кода
а можно пример что не так в коде с точки зрения C++17 или C++14? просто сложновато смоттреть в этом гитхабе с планшета
Здравствуйте, vovkos, Вы писали:
bnk>>Наибольшую ценность имеют именно написанные вручную тексты (getting started, tutorial, samples, etc), а не гроссбухи из функций и неймспейсов.
V>А разве не хочется, чтобы из этих самых Getting Started и Tutorial (которые, безусловно, можно писать только руками), были ссылки на описания функций в гроссбухе? Чтобы хотя бы можно было посмотреть, что за аргументы принимает функция, которую вы демонстрируете в сниппете -- тут ведь IDE-шные Ctrl+Click и mouse-hover не сработают!
Не, ссылки на сигнатуры не нужны. Все равно же печатать будешь в ide, раньше тебе это просто не нужно знать, int там или long. Достаточно понять общую картину, детали на этапе чтения документации бесполезны.
V>А вот уже для корпоративных (не публичных!) фреймворков ценность доков далеко не ноль. Да на самом деле и для личных тоже -- процесс документирования помогает разложить всё по полочкам и выявить несуразности в API, которые могут и не замечаться при использовании.
Агащас. Ни разу не видел пользы в корпоративных проектах от автогенернной документации. Согласно моему опыту, обычно это делается ради галочки, на самом деле никто это не читает.
Z>>у меня был опыт работы с clang API и я бы не сказал, что там сложно все. более того, clang умеет парсить Doxygen-like комменты и есть API для их получения %) Z>>Doxygen уже не исправить -- его проще написать заново.
V>Насколько я знаю, автор Доксигена уже занят прикручиванием Clang.
насколько я помню, в Gentoo USE=clang у Doxygen появился где-то с 1.8.10 или .11 -- т.е. можно считать что, он есть (вчера выкатили DOxygen 1.8.13)
но дело даже не в том, как Doxygen парсит С/С++ ... больше всего багов за последнее время я обнаружил в его попытках поддерживать MarkDown для документации ;( ну а также при работе с layout.xml...
V>Если у него всё получится, то я бы и не затевал переписывание начисто, а просто продолжал использовал .xml выход доксигена -- просто чтобы оставить совместимость с уже написанной кем-то Доксиген документацией. Вы ведь видели, сколько Доксиген поддерживает тагов (абсолютно, к слову, ненужных)?
безусловно, если и делать next generation Doxygen, нужно обеспечить поддержку всех (ли?) его тэгов... развивать сам Doxygen я считаю бессмысленной тратой времени (в смысле когда внезапно возникает желание что-то в нем улучшить... не так что бы quick patch состряпать лишь бы собралось, а именно большую фичу какую добавить) -- даже с учетом того, что он стал пользовать clang, это все еще вонючая куча (даже КУЧИЩА!) не говнокода, а ГОВНОКОДИЩА!... "по быстрой" в него что-то добавлять, похоже не может уже даже автор... не говоря уже о том, чтобы фиксить багии от которых ломится трэкер и регрессии возникающие с каждым релизом... папка `testing/` вызывает когнетивный диссонанс сменяемый бесконечным разочарованием...
в общем я не жду, что этот инструмент скоро сдохнет, но и надежды на него ни какой...
после того, как я все это увидел, я стал жестко фиксировать (в зависимостях проекта) требуемую версию (щаз это 1.8.11) и как очень скоро оказалось, вовсе не зря! с выходом 1.8.12 все что было нажито непосильным трудом, перестало работать ;(
Z>>с надеждой было обнаружил standardese, но как уже верно было замечено, проект решительно наступает на те же грабли: еще больший хардкод HTML (причем внутри какой-то "левой" сишной библы) -- т.е. вообще без какой-либо возможности влиять на layout выхлопа.
V>Мне на хабре указали, что в standardese тоже есть движок шаблонизации, но он там для самостоятельных (рукописных) страниц, да ещё и на своём языке с каким-то непотребным синтаксисом (рекомендую глянуть
ммм... спасибо, наверное я откажусь, чтобы легче спалось/жилось %)
я повтыкал его код довольно поверхностно, и поиски шаблонов завели меня в 3rd party библу какуюто.... там я и бросил это дело, когда у видел что она на С...
Z>>чего я лично хотел бы видеть от идеального аналога Doxygen: Z>>* полный контроль над HTML layoutом через шаблоны -- по сути от документирующей тулзы нужны только данные, шаблоны в которые их нужно отрендерить я нарисую сам, если стандартные (темы), мне не подойдут. Z>>* не нужно на плюсах переписывать движки для парсинга микроформатов (выходит очень коряво) -- их 100500 уже написано на скриптовых языках и кое-кто из них уже стандарт де-факто. нужно уметь кормить эти движки текстом, и собирать вывод... Z>>* unix way: вместо одной программы делающей все, я бы предпочел делать конвеер из небольших (и чорд подери безглючно выполняющих свою задачу) программ, каждая из которых передает свой вывод дальше... схематично как-то так: поиск файлов для обработки -> парсинг -> рендеринг собранных данных в шаблоны
V>Всё логично. В Doxyrest, конечно, есть несоответствие пункту два: парсинг Доксигеновского XML сделан на основе libExpat
под "парсингом микроформатов" я имел ввиду жалкие потуги Doxygen поддерживать MarkDown -- меня выбешивают постоянные глюки в ней, часто для которых нет workaround'ов, а глюкавый код страшнее атомной войны... исправлять который не то что не тянет, а хочется стереть себе память о нем...
V> Можно было бы конечно вообще ВСЁ писать на Питоне -- но я профессиональный сишник и наиболее комфортно себя чувствую в си-мире, а на скриптовых языках пишу расширения и код, который должен потом модифицироваться пользователями.
про скриптовые языки я имел ввиду поддержку микроформатов в первую очередь: тот же python легко встраивается в C/C++ приложения. а вообще, если подумать, вероятно можно было бы просто запускать внешнюю прогу для процессинга и хватать ее вывод (тот же `kramdown`) -- вместо этого, заявленная поддержка MD будет не полноценная и безбожно глючная до самой смерти проекта (юнит тестов для плюсового кода походу и не предвидится) -- так и будут пока чинится одно, ломать другое... ;(
Z>>если ближе к Doxyrest (почему я не буду его использовать, по крайней мере в ближайшей перспективе): Z>>* ни когда не доводилось работать с Lua (я бы предпочел Python
V>Принято. Архитектурно ничто не мешает добавить поддержку других языков, в том числе и Питона. А вообще для целей шаблонизации подходит почти любой -- там от скрипта требуются только control-flow и regexp-ы.
здесь меня скорее смутил какой-то код на lua в шаблонах...
Z>>* шаблоны, которые я увидел, показались мне чем-то большим чем то, что я ожидал (после опыта с jinja/django/jade) -- как мне кажется "логика" не до конца отделена от "представления"
V>Как мне кажется, шаблон при любом раскладе будет представлять из себя вермишель логики и представления. Ну и потом, вы смотрели на шаблоны для си-семейства -- не думаю, что можно принципиально упростить форматирование объявлений для [голосом Карлсона] Самого Сложного Языка В Мире Но одно то, что вся генерация вынесена в отдельные файлы шаблонов -- это уже вполне себе неплохое отделение.
да, конечно это здорово
у меня к примеру в текущем проекте накопилось много опыта по геренации плюсового кода по шаблонам jinja (http://jinja.pocoo.org/) -- и надо сказать, вполне запросто иметь реюзабельные шаблоны в которых нет питоньего кода вообще! как и логики что-то делающей с данными... (всякие встроенные фильтры в jinja, типа lower/upper и прочих мелких строковых трансформаций не всчет %) а возможностей jinja по управлению white space'ами, более чем достаточно, чтобы получать исходники без лишних пробелов/переводов строк и согласно принятому codong style без дополнительного примерения "автоформаттеров".
имея к примеру встроенный интерпретатор питона, можно было бы "выгрузить" логику рендеринга данных в шаблоны в "юзерские" скрипты, позволив таким образом end-user'у работать с любым template engine (на петоне) по его вкусу (если вдруг "стандартный" ему кажется странным)...
Z>>* все собираюсь более плотно (не на проектах уровня "Hello World") ознакомиться со sphinx и вряд ли имеет смысл подсаживаться на Doxyrest, не разобравшись с ним и RST (если MD пишу уже на автомате, практически везде, а RST вот как-то не прижился, хотя узнал о нем раньше MD...)
V>Разбирайтесь с reStructuredText и возвращайтесь
определенно!
Z>>прочие наблюдения в коде: Z>>* раз выбран CMake, почему не используется CPack??? %() -- способ создания пакетов откровенно удивляет (в т.ч. и героизмом автора наваявшего такой велосипет... даже ВЕЛОСИПЕДИЩЕ)
V>Принято. Надо разобраться с CPack да переписать -- руки, как обычно, не доходят. А героизма никакого и не было вроде. Там bash-скрипты на пол-экрана с подстановкой CMake-переменных -- для упаковки нужной части репы таром (7z под Виндами). Но ещё раз -- согласен, по уму это надо делать на CPack.
CPack "искаропки" поддерживает кучу форматов... а уж чтобы делать архивы кроссплатформенно вообще нужно "пяток" строк на CMake...
Z>>* CMake "код", к слову, тоже "застрял" в где-то в прошлом (причем альтернативном нашей вселенной, глядя на `dependencies.cmake`)... на дворе уже CMake 3.7, exported/imported targetы, compiler features, нормальный way управлять глючиками компилятору/линкеру и зависимостями без головной боли...
V>А вот тут не соглашусь -- подход с dependencies.cmake/paths.cmake позволяет гибко переключаться между различными версиями и сборками разных зависимостей на одной и той же билд-машине.
`find_package()` же! все вменяемые finder'ы поддерживают hintы -- хочешь попробовать с другой версией, просто укажи с какой...
> Макросы для удобного переключения ключей компиляции через выпадающие списки были написаны
вот это я не понял о чем... я, к слову, `cmake-gui` не пользую от слова совсем... -- нафиг не сдался он.
> когда в CMake кроме CMAKE_C_FLAGS/CMAKE_CXX_FLAGS никаких аналогичных средств не было.
"трогать руками" эти переменные сейчас вообще не нужно (и даже вредно!) -- есть куча специально предназначенных для этого средств:
* target_compile_definitions
* target_compile_features
* target_compile_options
* target_include_directories
* target_link_libraries
по сути, более ничего и не надо. особенно если хочешь линковаться со своими же зависимостями из других проектов без головной боли.
> Это же касается precompiled headers (они кстати появились уже в новом CMake? у меня там макросы precompiled headers для большой тройки: MSVC, GCC, Clang) и много другого.
вот это пока не сделано ;( и тут поле для customных решений... они тоже есть в том или ином виде.
Z>>* (вкусовщина кэшно), но не люблю ломать себе моск об "необычный" (и чо уж там, чуждый) стиль С++ кода
V>Да вроде обычный Java/QT-style.
... ну не совсем обычный всеже %) Java не знаю, а для Qt/KDE доводилось...
V>По-моему, любому сишному программисту в течение карьеры приходится постоянно переключаться между разными coding-styles -- главное, чтобы внутри проекта всё было consistent. Тут это есть.
когда речь заходит о "а не исправить/допилить ли мне на досуге ..." чуждость coding style тоже принимается во внимание. и да, "переключение" на другой coding style конечно возможен, но pain in the ass в процессе меня бесит %) -- особенно если дело не касается оплачивоемой работы %)
V> Или вам принципиально, чтобы в плюсовом проекте был именно C/STL/Boost-style?
скорее boost... не принципиально. в некоторых проектах желание улучшить что-то бывает очень сильным и перевешивает coding style inconvenience... но иногда "баланс" не такой явный
Здравствуйте, RonWilson, Вы писали:
RW>Здравствуйте, zaufi, Вы писали:
Z>>* через 4 дня наступит 2017 год!! (УРА!) через 3-4 месяца С++17 будет официально опубликован... не понимаю, зачем в этом проекте "прогибаться" под старые компиляторы??? где С++14? или хотябы С++11??? Z>>* (вкусовщина кэшно), но не люблю ломать себе моск об "необычный" (и чо уж там, чуждый) стиль С++ кода
RW>а можно пример что не так в коде с точки зрения C++17 или C++14? просто сложновато смоттреть в этом гитхабе с планшета
его там нет в этом проекте... по непонятной мне причине (ну автор уже разяснил про какую-то древнегреческую вижуал студию...)
Здравствуйте, zaufi, Вы писали:
Z>насколько я помню, в Gentoo USE=clang у Doxygen появился где-то с 1.8.10 или .11 -- т.е. можно считать что, он есть (вчера выкатили DOxygen 1.8.13)
Не помню уже какая это была версия, но при попытке включить clang он просто падал на моём проекте. Я понял, что поддержка clang пока ну уж слишком экспериментальная и решил подождать. Надо попробовать с новой версией...
Z>но дело даже не в том, как Doxygen парсит С/С++ ... больше всего багов за последнее время я обнаружил в его попытках поддерживать MarkDown для документации ;( ну а также при работе с layout.xml...
Если использовать подход Doxyrest, то ничего, кроме парсинга C/C++ и не важно -- внутри комментариев можно писать чисто на reStructuredText и вообще забить на поддержку маркдауна. То есть брать от Доксигена только выдаваемую им в XML структуру дерева объявлений C/C++ проекта с привязанными комментариями.
Z>безусловно, если и делать next generation Doxygen, нужно обеспечить поддержку всех (ли?) его тэгов... развивать сам Doxygen я считаю бессмысленной тратой времени (в смысле когда внезапно возникает желание что-то в нем улучшить... не так что бы quick patch состряпать лишь бы собралось, а именно большую фичу какую добавить) -- даже с учетом того, что он стал пользовать clang, это все еще вонючая куча (даже КУЧИЩА!) не говнокода, а ГОВНОКОДИЩА!... "по быстрой" в него что-то добавлять, похоже не может уже даже автор... не говоря уже о том, чтобы фиксить багии от которых ломится трэкер и регрессии возникающие с каждым релизом... папка `testing/` вызывает когнетивный диссонанс сменяемый бесконечным разочарованием...
Так как я не использовал маркдаун, то меня чаша сия обошла стороной Но вообще у него и в XML имеются серьёзные проблемы. Навскидку, меня просто поставила в ступор его неспособность описать unnamed structs/unions. То есть он он тупо встраивает поля неименованных struct/unions в родителськие -- восстановить исходную структуру сорцов с неименованными structs/unions по доксигеновскому XML просто невозможно! Я для этой цели сейчас использую уродливые костыли в виде спец-комментариев у самого первого поля неименованного struct/union...
Z>у меня к примеру в текущем проекте накопилось много опыта по геренации плюсового кода по шаблонам jinja (http://jinja.pocoo.org/) -- и надо сказать, вполне запросто иметь реюзабельные шаблоны в которых нет питоньего кода вообще! как и логики что-то делающей с данными... (всякие встроенные фильтры в jinja, типа lower/upper и прочих мелких строковых трансформаций не всчет %) а возможностей jinja по управлению white space'ами, более чем достаточно, чтобы получать исходники без лишних пробелов/переводов строк и согласно принятому codong style без дополнительного примерения "автоформаттеров".
Не пользовался jinja, надо глянуть. Но вообще с трудом представляю, как совсем без кода сделать цикл? Ну для примера -- как на jinja будет выглядеть шаблон для объявления класса? Там же нужен цикл по методам, у каждого несколько аргументов (цикл по аргументам), аргументы опять таки могут быть указателями на функции (опять нужен цикл по аргументам) или массивам (здесь цикл по размерностям).
Z>CPack "искаропки" поддерживает кучу форматов... а уж чтобы делать архивы кроссплатформенно вообще нужно "пяток" строк на CMake...
Обязательно попробую.
Z>) `find_package()` же! все вменяемые finder'ы поддерживают hintы -- хочешь попробовать с другой версией, просто укажи с какой...
Так, да не совсем =) Во-первых find_package работает крайне ненадёжно на Виндах -- считай, там его просто нет, обязательно нужны HINTS/PATHS. То есть на Виндах всё сводится к вопоросу: как именно настраивать явные пути. Но и на Никсах подход с явным указанием путей тоже имеет область применимости. Например, это позволяет иметь несколько версий (и различных вариаций сборок -- Debug/Release/x86/amd64/static/shared/rtti/no-rtti и т.д.) -- без установки! То есть скачал исходники нужной версии либы, собрал -- с нужными ключами -- и оставил лежать там же, не устанавливая в систему!
Теперь, какая у меня модель настройки путей. Имеется файл paths.cmake в котором указаны явные пути, как-то так:
set (LUA_VERSION 5.2.1)
set (EXPAT_VERSION 2.2.0)
set (LUA_INC_DIR "/home/vladimir/Develop/lua/lua-${LUA_VERSION}/include")
set (EXPAT_INC_DIR "/home/vladimir/Develop/expat/expat-${EXPAT_VERSION}/lib")
if ("${AXL_CPU}" STREQUAL "amd64")
set (LUA_LIB_DIR "/home/vladimir/Develop/lua/lua-${LUA_VERSION}/lib-amd64")
set (EXPAT_LIB_DIR "/home/vladimir/Develop/expat/expat-${EXPAT_VERSION}/build/make-amd64")
else ()
set (LUA_LIB_DIR "/home/vladimir/Develop/lua/lua-${LUA_VERSION}/lib-x86")
set (EXPAT_LIB_DIR "/home/vladimir/Develop/expat/expat-${EXPAT_VERSION}/build/make-x86")
endif ()
Файл каскадный -- это означает, что он может лежать где угодно и влияет на все CMake проекты, находящиеся в поддиректориях. Проекты ищут paths.cmake в текущей и родительской директориях, и если находят, используют пути из него:
Велосипед? Безусловно. Но с моторчиком! Очень удобно, особенно в случаях когда проектов много и надо делать кросс-сборки (причём и для отладки и для release), а также если хочется скачать и попробовать новую версию либы, не затрагивая систему -- не нужно устанавливать а потом сносить.
>> Макросы для удобного переключения ключей компиляции через выпадающие списки были написаны Z>вот это я не понял о чем... я, к слову, `cmake-gui` не пользую от слова совсем... -- нафиг не сдался он.
Ясно. А я пользую -- сначала `cmake ..` потом `cmake-gui .` Под выпадающими списками имелось в виду, что любые ключики компилятора могут быть вынесены в Combobox для настройки из cmake-gui. Опять таки мне нравится, что можно попробовать, и так и эдак. Это я впервые увидел в LLVM build system, и мне очень понравилось. Из командной строки этим играться не очень удобно, потому что надо помнить все возможные варианты значений ключа (что критично, когда опций вагон, например, как для ключа -std=).
Z>"трогать руками" эти переменные сейчас вообще не нужно (и даже вредно!) -- есть куча специально предназначенных для этого средств: Z>* target_compile_definitions Z>* target_compile_features Z>* target_compile_options Z>* target_include_directories Z>* target_link_libraries
Z>по сути, более ничего и не надо. особенно если хочешь линковаться со своими же зависимостями из других проектов без головной боли.
ИМХО реальный смысл использовать target_compile_options а не CMAKE_C_FLAGS/CMAKE_CXX_FLAGS есть тогда, когда в подпапке более одного таргета, и у им нужны разные ключи. Мне чаще наоборот хочется, чтоб была каскадность -- чтоб всё, что в подпапках, использовало данные ключи.
>> Это же касается precompiled headers (они кстати появились уже в новом CMake? у меня там макросы precompiled headers для большой тройки: MSVC, GCC, Clang) и много другого. Z>вот это пока не сделано ;( и тут поле для customных решений... они тоже есть в том или ином виде.
Тоже начинал с поиска (естесвенно), нашёл несколько скриптов разной степени готовности -- но ничего работающего из коробки для GCC и Clang. В итоге написал сам.
Z>когда речь заходит о "а не исправить/допилить ли мне на досуге ..." чуждость coding style тоже принимается во внимание. и да, "переключение" на другой coding style конечно возможен, но pain in the ass в процессе меня бесит %) -- особенно если дело не касается оплачивоемой работы %)
Здравствуйте, vovkos, Вы писали: V>Здравствуйте, zaufi, Вы писали: Z>>насколько я помню, в Gentoo USE=clang у Doxygen появился где-то с 1.8.10 или .11 -- т.е. можно считать что, он есть (вчера выкатили DOxygen 1.8.13) V>Не помню уже какая это была версия, но при попытке включить clang он просто падал на моём проекте. Я понял, что поддержка clang пока ну уж слишком экспериментальная и решил подождать. Надо попробовать с новой версией...
1.8.11 у меня собран с поддержкой clang и все текущие проекты хавает и не падает. в качество парсинга честно говоря не особо вглядывался, где то были пара косяков с шаблонами, но точно уже не помню в чем (руки были заняты другими задачами), а сейчас это все "на потоке" билдится в тимсити и деплоится в интранет... вроде на вскидку ничо странного не видно (исключая убогую поддержку MD) V>Если использовать подход Doxyrest, то ничего, кроме парсинга C/C++ и не важно -- внутри комментариев можно писать чисто на reStructuredText и вообще забить на поддержку маркдауна. То есть брать от Доксигена только выдаваемую им в XML структуру дерева объявлений C/C++ проекта с привязанными комментариями.
вот тут как мне кажется начинает теряться необходимость в doxygen -- напилить "парсер" с использованием clang чтобы он выплевывал то, что хочется, и процессить это дальше как заблагорассудится, не кажется уже непосильной задачей (в целом это не сложно, сложнее всеже понять что именно хочется %)
... чот меня опять начало подмывать сделать это... %) -- нужен просто *надежный* парсер C++ в структуированный XML или даже JSON, а то и вовсе YAML -- а далее есть 10050 скриптовых языков с шаблонизаторами, которые отрендереят это как захочется V>Так как я не использовал маркдаун, то меня чаша сия обошла стороной Но вообще у него и в XML имеются серьёзные проблемы. Навскидку, меня просто поставила в ступор его неспособность описать unnamed structs/unions. То есть он он тупо встраивает поля неименованных struct/unions в родителськие -- восстановить исходную структуру сорцов с неименованными structs/unions по доксигеновскому XML просто невозможно! Я для этой цели сейчас использую уродливые костыли в виде спец-комментариев у самого первого поля неименованного struct/union...
еще один плюс, "за" то чтобы сделать "просто надежный парсер плюсов, на clang'e" V>Не пользовался jinja, надо глянуть. Но вообще с трудом представляю, как совсем без кода сделать цикл?
нет, разумеется "циклы" там есть в шаблоне -- в смысле есть у тебя список методов, и чтобы его отрендерить конечно надо проитеритьсяя по item'ам... для этого есть {% for... %}, но писать питоний код в шаблонах, чтобы чего-то там достать/преобразовать, должно быть не нужно (в хорошем коде) -- используем *только* директивы/трансформации шаблонизатора, а все данные для рендерига уже аккуратно были подготовлены "бизнес слоем" и делать с ними в шаблонах ничего не надо... только достать и подставить куда надо.
вот к примеру из реального проекта
/// This class represents the {{ message.notes }}{# TODO Make sure `notes` is a single line #}
struct {% if message is public %}EXPORT_API {% endif %}{{ message|cxx_type }}
{
/// Message type constant
enum { messageType = '{{ message.type }}' };
{% for field in message.fields|public -%}
{%- for note in field.notes %}
/// {{ note }}
{%- endfor %}
{{ field|cxx_type }} {{ field|cxx_id }};
{% endfor %}
{%- for group in message.groups|public %}
/// {{ group.notes }}{# TODO Make sure `notes` is a single line #}
struct {% if message is public %}EXPORT_API {% endif %}{{ group|cxx_type }}
{
{%- for field in group.fields|public %}
{%- for note in field.notes %}
/// {{ note }}
{%- endfor %}
{{ field|cxx_type }} {{ field|cxx_id }};
{%- endfor %}
/// Returns string representation.
std::string toString() const;
};
/// Alias for collection of {{ group.plural }}.
typedef std::vector<{{ group|cxx_type }}> {{ group|cxx_type('plural') }};
/// Collection of {{ group.plural }}.
{{ group|cxx_type('plural') }} {{ group|cxx_id('plural') }};
{% endfor %}
{%- for field in message.optional.fields|public -%}
{%- for note in field.notes %}
/// {{ note }}
{%- endfor %}
Optional<{{ field|cxx_type }}> {{ field|cxx_id }};
{% endfor %}
/// Default constructor.
{{ message|cxx_type }}();
/// Returns string representation.
std::string toString() const;
private:
friend class MessageDeserializer;
{{ message|cxx_type }}(const char* data, size_t dataSize);
void deserialize(const char* data, size_t dataSize);
void reset();
};
здесь нет никакого питоньего кода, ничего что бы занималось "подготовкой" данных -- только рендеринг, никакой другой логики... и как оно будет рендерится определяется только здесь и нигде более, а то что именно будет тут рендериться, подготавливается в другом месте, ровно то, что нужно в этом шаблоне
Z>>) `find_package()` же! все вменяемые finder'ы поддерживают hintы -- хочешь попробовать с другой версией, просто укажи с какой... V>Так, да не совсем =) Во-первых find_package работает крайне ненадёжно на Виндах -- считай, там его просто нет, обязательно нужны HINTS/PATHS.
ну ладно уж пессимизировать то -- то, что в виндах вместо файловой системы помойка, не отменяет того, что даже на этой помойке с CMakeом можно как-то выживать и выкручиваться %) к несчастью я хоть и не настоящий сварщик виндовый программист, но недавно доводилось настраивать кучу CMake проектов, разумеется с пачкой внешних зависимостей, которые не используют CMake... все как-то обошлось без необходимости указывать кучу хинтов %)
более того, в итоге в "обычной жизни" виндового программиста, вообще не нужно ничего указывать -- все находится само V>То есть на Виндах всё сводится к вопоросу: как именно настраивать явные пути.
100500 способов же -- нужно просто выбрать, что было бы удобно в повседневной жизни... (может даже сначала проанализировать эту "поседневную жизнь" на адекватность современным реалиям... вполне может так получиться, что она складывается из вредных привычек прошлого, и стоит только принять CMake-way, как все внезапно становится проще %) (потому, что не приходтся городить себе трудностей, а потом героически их решать %) V>Но и на Никсах подход с явным указанием путей тоже имеет область применимости. Например, это позволяет иметь несколько версий (и различных вариаций сборок -- Debug/Release/x86/amd64/static/shared/rtti/no-rtti и т.д.) ...
ох, что-то это начинает "попахивает" windows-way'ем %) V>... -- без установки! То есть скачал исходники нужной версии либы, собрал -- с нужными ключами -- и оставил лежать там же, не устанавливая в систему!
да, точно это ОН %) V>Теперь, какая у меня модель настройки путей. Имеется файл paths.cmake в котором указаны явные пути, как-то так:
отсюда и далее прослеживается очень распространенная bad practice (очевидно пришедшая из windows), мешающая масштаируемости, тиражируемости и воспроизводимости сборок %)
не говоря уже о том, что это усложняет жизнь newcomer'ам -- не достаточно просто знать CMake... нужно еще втыкать homecooked велосипет, и "перебрать" его моторчик не имея при этом его "чертежей" %) да и просто при "развертывании" рабочего места, это еще куча телодвижений... удивлюсь, если документированных где-то %) V>Файл каскадный -- это означает, что он может лежать где угодно и влияет на все CMake проекты, находящиеся в поддиректориях.
и ошибиться в нем может кто угодно? V>Велосипед? Безусловно. Но с моторчиком! Очень удобно, особенно в случаях когда проектов много и надо делать кросс-сборки (причём и для отладки и для release),
у меня куча cmake проектов и целевых платформ (сам я на gentoo) -- легко обхожусь без моторчика %) и вообще не вижу в нем необходимости для себя %) V>а также если хочется скачать и попробовать новую версию либы, не затрагивая систему -- не нужно устанавливать а потом сносить.
это пожалуй единственный case когда я указываю hint finder'у на собранный пакет... а вот если новая версия понравилась и пошла в дело?
управлять пакетами и их файлами это задача package manager'a -- не моя (в gentoo это означает еще и компиляцию с нужными глючиками)!
paludis и gentoo соответствует всем моим требованиям %) -- вопреки бытующему среди windows разработчиков мнению, компилячить что-то "руками" в Linux это bad practice -- все знают, что это ведет к "нетиражируемости" решения.
"не затрагивать" систему, есть зиллиард способов... зависит от того что за "система".
V>Ясно. А я пользую -- сначала `cmake ..` потом `cmake-gui .` Под выпадающими списками имелось в виду, что любые ключики компилятора могут быть вынесены в Combobox для настройки из cmake-gui. Опять таки мне нравится, что можно попробовать, и так и эдак. Это я впервые увидел в LLVM build system, и мне очень понравилось. Из командной строки этим играться не очень удобно, потому что надо помнить все возможные варианты значений ключа (что критично, когда опций вагон, например, как для ключа -std=).
ну не знаю... играться какими-то ключиками компилятору из командной строки вообще не хочется... не потому что "неудобно" (у меня как раз удобный shell и терминал) и я даже помню много ключей gcc так что мне не нужен man... но вот коллеги далеко не все знают это и хотят помнить %)
наборов ключей на сам деле довольно не много -- и для их управления как нельзя лучше подходят "профайлы". кроме стандартных debug/release я добавляю extreme-optimize и extreme-debug... стандартные minsize/release-with-debug-info в общем и не использую. указывать конкретные ключи в CLI как-то вообще не выглядит хорошей идеей...
и кстати, для управления -std не надо вообще трогать CMAKE_XXX_FLAGS! (добро пожаловать в cmake 3.x) -- для этого есть более надежное кроссплатформенное средство. V>ИМХО реальный смысл использовать target_compile_options а не CMAKE_C_FLAGS/CMAKE_CXX_FLAGS есть тогда, когда в подпапке более одного таргета, и у им нужны разные ключи. Мне чаще наоборот хочется, чтоб была каскадность -- чтоб всё, что в подпапках, использовало данные ключи.
это устаревшее представление -- где-то из CMake 2.x ветки -- реальной необходимости манипулировать этими переменными щаз вообще нет! только если ты рисуешь свой toolchain файлик...
оч рекомендую заштудировать доки CMake по управлению требованиями... оно может показаться непонятным с первого прочтения, но уверяю тебя, оно стоит 2х-3х внимательных чтений и экспериментов чтобы догнать все идеи.
к примеру у меня щаз куча наших проектов связанных между собой зависимостями (плюс конечно же "внешние" библы/зависимости)... и я вообще не парюсь устанавливать какие-то глючики компиляторов под каждую цель `target_link_libraries` "наследует" их от зависимостей! V>Тоже начинал с поиска (естесвенно), нашёл несколько скриптов разной степени готовности -- но ничего работающего из коробки для GCC и Clang. В итоге написал сам.
gcc и clang вообще ничо сложного... я тогда (во времена cmake 2.6) тоже сделал свой sipeda-motor... сложности начинаются, когда нужно еще и убогий MSVC приучить... (пока эта задача даже у меня в долгом ящике ибо есть более насущные)
Получается слишком длинная простыня, порежу на подразделы.
Doxygen
Z>1.8.11 у меня собран с поддержкой clang и все текущие проекты хавает и не падает.
Не помню уже конкретную комбинацию версий, возможно, была несовместимость сборок Doxygen и Clang.
Далее следует удивительное логическое построение:
Z>в качество парсинга честно говоря не особо вглядывался, где то были пара косяков с шаблонами, но точно уже не помню в чем (руки были заняты другими задачами), а сейчас это все "на потоке" билдится в тимсити и деплоится в интранет... вроде на вскидку ничо странного не видно (исключая убогую поддержку MD)
То есть парсинг C++ в целом устраивает. Поэтому -- внезапно! -- надо
Z>... напилить "парсер" с использованием clang чтобы он выплевывал то, что хочется, и процессить это дальше как заблагорассудится.
Дальше -- лучше:
Z> не кажется уже непосильной задачей (в целом это не сложно, сложнее всеже понять что именно хочется %) ... чот меня опять начало подмывать сделать это... %)
И эти люди запрещают мне ковыряться в носу! (с) Это про "мужественное" решение поставленных перед собой проблем Если парсер плюсов -- даже с использованием Clang -- кажется вам лёгкой задачей, то вы просто не в теме. Если же вы рассматриваете это просто как интересный исследовательский проект, направленный на получение опыта -- ок, желание понятно.
Z> -- нужен просто *надежный* парсер C++ в структуированный XML или даже JSON, а то и вовсе YAML --
Ещё раз -- если вас в целом устраивает качество парсинга плюсов Доксигеном, то зачем вы хотите писать свой парсер? У Доксигена уже есть выход в структурированный XML.
Z> а далее есть 10050 скриптовых языков с шаблонизаторами, которые отрендереят это как захочется
В бытность мою студентом мы изучали теорфизику по Ланфшицу, и в ходу был такой бородатый анекдот:
Лифшиц приходит с утра в институт расстроенный.
— Что случилось? — спрашивает Ландау.
— Слушай, я три листа выкладок в троллейбусе потерял.
— Да ладно, ничего страшного. Напишем, как обычно: "откуда легко следует, что..."
Превращение структуры плюсового проекта из XML/JSON/... в HTML/PDF/... -- это те самые потерянные несколько листов выкладок. Не электродинамика сплошных сред, конечно, но шапками не закидывается, и представляет собой вполне себе самостоятельную задачу. Одно из известных мне её решений -- breathe (парсит XML и создаёт узлы reStructuredText напрямую), второе -- мой Doxyrest (парсит XML и отдаёт шаблонизатору на Lua).
Над решением этой задачи и нужно работать, а не кидаться писать новый парсер плюсов на Кланге. Зачем с этого начинать? Если front-end Доксигена (в целом) устраивает, а back-end -- однозначно не устраивает, то надо оставить устраивающее, а не переписывать всё с нуля!
V>> ... неспособность описать unnamed structs/unions. То есть он он тупо встраивает поля неименованных struct/unions в родителськие -- восстановить исходную структуру сорцов с неименованными structs/unions по доксигеновскому XML просто невозможно! Я для этой цели сейчас использую уродливые костыли в виде спец-комментариев у самого первого поля неименованного struct/union...
Z>еще один плюс, "за" то чтобы сделать "просто надежный парсер плюсов, на clang'e"
Пока это единственное найденное мной реальное ограничение доксигеновского выхода в XML (конечно, схема XML сама по себе кривовата, так как спроектирована явно не компиляторостроителем -- но жить можно). Но всё равно -- это ну никак не тянет на casus belli для написания парсера плюсов.
Или же парсер плюсов затевается только как способ побороть неспособность Доксигена нормально парсить Markdown? Опять таки, это не тянет на casus belli. Как временное решение можно закатывать докси-комментарии в \verbatim (и парсить их самому на этапе генерации документации); как постоянное -- сделать контриб в Доксиген с новой настройкой по полному отключению парсинга комментариев, типа VERBATIM_COMMENTS = TRUE.
Z>нет, разумеется "циклы" там есть в шаблоне -- в смысле есть у тебя список методов, и чтобы его отрендерить конечно надо проитеритьсяя по item'ам... для этого есть {% for... %} Z> вот к примеру из реального проекта
Ну... На таком примитивном примере действительно почти никакого кода не нужно. Он и в шаблонах на Lua будет выглядеть не сложнее.
Итак, чем это (jinja)...
/// This class represents the {{ message.notes }}{# TODO Make sure `notes` is a single line #}
struct {% if message is public %}EXPORT_API {% endif %}{{ message|cxx_type }}
{
/// Message type constant
enum { messageType = '{{ message.type }}' };
{% for field in message.fields|public -%}
{%- for note in field.notes %}
/// {{ note }}
{%- endfor %}
{{ field|cxx_type }} {{ field|cxx_id }};
{% endfor %}
... лучше этого (lua)?
/// This class represents the $(message.notes) %{ -- TODO Make sure `notes` is a single line }
struct %{ if message.public then }EXPORT_API %{ end }$(filter (message, cxx_type))
{
/// Message type constant
enum { messageType = '$(message.type)' };
%{
public_fields = filter (message.fields, public)
for i = 1, #public_fields
field = public_fields [i]
for j = 1, #field.notes }
/// $(field.notes [j])
%{ end }
$(filter (field, cxx_type)) $(filter (field, cxx_id));
%{ end }
Z> здесь нет никакого питоньего кода,
Ещё бы!! Питон и не подходит для шаблонизации в силу своего синтаксиса (структурирование блоков с помощью отступов). Кстати, признаю ошибку и вношу коррекцию в своё утверждение выше, что, мол, Lua можно заменить на любой другой скриптовый язык. Любой, да не любой
Переформулирую необходимое и достаточное условие:
Скриптовый язык для шаблонизации должен иметь структурирование блоков НЕ с помощью отступов. Ну и control flow и регекспы ессно, но это и так есть везде.
Z> ну ладно уж пессимизировать то -- то, что в виндах вместо файловой системы помойка, не отменяет того, что даже на этой помойке с CMakeом можно как-то выживать и выкручиваться %)
Ну наконец-то -- а то я всё думал, неужели обойдётся без наездов на Винду от гентушника. Ан нет, не обошлось А вообще c последней частью утверждения сложно спорить. Выживать и выкручиваться, действительно, можно в любой ситуации.
Z>к несчастью я хоть и не настоящий сварщик виндовый программист, но недавно доводилось настраивать кучу CMake проектов, разумеется с пачкой внешних зависимостей, которые не используют CMake... все как-то обошлось без необходимости указывать кучу хинтов %)
Хммм... Мне это странно слышать. По моему опыту хинты на виндах для find_package просто необходимы. Да, иногда встречается специально обученный файндер, который может найти установку в УМОЛЧАЛЬНУЮ папку какого-то КОНКРЕТНОГО инсталлятора, но это скорее исключение из правил. Добавим сюда то, что официальных сборок под винду у многих либ просто нет, и надо или искать сторонние бинарники, или собирать самому -- что опять таки выливается в необходимость хинтов.
Далее, единообразия в хинтах у файндеров тоже нет -- они и называются по разному (XXX_DIR, XXX_BASE_DIR, XXX_ROOT_DIR) и задаются иногда как CMake-variable, а иногда как environment variable.
Z>более того, в итоге в "обычной жизни" виндового программиста, вообще не нужно ничего указывать -- все находится само
Склоняюсь к версии, что повезло с конкретными зависимостями, раз они нашлись на Винде без хинтов. А можно подробнее -- что за зависимости и как они нашлись без хинтов?
V>>То есть на Виндах всё сводится к вопоросу: как именно настраивать явные пути.
Z>100500 способов же -- нужно просто выбрать, что было бы удобно в повседневной жизни... (может даже сначала проанализировать эту "поседневную жизнь" на адекватность современным реалиям... вполне может так получиться, что она складывается из вредных привычек прошлого, и стоит только принять CMake-way, как все внезапно становится проще %)
Ещё раз, даже когда CMake-way c find_package/find_path/find_library работает из коробки, это не универсальный ответ на всё. Иногда нужно указывать явные пути. Пример будет ниже.
Z>(потому, что не приходтся городить себе трудностей, а потом героически их решать %)
Это мне говорит человек, которого "снова начало подмывать" написать парсер плюсов, ведь "в целом это не сложно"
V>>Но и на Никсах подход с явным указанием путей тоже имеет область применимости. Например, это позволяет иметь несколько версий (и различных вариаций сборок -- Debug/Release/x86/amd64/static/shared/rtti/no-rtti и т.д.) ...
Z> ох, что-то это начинает "попахивает" windows-way'ем %)
V>>... -- без установки! То есть скачал исходники нужной версии либы, собрал -- с нужными ключами -- и оставил лежать там же, не устанавливая в систему!
Z> да, точно это ОН %)
И снова наезд на Винду. Два-ноль!
Только я не понял, в чём заключается неправильность на этот раз. В том что нельзя тестировать с разными вариациями сборок (Debug/Release/x86/amd64/static/shared/rtti/no-rtti)?
Если так, то это что-то новенькое -- обвинения "виндузятнику" в настраиваемости -- из мира Линукса И кстати, я не являюсь чисто виндовым программером -- я переключаюсь между Виндой, несколькими дистрами Линукса и Маком, проводя в последнее время большую часть разработки на Арче.
V>Теперь, какая у меня модель настройки путей. Имеется файл paths.cmake в котором указаны явные пути, как-то так:
Z>отсюда и далее прослеживается очень распространенная bad practice (очевидно пришедшая из windows), мешающая масштаируемости, тиражируемости и воспроизводимости сборок %)
ОК, вы считаете, что иметь возможность настроить пути через конфигурационные файлы -- это "bad practice (очевидно пришедшая из windows)". Ваше мнение понятно, но я с ним не согласен.
Z> не говоря уже о том, что это усложняет жизнь newcomer'ам -- не достаточно просто знать CMake... нужно еще втыкать homecooked велосипет, и "перебрать" его моторчик не имея при этом его "чертежей" %) да и просто при "развертывании" рабочего места, это еще куча телодвижений...
Вы удобно выкинули часть моего сообщения (очевидно, чтоб было на что нападать). Если paths.cmake нет, то происходит сваливание в стандартные find_package/find_path/find_libs. Paths.cmake даёт возможность настроить явные пути тогда, когда автоматический подход не работает (или не желателен). И о какой куче телодвижений идёт речь?
Создать файл, состоящий из
set (LUA_LIB_DIR /home/vladimir/Develop/lua/lua-5.3.3/build/gcc-x86-debug)
...
-- это куча телодвижений? И то, это только для нестандартных путей! Если и так всё находится -- paths.cmake вообще не нужен!
Z>удивлюсь, если документированных где-то %)
Ссылка на билд-гайд дадена в самом первом посте. Есть мнение, что читать сообщения собеседника (даже если вы его воспринимаете как оппонента кусками -- неправильно.
V>Файл каскадный -- это означает, что он может лежать где угодно и влияет на все CMake проекты, находящиеся в поддиректориях.
Z>и ошибиться в нем может кто угодно?
Это вообще не аргумент. Ошибиться может кто угодно и где угодно, но означает ли это, что надо запретить конфигурационные файлы?
И кстати, в моей build-system происходит диагностический вывод путей, и все используемые пути (как найденные, так и из paths.cmake) отображаются на этапе CMake-configue.
V>Велосипед? Безусловно. Но с моторчиком! Очень удобно, особенно в случаях когда проектов много и надо делать кросс-сборки (причём и для отладки и для release),
Z> у меня куча cmake проектов и целевых платформ (сам я на gentoo) -- легко обхожусь без моторчика %) и вообще не вижу в нем необходимости для себя %)
Вот пример из прошлой недели, когда это реально понадобилось, и я в очередной раз убедился, что возможность настройки путей через внешние конфиги paths.cmake -- "the right thing to do".
Настраивал continuous integration через Travis CI.
Проблема 1. Нужен openssl на Маc OSX. Он ставится через homebrew -- и уже есть на виртуалке, предоставляемой Travis. Но СMake find_package/find_path его не видит! Поиск по stackoverflow даёт ответ -- надо вручную добавлять /usr/local/opt/openssl (либо как хинты к find_xxx либо напрямую компилятору)
Вместо модификации CMake файлов добавляю две строчки в .travis.yml
Проблема 2. Кросс компиляция amd64 -> ia32 на Linux том же Travis CI.
На Travis крутится Ubuntu 12 или 14. После установки multiarch и пакета libssl-dev:i386 CMake всё равно находит 64-битную версию, хоть ты тресни -- никакие FIND_LIBRARY_USE_LIB64_PATHS/FIND_LIBRARY_USE_LIB32_PATHS ни на что не влияют (протестировал самый распоследний CMake). Нужны явные пути.
Готово, линкуемся к правильной битности библиотеки.
Проблема 3. Кросс компиляция amd64 -> ia32, openSSL в проекте опциональна. Как было написано выше, CMakе находит неправильную 64-битную версию, что ведёт к фейлу компиляции. Можно установить libssl-dev:i386 и свести задачу к предыдущей, а можно:
echo "set (OPENSSL_INC_DIR DISABLED)" >> paths.cmake
# <-- any non-existent path will do
Готово, OpenSSL больше не находится.
Логи build matrix на 12 билдов можете посмотреть на http://travis-ci.org/vovkos
V>а также если хочется скачать и попробовать новую версию либы, не затрагивая систему -- не нужно устанавливать а потом сносить.
Z>это пожалуй единственный case когда я указываю hint finder'у на собранный пакет... а вот если новая версия понравилась и пошла в дело?
Установили новую версию в систему и удалили кастомный путь из paths.cmake
Z> "не затрагивать" систему, есть зиллиард способов... зависит от того что за "система".
Ого, 100500 потихоньку проапгрейдился до зиллиарда! Надо полагать, имеются в виду подходы с виртуализацией (чтоб была система на virtualbox/vagrant/docker/... и в неё устанавливать и тестировать)?
Это вариант, согласен; иногда по другому и не получается. Но если можно тестировать (и дебажить) на своём же хосте -- при этом без установки новых либ/тулзов и затрагивания системы -- я однозначно предпочту его. Хотя -- дело вкуса.
неговоря уже о деталях, ограничениях и области применения конкретной реализации.
и есть API для их получения %)
