Project

General

Profile

Структура проекта Retrascope » History » Version 12

Sergey Smolov, 12/15/2014 09:24 AM

1 5 Sergey Smolov
h1. Структура проекта Retrascope.
2 1 Sergey Smolov
3 5 Sergey Smolov
В данном документе описывается структура каталогов и пакетов проекта Retrascope. При добавлении новых компонентов в проект необходимо обязательно удостовериться, что никакие требования настоящего документа не нарушаются.
4 1 Sergey Smolov
5 5 Sergey Smolov
Данная версия документа не является окончательной.
6
Любые замеченные орфографические, стилистические и пунктуационные ошибки могут быть исправлены разработчиками проекта без предварительного уведомления.
7
Однако любые случаи увеличения числа каталогов и пакетов проекта, влекущие за собой концептуальные правки данного документа, необходимо предварительно обсуждать.
8 1 Sergey Smolov
9 5 Sergey Smolov
h2. Структура каталогов
10 1 Sergey Smolov
11 5 Sergey Smolov
В проекте принята следующая структура каталогов:
12
13
1. Корневой каталог носит название _retrascope_. Каталог retrascope содержит следующие подкаталоги: _doc_, _share_, _src_.
14
15
1.1. Каталог _doc_ содержит документацию к инструменту Retrascope. Каталог не должен содержать материалов к сторонним инструментам, а также научных статей (в том числе описывающих инструмент Retrascope).
16
17
1.2. Каталог _share_ содержит используемые в проекте сторонние инструменты и библиотеки с открытым исходным кодом. Подкаталоги _share_ именуются в соответствии с расширениями используемых инструментов и библиотек. Например, Java-программы, представленные в виде jar-архивов, должны быть размещены в подкаталоге _share/jar_.
18
19 10 Sergey Smolov
1.3. Каталог _src_ содержит исходный код компонентов проекта Retrascope. Все компоненты проекта должны быть реализованы разработчиками проекта, любое использование стороннего исходного кода запрещено. Каталог _src_ содержит следующие подкаталоги: _main_, _test_, _sandbox_.
20 5 Sergey Smolov
21
1.3.1. Каталог _main_ содержит исходный код компонентов проекта Retrascope. Подкаталоги _main_ именуются в соответствии с языками программирования, на которых реализованы соответствующие компоненты. Например, компоненты, реализованные на языке Java, должны быть размещены в подкаталоге _main/java_. Более подробно структура Java-пакетов разссмотрена в разделе «Структура Java-классов».
22
23
1.3.2. Каталог _test_ содержит исходный код тестовых программ для компонентов проекта Retrascope. Подкаталоги _test_ именуются в соответствии с языками программирования, на которых реализованы соответствующие тестовые программы. Например, компоненты, реализованные на языке Java, должны быть размещены в подкаталоге _test/java_.
24
25
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@,
26 1 Sergey Smolov
 то тест должен быть размещен в файле @retrascope/test/java/ru/ispras/retrascope/basis/MyClassTestCase.java@. Классы с именами вида *TestCase интерпретируются скриптом сборки проекта как JUnit-тесты, а потому должны быть исполнимыми (содержать "Main-методы").
27 10 Sergey Smolov
28 11 Sergey Smolov
1.3.3 Каталог _sandbox_ предназначен для незавершенных и экспериментальных компонентов проекта Retrascope. Эти компоненты не включаются в сборку, осуществляемую с помощью Ant-скрипта.
29 1 Sergey Smolov
30 5 Sergey Smolov
h2. Структура Java-классов.
31 1 Sergey Smolov
32 6 Igor Melnichenko
При именовании Java-классов и Java-пакетов необходимо придерживаться рекомендаций, описанных в документе Google Code Style (см. [[Code Style Guide]]).
33 1 Sergey Smolov
34 6 Igor Melnichenko
При именовании Java-пакетов рекомендуется использовать имена существительные, отвечающие сущностям, а не процессам и пр. Длина имен не должна быть избыточной.
35 1 Sergey Smolov
36 5 Sergey Smolov
2. Базовый Java-пакет проекта Retrascope носит название *ru.ispras.retrascope*. Все Java-компоненты проекта должны располагаться в его внутренних подпакетах. Базовый пакет содержит следующие пакеты: *basis*, *engine*, *model*, *parser*, *result*, *util*. Базовый пакет проекта Retrascope содержит единственный класс, называемый *Retrascope*. Только указанный класс в проекте содержит метод main.
37 1 Sergey Smolov
38 5 Sergey Smolov
2.1. Пакет *basis* содержит компоненты, реализующие базовые сущности проекта. Предполагается, что эти сущности могут использоваться в классах, находящихся в пакетах того же уровня, что и *basis*, а также в их подпакетах любой вложенности.
39 1 Sergey Smolov
40 6 Igor Melnichenko
2.2. Пакет *model* содержит компоненты, реализующие внутренние представления моделей аппаратуры. Компоненты из подпакета *model.basis* могут использоваться в прочих подкаталогах пакета *model* (то же верно и для прочих подпакетов с вложенностю уровня *model*). Прочие подпакеты должны носить имена, совпадающие с именами соответствующих внутренних представлений. Например, все Java-компоненты, реализующие представление моделей аппаратуры в виде расширенного конечного автомата (extended finite state machine, EFSM), должны быть размещены в подпакете *model.efsm*.
41 1 Sergey Smolov
42 5 Sergey Smolov
2.3. Пакет *engine* содержит компоненты, реализующие анализ и преобразование моделей аппаратуры (далее - инструменты).Инструменты должны быть размещены по подпакетам, имена которых соответствуют входным и выходным данным. Например, инструмент, реализующий отображение EFSM-моделей в графический формат GraphML, должен быть размещен в подпакете *engine.efsm.<тип инструмента>.graphml*. 
43
В проекте принята следующая классификация инструментов по типам: *printer*, *generator*, *transformer*, *extractor*.
44
Имена инструментов должны отвечать следующему формату: *<Тип входных данных><Тип выходных данных><Тип инструмента>*. Например, инструмент, реализующий отображение EFSM-моделей в графический формат GraphML, носит название *EfsmGraphMlPrinter*.
45
46
2.3.1. Инструменты типа *printer* преобразуют подаваемую на вход модель в текстовый формат и сохраняют в виде набора файлов.
47
48
2.3.2. Инструменты типа *generator* выполняют анализ входных данных и строят сущности, обладающие новыми свойствами.
49
50
2.3.3. Инструменты типа *transformer* преобразуют модели из одного внутреннего представления в другое.
51
52
2.3.4. Инструменты типа *extractor* выполняют извлечение из входных данных некоторых параметров или свойств типа *result*.
53
54 8 Sergey Smolov
2.4. Пакет *result* содержит компоненты, описывающие некоторые избранные свойства или параметры. В пакете result хранятся классы, соответствующие выходным данным инструментов типа *extractor*, но не являющиеся моделями. Компоненты не должны содержать зависимостей от компонентов категории *model*, а также кросс-зависимостей. Компоненты должны быть размещены в под-пакетах, имена которых соответствуют их названиям.
55 5 Sergey Smolov
56 6 Igor Melnichenko
2.5. Пакет *parser* содержит выделенный класс инструментов. Все инструменты данного класса на вход получают набор текстовых файлов определенного формата, а на выходе строят их внутреннее представление, описанное в одном из подпакетов пакета *model*. В проекте Retrascope существует соглашение, обязывающее все инструменты класса *parser* возвращать модели типа *Cfg* (control flow graph, граф потока управления).
57 5 Sergey Smolov
Имена инструментов типа *parser* должны отвечать следующему формату: *<Формат входных данных>Parser*. Например, инструмент, получающих на вход файлы на языке описания аппаратуры Verilog, носит название *VerilogParser*.
58
59
2.6. Пакет *util* содержит компоненты, обеспечивающие упрощенное взаимодействие со сторонними компонентами и библиотеками.
60 12 Sergey Smolov
61
2.7 Рекомендуется размещать классы в тех пакетах, которым они соответствуют (например, в смысле наследования базовым классам Engine, Entity и т.п.). Например, нежелательно размещать наследников класса Entity в подпакетах пакета Engine и наоборот.