воскресенье, 15 декабря 2013 г.

Сложные моменты при изучении исходного кода LibreOffice

Открывая исходный код проекта LibreOffice в первый раз, можно испугаться количества кода, который придется разобрать. Только перевод файлов README может занять несколько дней, а разбор того, что всё таки имел ввиду автор — несколько недель. У меня возникла необходимость сделать небольшие улучшения, адаптации, поэтому мне пришлось в него углубиться, практически без проводников. Я постараюсь изложить свои наблюдения как можно яснее и подробнее. Эту статью я посвящу моментам, которые усложняют нам жизнь при чтении кода LibreОffice, а так же могут вызывать у нас неоднозначные понимания написанного.


История кода

К сожалению, из-за того что история кода насчитывает уже почти 30 лет, мы не сможет описывать изменения самого кода, но косвенно ориентируясь на выпуск готовых версий мы можем сделать некоторые свои заключения.
Код пакета LibreOffice начал своё существование как код проприетарной программы StarWriter for DOS, выпущенной компанией StarDivision, в далеком 1985 году. Сама немецкая компания была создана в 1984 году 16-летним программистом Марком Беррисом. Из этого мы можем сделать вывод что история кода начинается около 1984 года.
В 1994 году в свет вышла версия 2.0 пакета StarOffice, в который входили уже StarWriter, StarCalc и StarBase, эти программы могли работать под управлением Windows 3.1. В 1995 году вышла версия StarOffice 3.0, работавшая под управлением таких системам как DOS, Windows 3.1, OS/2, Solaris SPARC, Power Macintosh, и включающая в себя программы StarWriter, StarCalc, StarDraw, StarImage, StarChart. Именно эту дату в русской части энциклопедии Wikipedia называют началом существования пакета StarOffice. С чем связано такое суждение мне не известно. В июле 1996 года вышла версия 3.1, первая работающая под управлением Linux.
В 1999 году StarDivision была куплена компанией Sun Microsystems, пакет сменил владельца. Sun Microsystems выпустила свою первую версию StarOffice 5.2 под свободной лицензией. В этот момент отделяется ветвь OpenOffice.org, в который включается большое количество стороннего кода в виде модулей. Дальнейшие версии StarOffice основывались на работе сообщества OpenOffice.org. Надо заметить, что хотя код и основывался на коде сообщества, права на продукт и на бренд OpenOffice.org принадлежали Sun Microsystems. Sun Microsystems успела выпустить 5 версий продукта StarOffice, последняя версия которого была выпущена под номером 9.0 в ноябре 2008 года. За это же время вышло 4 версии OpenOffice.org, где OpenOffice.org 1.0 соответствует StarOffice 6, OpenOffice.org 1.1 соответствует StarOffice 7, OpenOffice.org 2.0 соответствует StarOffice 8, OpenOffice.org 3 соответствует StarOffice 9.
В 2002 году 22 мая появился дистрибутив BrOffice.org который был адаптирован под Бразилию и стал популярным в латинской Америке. Последний выпуск этого пакета был 22 марта 2011.
В 2003 году от проекта OpenOffice.org отделилась ветка Go-оо. Сначала это были просто патчи для проекта OpenOffice.org, а впоследствии стало отдельным офисным пакетом. Первый дистрибутив Go-оо в виде бинарных файлов, а не в виде пачей появился 8 октября 2007. Он имел уровень нестабильный. Последняя версия пакета вышла в 21 июня 2010 года.
За 2009 год компания Sun Microsystems была поглощена Oracle Corporation. В месте с патентами Sun Microsystems к Oracle Corporation перекочевали все права на бренды в том числе и на OpenOffice.org.
15 декабря 2010 года компания Oracle выпускает Oracle Open Office 3.3 который соответствует версии OpenOffice.org 3.3 beta. Это была первая и последняя версия Oracle OpenOffice. В неё не были включены свободные изменения Go-oo и BrOffice.org так как это бы помешало выпустить коммерческую версию Oracle OpenOffice.
Но за 1,5 месяца до выпуска Oracle Open Office, 28 сентября 2010 года разработчики и промоутеры сообщества OpenOffice.org объявили о создании независимого от Oracle ответвления офисного пакета под названием LibreOffice и организовали фонд The Document Foundation. После чего разработка Go-oo и BrOffice.org была остановлена в пользу LibreOffice и все наработки созданные командами объединились.

Развитие пакета StarOffice
Схема взята с сайта: https://en.wikipedia.org/

Отпечаток истории

Вся эта история красива и захватывающа, и если вы хотите подробностей вы можете сделать своё исследование, и вероятнее всего найдёте много интересного. Но я хотел бы поговорить именно о коде пакета.
Первое наследие которое мы получили от далекого прошлого кроме самого кода — это название модулей. Человеку, незнакомого с историей пакета, не сразу придёт в голову, что sw — это основной модуль Libreoffice Writer, а sc — это основной модуль Libreoffice Calc. Для того что бы это понимать нужно помнить что это были StarWriter и StarCalc сначала. Всё это было бы не страшно, но на сегодняшний день пакет имеет уже 216 модулей, и для того что бы получить поверхностное видение пакета нужно пару дней потратить, и стать немного историком (наверное, даже археологом).
Второе наследство — это старые форматы, фильтры и API. Старые функции — это действительно проблема. Разработчикам нужно постоянно помнить о том что существовала такая функция, которая не удобна, но которую нужно поддерживать. Или, к сожалению, нет возможности перевести весь код на одну функцию. Примером такого модуля может быть padmin/, в котором содержаться устаревшие диалог администрирования принтера, до сих пор использующиеся для некоторых вещах.
Также сюда можно отнести модули у которых есть графический интерфейс. Они могут иметь два варианта структуры каталогов. Это связано с тем, что до сих пор ведётся перевод их из .src/.hrc традиционного, но не гибкого формата к основанному на xml Glade/GTK3 формату (.ui).
Третье наследство которое мы получили — это полный бардак в описаниях.
Хотя в README.Code мы можем прочесть:
"Each module should have a README file inside it which has some degree of documentation for that module"
— "Каждый модуль должен иметь README файл внутри него, который имеет некоторую степень документации для этого модуля" на самом деле в README или иногда это README.txt мы находим только ссылку на страницу на которой должна быть информация.
Но и тут есть исключения, например, в модуле mysqlcppconn/ есть файл mysqlcppconn/README в котором написано:
"https://www.mysql.com/wiki/Connector_C++/".
При открытии страницы обнаруживаем, что её нет. Конечно, по названию понятно, что это драйвер mysql написанный на с++, но на этом знание об этом пакете, к сожалению заканчивается. На странице LibreOffice Modules мы не находим этого модуля совсем. Возникает вопрос, а нужен ли он вообще?
Возможно, проблемой стал отказ от строгой документации кода, который принят в фирмах, но напрочь отсутствует у свободных программистов.
В модуле tools/ мы можем прочесть следующее:
"Exact history is lost before Sept. 18th, 2000, but old source code comments show that part of the tools library dates back until at least April 1991".
А в модуле sw/:
"Exact history was lost before Sept. 18th, 2000, but old source code comments show that Writer core dates back until at least November 1990".
Как вы понимаете «Точная история была потеряна до 18 сентября 2000» связано с изменением владельца. Возможно при передаче кода между сторонами, по каким-то причинам произошла потеря части кода, или комментариев к этому коду. Теперь мы можем уже только гадать по поводу этого.
Ещё один пример из модуля libcdr:
«I couldn't find an upstream for this library - although I did only try a primitive Google search».
Я не совсем понимаю этой фразы, так как с информацией по этой библиотеке вместе с исходниками можно ознакомиться на странице libcdr сайта freedesktop.org. В архиве самой библиотеки есть README с коротким описанием.
Есть ещё одна проблема у которой корень забывчивость в исправлении комментариев: в некоторых комментариях, вроде бы подробных и интересно написанных мы находим ссылки на файлы и директории которых уже нет. И это прискорбно, потому что они нас только путают и тратят наше время в пустую, не принося нам совсем никакой пользы.
Конечно, всё это не особо критично. Постепенно изучая и проникая в структуру программы начинаешь понимать что и зачем нужно. Например, информация о модуле mysqlcppconn/ содержится в файле mysqlc/README, что, наверное, достаточно логично. Но для того что бы это понять, приходиться делать значительные усилия, и тратить время которое можно было бы потратить на что-нибудь более полезное. В итоге, если говорить образно, вместо того что бы мчаться слалом с горки на лыжах, мы пытаемся в этих лыжах маршировать по асфальту размахивая флагами и крича патриотические песни.

Вместо заключения

Начиная писать эту статью, я не собирался посвятить вас в тонкости перипетий исходного кода LibreOffice, но моя цель была подготовить вас к возможным трудностям понимания с которыми вы возможно сталкнётесь на пути изучения кода.
Я рекомендую вам при работе с исходным кодом:
  1. Всегда иметь браузер с поисковиком под рукой. Он часто позволяет быстро решить возникающие вопросы, найти, например, дополнительную информацию по стороннему модулю.
  2. Не забывайте историю пакета. Например, в тексте часто можно встретить фразу «Этот модуль часть проекта OpenOffice.org ..», не все комментарии изменены, с этим приходиться смериться.
  3. Используйте страничку LibreOffice Modules пусть она и не полная, но она позволит находить некоторые модули быстрее чем угадывание каталога.

Список литературы

К сожалению по данному вопросу я могу рекомендовать только не русскоязычные источники, в русских есть много неточностей, и небольшое количество ляпов.

Историческая справка в Wikipedia.org:
Исходный код проекта:
Помощь разработчикам:
Как дополнительная информация: