Структура проекта Retrascope.¶

В данном документе описывается структура каталогов и пакетов проекта Retrascope. При добавлении новых компонентов в проект необходимо обязательно удостовериться, что никакие требования настоящего документа не нарушаются.

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

Структура каталогов¶

В проекте принята следующая структура каталогов:

1. Корневой каталог носит название retrascope. Каталог retrascope содержит следующие подкаталоги: doc, share, src.

1.1. Каталог doc содержит документацию к инструменту Retrascope. Каталог не должен содержать материалов к сторонним инструментам, а также научных статей (в том числе описывающих инструмент Retrascope).

1.2. Каталог share содержит используемые в проекте сторонние инструменты и библиотеки с открытым исходным кодом. Подкаталоги share именуются в соответствии с расширениями используемых инструментов и библиотек. Например, Java-программы, представленные в виде jar-архивов, должны быть размещены в подкаталоге share/jar.

1.3. Каталог src содержит исходный код компонентов проекта Retrascope. Все компоненты проекта должны быть реализованы разработчиками проекта, любое использование стороннего исходного кода запрещено. Каталог src содержит следующие подкаталоги: main, test, sandbox.

1.3.1. Каталог main содержит исходный код компонентов проекта Retrascope. Подкаталоги main именуются в соответствии с языками программирования, на которых реализованы соответствующие компоненты. Например, компоненты, реализованные на языке Java, должны быть размещены в подкаталоге main/java. Более подробно структура Java-пакетов рассмотрена в разделе «Структура Java-классов».

1.3.2. Каталог test содержит исходный код тестовых программ для компонентов проекта Retrascope. Подкаталоги test именуются в соответствии с языками программирования, на которых реализованы соответствующие тестовые программы. Например, компоненты, реализованные на языке Java, должны быть размещены в подкаталоге test/java.

1.3.2.1. Тестовые программы для компонентов Retrascope, реализованных на языке Java, должны быть реализованы с использованием библиотеки модульного тестирования JUnit (http://junit.org/). Тестовые программы на языке Java должны размещаться в тех же Java-пакетах (package), что и тестируемые компоненты, но в каталоге test/java. Например, если тест проверяет корректность работы класса, находящегося в файле retrascope/src/main/java/ru/ispras/retrascope/basis/MyClass.java,
то тест должен быть размещен в файле retrascope/test/java/ru/ispras/retrascope/basis/MyClassTestCase.java. Классы с именами вида *TestCase и *TestSuite интерпретируются скриптом сборки проекта как JUnit-тесты, а потому должны содержать методы, аннотированные @Test.

1.3.3 Каталог sandbox предназначен для незавершенных и экспериментальных компонентов проекта Retrascope. Эти компоненты не включаются в сборку.

Структура Java-классов.¶

При именовании Java-классов и Java-пакетов необходимо придерживаться рекомендаций, описанных в документе Google Code Style (см. Code Style Guide).

При именовании Java-пакетов рекомендуется использовать имена существительные, отвечающие сущностям, а не процессам и пр. Длина имен не должна быть избыточной.

2. Базовый Java-пакет проекта Retrascope носит название ru.ispras.retrascope. Все Java-компоненты проекта должны располагаться в его внутренних под-пакетах. Базовый пакет содержит следующие пакеты: basis, engine, model, parser, result, util. Базовый пакет проекта Retrascope содержит единственный класс, называемый Retrascope. Только указанный класс в проекте содержит метод main.

2.1. Пакет basis содержит компоненты, реализующие базовые сущности проекта. Предполагается, что эти сущности могут использоваться в классах, находящихся в пакетах того же уровня, что и basis, а также в их под-пакетах любой вложенности.

2.2. Пакет model содержит компоненты, реализующие внутренние представления моделей аппаратуры. Компоненты из подпакета model.basis могут использоваться в прочих подкаталогах пакета model (то же верно и для прочих подпакетов с вложенностью уровня model). Прочие под-пакеты должны носить имена, совпадающие с именами соответствующих внутренних представлений. Например, все Java-компоненты, реализующие представление моделей аппаратуры в виде расширенного конечного автомата (extended finite state machine, EFSM), должны быть размещены в под-пакете model.efsm.

2.3. Пакет engine содержит компоненты, реализующие анализ и преобразование моделей аппаратуры (далее - инструменты).Инструменты должны быть размещены по под-пакетам, имена которых соответствуют входным и выходным данным. Например, инструмент, реализующий отображение EFSM-моделей в графический формат GraphML, должен быть размещен в подпакете engine.efsm.<тип инструмента>.graphml.
В проекте принята следующая классификация инструментов по типам: printer, generator, transformer, extractor, simulator.
Имена инструментов должны отвечать следующему формату: <Тип входных данных><Тип выходных данных><Тип инструмента>. Например, инструмент, реализующий отображение EFSM-моделей в графический формат GraphML, носит название EfsmGraphMlPrinter.

2.3.1. Инструменты типа printer преобразуют подаваемую на вход модель в текстовый формат и сохраняют в виде набора файлов.

2.3.2. Инструменты типа generator выполняют анализ входных данных и строят сущности, обладающие новыми свойствами.

2.3.3. Инструменты типа transformer преобразуют модели из одного внутреннего представления в другое.

2.3.4. Инструменты типа extractor выполняют извлечение из входных данных некоторых параметров или свойств типа result.

2.3.5. Инструменты типа simulator выполняют входные модели.

2.4. Пакет result содержит компоненты, описывающие некоторые избранные свойства или параметры. В пакете result хранятся классы, соответствующие выходным данным инструментов типа extractor, но не являющиеся моделями. Компоненты не должны содержать зависимостей от компонентов категории model, а также кросс-зависимостей. Компоненты должны быть размещены в под-пакетах, имена которых соответствуют их названиям.

2.5. Пакет parser содержит выделенный класс инструментов. Все инструменты данного класса на вход получают набор текстовых файлов определенного формата, а на выходе строят их внутреннее представление, описанное в одном из под-пакетов пакета model. В проекте Retrascope существует соглашение, обязывающее все инструменты класса parser возвращать модели типа Cfg (control flow graph, граф потока управления).
Имена инструментов типа parser должны отвечать следующему формату: <Формат входных данных>Parser. Например, инструмент, получающих на вход файлы на языке описания аппаратуры Verilog, носит название VerilogParser.

2.6. Пакет util содержит компоненты, обеспечивающие упрощенное взаимодействие со сторонними компонентами и библиотеками.

2.7 Рекомендуется размещать классы в тех пакетах, которым они соответствуют (например, в смысле наследования базовым классам Engine, Entity и т.п.). Например, нежелательно размещать наследников класса Entity в подпакетах пакета Engine и наоборот.