====== SpascharmRoot ======

===== Введение =====

Система SpascharmRoot основана на PandaRoot, используемая сотрудничеством ПАНДА. На данный момент за основу взят последний релиз PandaRoot -> jan16. По мере выходов новых релизов PandaRoot, планируется обновлять этот "базовый" для нас пакет.

Для удобства совместной разработки создан репозиторий [[http://svnbook.red-bean.com/en/1.7/svn-book.html|subversion]], который расположен по адресу: [[svn+ssh://svn.ihep.su/svn/SpascharmRoot/trunk]] (основная ветка разработки) (старый адрес http://star-kes.ihep.su/svn/SpascharmRoot/trunk вскоре будет отключен. Не делайте коммиты пожалуйста сюда). Для работы с репозиторием рекомендуется установить на локальную машину svn версии 1.7 или выше.

Структура проекта выглядит следующим образом:
   * PandaRoot/ - папка внешнего пакета PandaRoot (стараться делать как можно меньше изменений здесь)
   * U70ecal/ - исходные коды электромагнитного калориметра
   * U70guard/ - исходные коды охранной системы
   * U70hcal/ - исходные коды адронного калориметра
   * U70magnet1/ - исходные коды магнита мишени
   * U70muon/ - исходные коды мюонной системы
   * U70mwpc/ - исходные коды пропорциональных камер
   * cmake/ - скрипты для конфигурирования (создания) Makefiles для утилиты cmake
   * gconfig/ - конфигурационные макро для fluka, geant3, geant4, pythia6, pythia8, geane, root (для начала скопированы из PandaRoot, но их можно смело править)
   * geometry/ - файлы с описанием геометрии детекторов (.geo, .root, .dat)
   * input/ - входные файлы для различных генераторов частиц, карты магнитных полей, матрицы ошибок и тп
   * macro/ - root макро для запуска задач (моделирование, дигитизация, реконструкция, pid, анализ и тп)
   * CMakeLists.txt - основной файл описания конфигурации SpascharmRoot для утилиты cmake
   * CTestCustom.cmake

Предполагается вести разработку в директориях U70xxx (для детекторов) - любые алгоритмы/коды из PandaRoot можно смело копировать и/или наследовать и модифицировать в своем классе. 

===== Как установить SpascharmRoot =====

Чтобы установить SpascharmRoot у себя на машине нужно проделать несколько шагов:

  - Установить external packages ([[http://fairroot.gsi.de/|fairroot]]), который является внешним для всех систем в FAIR. На данный момент они состоят из двух подпакетов и последние их версии таковы: FairSoft - [[http://fairroot.gsi.de/?q=node/104|nov15]], FairRoot - [[https://github.com/FairRootGroup/FairRoot/releases|v-15.11a]] (Для ревизии SpascharmRoot 109 и ниже основной версией внешних пакетов была [[http://fairroot.gsi.de/?q=node/79|dec13]]). Установка описана на wiki PandaRoot [[https://panda-wiki.gsi.de/foswiki/bin/view/Computing/PandaRootInstallGit|PandaRoot wiki]].
  - Скачать на локальную машину исходные коды системы SpascharmRoot (потребуется ввести имя пользователя и пароль на кластере ИФВЭ): <code Bash> svn co svn+ssh://<username>@svn.ihep.su/svn/SpascharmRoot/trunk SpascharmRoot/trunk </code>, где <username> необходимо заменить на свое имя пользователя на КЛАСТЕРЕ ИФВЭ. 
  - Перейти в директорию с исходниками: <code  Bash> cd SpascharmRoot/trunk </code>
  - Установить переменную среды SIMPATH на путь до директории, где установлен FairSoft (директория инсталляции, не исходники!). Например: <code Bash> bash</code>  <code Bash> export SIMPATH=/path_to_fairroot/fairsoft_nov15/buildFairSoft </code>
  - Установить переменную среды FAIRROOTPATH на путь до директории, где установлен FairRoot (директория инсталляции, не исходники!). Например: <code Bash> bash</code>  <code Bash> export FAIRROOTPATH=/path_to_fairroot/fairsoft_nov15/buildFairRoot </code>
  - Создать директорию для компиляции системы: <code Bash> cd ../.. </code> <code Bash> mkdir spascharmroot_build </code> <code Bash> cd spascharmroot_build </code>
  - Выполнить конфигурацию (создание Makefile) с помощью утилиты cmake: <code Bash> cmake /path_to_dir/SpascharmRoot/trunk </code>
  - Выполнить компиляцию: <code Bash> make </code>
===== Как обновить SpascharmRoot =====

Чтобы обновить исходные коды в рабочей копии (в своей рабочей директории - кто-то другой мог что-то изменить в репозитории), необходимо выполнить команду:
<code Bash> cd SpascharmRoot/trunk </code>
<code Bash> svn update </code>
Чтобы посмотреть состояние рабочей копии (узнать какие изменения есть по сравнению с последней редакцией на сервере можно выполнить команду: <code Bash> svn status </code>
Чтобы получить общую информацию о svn репозитории (тип, пути до рабочей копии, репозитория, номер, дату и пользователя последней редакции) можно выполнить команду <code Bash> svn info </code>

===== Как зафиксировать сделанные изменения в коде SpascharmRoot =====

После того, как работа на кодом завершена можно выкладывать свои изменения на сервер svn (репозиторий). 

**Внимание! Большая просьба! Выкладывать изменения только, если вы убедились, что код компилируется!**.

Для фиксирования своих изменений достаточно выполнить команду: <code Bash> svn commit </code>
//Замечание:// При этом могут возникнуть конфликты, которые необходимо будет справить (svn сообщит какие и где). В документации по [[http://svnbook.red-bean.com/en/1.7/svn-book.html|subversion]] написано как это делать.

===== Использование IDE Eclipse для разработки =====
Довольно удобно (даже очень) использовать для разработки такого большого проекта интегрированную среду разработки (IDE), например [[http://www.eclipse.org/|eclipse]]. Eclipse снабжен такими полезными функциями как:
  * Удобное перемещение по коду с активными взаимными ссылками, то есть можно переходить в текст с описанием типа переменной, функции и тп. просто кликнув в том месте где такой объект используется. Другими словами все типы, классы, методы классов индексируются для такой возможности. 
  * Автодополнение кода - то есть, среда сама покажет какие методы есть у данного класса, когда вы объявили объект данного класса.
  * Проверка синтаксиса налету.
  * Интеграция с множеством систем компоновки (в том числе с cmake).
  * Интеграция с svn - все команды svn можно выполнять декларативно, кликая по пунктам меню.
  * Списки ToDo - если вставлен комментарий вида <code c++>//!TODO </code> среда напомнит об этом.
  * Встроенный debugger (правда в нашем случае это не очень актуально, так как при компиляции получаются библиотеки, которые вызываются из макро ROOT, однако для скомпилированного исполняемого кода он работает замечательно)
  * И еще множество замечательных функций. 

Приведем пример, как настроить проект SpascharmRoot в eclipse. //Пример описан для  Eclipse версии "Kepler" 4.3.1//. Для более старых версий процесс примерно похож. 

==== Инсталляция ====
 
Необходимо установить C++ версию на вашей системе:
  * Установить Java JRE [[http://www.java.com/|Java JRE]]
  * Установить Eclipse for C++ Developers
  * Установить плагин для SVN, лучше всего [[http://www.eclipse.org/subversive/|subversive]]  (иногда в дистрибутивах Linux - eclipse уже идет с этим плагином). Не рекомендую плагин subclipse от tigris.org - мне так и не удалось через него авторизоваться на нашем кластере, subversive намного более гибкий.

==== Создание проекта SpascharmRoot, начиная с текущей рабочей версии из svn ====

  * Убедитесь что установлены переменные среды окружения, вызвав config.sh из директории где собирается проект (spascharm_build)
  * Запустите Eclipse перейдя в его директорию установки <code Bash> ./eclipse </code>. Можно также запустить его из меню.
  * Появится запрос выбора рабочей области (можно оставить название по умолчанию или назвать по-своему)
{{howto:root:eclipse1.png}}
  * Откроется страница "Обзор"(Overview). Можно ее закрыть, перейдя в рабочее пространство.
  * Выбрать Файл -> Создать -> Проект (Или сразу C++ project)
  * Откроется диалог создания проекта
  * Выбираем С++ Project, нажимаем Далее
{{howto:root:eclipse2.png?x800}}
  * Указываем Имя проекта, например spascharmroot
  * Снимаем галку "Расположение по умолчанию" и выбираем вашу директорию с исходниками SpascharmRoot
  * Выбираем Project Type: Makefile project и Toolchain: Linux GCC
{{howto:root:eclipse3.png?x800}}
  * Нажимаем Готово
  * После этого проект настроен и код будет проиндексирован
  * Если все ок к этому моменту вы должны увидеть следующее:
{{howto:root:eclipse4.png?800}}
{{howto:root:eclipse5.png?800}}

==== Настройка системы компоновки (компилятора) ====
  * Выберите в меню: Проект -> Свойства
  * В открывшемся диалоговом окне выберите С/C++ Build
  * Во вкладке Builder Settings укажите свою директорию для компиляции (например spascharm_build):
{{howto:root:eclipse6.png?x600}}
  * Во вкладке Tab Behaviour очистите поле "Build (incremental build)":
{{howto:root:eclipse7.png?x600}}
  * Теперь проект должен собраться (откомпилироваться). Можно наблюдать прогресс сборки во вкладке "Косносль" внизу окна IDE.
  * Для запуска процесса компиляции нажмите на значок "Молотка" в панели инcтрументов IDE. 
  * Все готово для работы в Eclipse! 
{{howto:root:eclipse8.png?1000}}
{{howto:root:eclipse9.png?1000}}

==== Добавление в проект исходных кодов ROOT ====

Для того, чтобы иметь доступ к описаниям классов ROOT (для автозаполнения и тд) нужно сделать следующее:
  * Правой кнопкой мыши кликнуть на проекте spascharmroot в "Структуре проекта"
  * Выбрать Создать -> Папка
  * В появившемся диалоге указать "Имя папки", например ROOT
  * Нажать кнопку "Дополнительно"
  * Выбрать в списке "Link to alternate location (Linked Folder)" и укажите папку, где установлен ROOT - например /data/fairsoft/tools/root. Так как ROOT - это монстро-подобная программа, то индексация займет довольно продолжительное время. Более легкий вариант - указать только папку include из инсталляции ROOT (будут доступны только заголовочные файлы ROOT).    
{{howto:root:eclipse10.png?x600}}
{{howto:root:eclipse11.png?1000}}

==== Некоторые дополнения ====
=== Номера строк в редакторе ===
Для удобства работы с кодом и отладки в редакторе хорошо бы видеть номера строк. Для этого надо сделать следующее:
  * Выбираем из меню Окно -> Параметры
  * В открывшемся диалоге раскрываем Общие -> Редакторы -> Текстовые редакторы и ставим галку на "Показать номера строк"
{{howto:root:eclipse12.png?x800}}

=== Поддержка SVN ===
Если Eclipse уже имеет плагин поддержки SVN то среда сама разберется, что папка проекта, который вы добавили находится под контролем версий SVN и сама подцепится к репозиторию. При этом в "Структуре проекта" напротив файлов будут показаны номер ревизии, дата и автор последнего изменения, кроме этого файлы и папки будут иметь иконки, указывающие на различные состояния svn (есть, нет отличий от версии в репозитории и тп). И также становятся доступны все команды svn из меню Team.

Если этого не произошло, то самый простой способ такой - сделать checkout проекта напрямую из svn:
  - Подключить новый репозиторий через [[https://eclipse.org/subversive/documentation/teamSupport/new_location_wiz.php|subversive]]
  - Сделать checkout проекта: меню Создать → Проект → SVN → Project from SVN.

Как говорится в подобных случаях: "Happy coding!" 8-O

=== Запуск пакетной обработки файлов для анализа ===

В системе реализована пакетная обработка файлов. Существует два варианта такой обработки:
  - Чтение .dat файлов ("сырые" файлы из daq) и запись деревьев в .root файлы;
  - Чтение деревьев из .root файлов для отображения гистограмм в online-мониторе online_gui_sm.

Для запуска варианта 1) необходимо выполнить следующие команды (пример приведен для машины lab3onl):

<code  Bash> cd spascharmroot_exec </code>
<code  Bash> ./batchRawToRoot.sh test </code>, где "test" - директория для обработки. 
Директория, переданная как параметр будет обрабатываться рекурсивно. То есть, можно например указать весь run0XX и обработаются также файлы из поддиректорий, в которых лежат файлы, разбитые по часам. 

Для запуска варианта 2), то есть отображение онлайн-гистограмм на уже записанных данных, необходимо выполнить:
<code  Bash> root 'online_gui_sm.C(kFALSE, "test")' </code>, где первый параметр: kTRUE/kFALSE - мода работы (online или пакетная обработка), второй параметр - директория из которой брать файлы. Директория также обрабатывается рекурсивно.