Структура проекта 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 интерпретируются скриптом сборки проекта как JUnit-тесты, а потому должны быть исполнимыми (содержать "Main-методы").

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

Структура 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.
Имена инструментов должны отвечать следующему формату: <Тип входных данных><Тип выходных данных><Тип инструмента>. Например, инструмент, реализующий отображение EFSM-моделей в графический формат GraphML, носит название EfsmGraphMlPrinter.

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

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

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

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

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

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

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