Участник:Sementry/Гайд по vizi

Дон Хуан добавил, что в его мире подарков не раздают и что всякое знание дается в нем великим трудом.

(К. Кастанеда, "Учение Дона Хуана")

Если вы зашли на эту страницу, то, вероятнее всего, вы не хотите самостоятельно разбираться с устаревшими недокументированными системами. Возможно, у вас нет на это времени, возможно, вам это не интересно, может быть, вам просто лень. Тем не менее, вы готовы написать много-много кода на Java и XML, а потом долго-долго его дебажить. Так или иначе, вы оказались здесь, потому что хотите разобраться с Vizi и написать визуализатор.

Что же такое Vizi? Это, в некотором роде, фреймворк, который должен облегчить разработку визуализаторов. К сожалению, из-за плохой и незавершенной документации написание приложения с использованием vizi скорее усложняется, а не упрощается. Этот гайд написан для того, чтобы можно было более-менее сориентироваться в процессе разработки и, вопреки всем препятствиям, написать что-то адекватно работающее.

Подготовка

Установка

Скачиваем последнюю версию Vizi, бинарики предпоследней, Java 1.1.8 classes и собранный Apache Ant.

Распаковываем куда-нибудь последнюю версию Vizi. В папку meta копируем файл "classes-1.1.8.jar". Создаем папку /meta/bin и копируем содержимое папки apache-ant-1.8.2 туда (чтобы получились папки /meta/bin/bin, /meta/bin/lib, etc.). Туда же, куда распаковали последнюю Vizi (т.е. туда, где лежит корневая папка vizi), распаковываем бинарники предпоследней, дополняя недостающие файлы. Заменять новые версии старыми не нужно.

Теперь надо немного подправить xml-файлы для сборки, конечно, если у вас нет Java 1.1. В /meta/scripts/build/build-compile.xml исправляем debuglevel на "lines,vars,source" в 154 строчке и target на "1.7" или "1.6" (в зависимости от версии jdk). Возможно, нужно исправить что-то еще, но, мне кажется, это все. (если этого недостаточно, нужно исправить аналогичным образом строчки 137 и 138 --Иван Раков 02:01, 18 декабря 2011 (MSK))

Для пользователей Windows

Добавляем в систему переменную окружения java_home, в ней прописываем путь к jdk. Путь не должен содержать пробелов. Hint: в Windows можно заменить "Program Files" на "Progra~1". А "Program Files [x86]" на "Progra~2", да.

(Если что-то не получается, можно попробовать прописать адреса вручную в ant.bat --Андрей Рыбак 18:36, 15 января 2012 (MSK))

Возвращаемся в корень папки vizi и пробуем запустить ant.bat без параметров. Если я написал эту часть гайда правильно, а вы правильно выполнили предыдущие действия, то все должно скомпилироваться, вы получите сообщение "BUILD SUCCESSFUL", а в корне появится новая папка deploy, в которой будет лежать визуализатор для поиска максимума.

Для пользователей Linux

Как вы могли заметить, для сборки проекта в vizi есть файлик ant.bat. Для того, чтобы получить соответствующий файл для сборки понятный Linux, выполните следующие действия:

В системе должны быть прописаны соответственные переменные окружения. Посмотрите на свой ~/.profile (или на ~/.bashrc, тогда надо будет всего лишь открыть новую консоль, а не перелогиниваться --Дмитрий Герасимов) (еще можно написать все это прямо в ant.sh, тогда не надо будет новую консоль открывать) и добавьте при необходимости следующие строчки:

JAVA_HOME=/путь/к/jdk
export JAVA_HOME

JDK_HOME=$JAVA_HOME
export JDK_HOME

JRE_HOME=$JAVA_HOME/jre
export JRE_HOME

ANT_HOME=/путь/к/ant
export ANT_HOME

PATH=$PATH:$JDK_HOME/bin
PATH=$PATH:$JRE_HOME/bin
PATH=$PATH:$ANT_HOME/bin
export PATH

Для того, чтобы все изменения .profile вступили в силу, нужно перезагрузить машину (или завершить сеанс пользователя и снова зайти)

Ок, переменные окружения мы прописали. Теперь в папке с vizi создайте файл ant.sh, дайте ему права на выполнения командой chmod +x ant.sh и поместите в него следующее содержимое:

#!/bin/sh

CLASSPATH=`find meta/bin/lib -maxdepth 3 -name '*.jar' -printf '%p:'`$CLASSPATH
CLASSPATH=`find $JDK_HOME -maxdepth 3 -name '*.jar' -printf '%p:'`$CLASSPATH

export CLASSPATH

exec \
java -classpath "$CLASSPATH" \
org.apache.tools.ant.Main $*

Запускаем командой ./ant.sh, должно всё получиться. В папке deploy должен валяться визуализатор примера.

Дальше

Для того, чтобы скомпилировать что-то еще, нужно исправить строчку project в файле build.properties на путь к нужному проекту. Другие визуализаторы можно взять в Term3. Если у вас собирался поиск максимума, а при попытке сделать то же самое с другим визуализатором начинают появляться ошибки о недостающих классах, то можно взять их из архива rt.jar в jdk и добавить в classes-1.1.8.jar. Также можно просто заменить classes-1.1.8.jar на rt.jar, правда, если это кого-то волнует, он весит на порядок больше. UPD: проблема в том, что конкатенация строк через "+" в Java, похоже, реализована через класс StringBuilder, который появился только в 5 версии. Если вы хотите, чтобы ваш визуализатор полностью соответствовал предъявляемым к нему требованиям, воспользуйтесь методом concat().

Ура-ура, теперь мы умеем собирать правильно написанный готовый визуализатор!

Теперь рекомендуется открыть и прочесть docs/readme.html, если вы вдруг это еще не сделали. Что-то пока будет непонятно, но, по крайней мере, вы узнаете про параметры запуска vizi.

Написание визуализатора

Теперь можно начать писать свой собственный визуализатор. Предварительно я настоятельно рекомендую прочесть спецификацию используемых XML-описаний.

Структуру проекта можно посмотреть в примерах. Если вы хотите пользоваться какой-нибудь средой разработки, то, вероятно, вам понадобятся исходные коды vizi, которые поставляются вместе с ней и также лежат в папке projects/vizi, ее содержимое нужно скопировать в папку вашего проекта, тогда IDE будет знать, что за классы вы хотите использовать. Компилить проект нужно все тем же запуском ant.bat, дебагать из-под IDE не получится, используйте debug-output.

%your_project%.xml

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

%your_project%-algorithm.xml

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

У нас есть конструкции step для присвоений, if-then-else для переменных, while для циклов и call-auto для вызова функции. Можно спокойно объявлять и пользоваться одиночными переменными и массивами примитивных типов, с другими объектами могут возникнуть внезапные осложнения. В спецификации сказано, что переменные бывают локальными и глобальными. Это не так, реальная область видимости у всех переменных одна и та же; главное отличие состоит в том, что значение по умолчанию у глобальных переменных обязательно присутствует, а у локальных — обязательно отсутствует. Поэтому с рекурсией все грустно, если она необходима, то, видимо, нужно написать стек самостоятельно, либо использовать на свой страх и риск объект stack, который Vizi сама пропишет(но позже там могут возникнуть проблемы с обращением автомата). Можно также схалтурить и написать основную часть кода в визуализаторе, а xml-файл менять как угодно, лишь бы только запланированное разбиение вашего алгоритма на шаги, которые будет видеть пользователь, оставалось прежним.

Рекомендуемый способ разработки: взять тщательно протестированный и уже сданный код вашего алгоритма на Java, выкинуть из него все сложные классы и языковые конструкции, включая рекурсию и циклы for и свалить все переменные в одну кучу "class Data". Сохраните люмпенизированный таким образом код и убедитесь в том, что он все еще работает так, как надо. Теперь полученный код можно постепенно перерабатывать в xml-файл, окружая все действия нужными тегами. Пока лучше ничего не рисовать, тег draw можно добавить и потом.

Аргументы в комментарии к шагу задаются как {0}, {1}, etc. Если вы не хотите показывать какой-то шаг пользователю, комментария у него нет, а он все равно показывается, сделайте значение level равным -1.

Когда все напишете, запустите ant.bat с параметром debug-source. Если где-то есть ошибка, то вам скажут, где именно. Если все написано верно, то версия кода для дебага должна появиться в папке src/ru/ifmo/vizi/%your_project%/%your_project%Debug.java. Сравните ее на похожесть с ранее упрощенным кодом, должно получиться примерно то же самое. Подебажьте сгенерированный код и убедитесь в том, что оно и работает так, как запланировано. Если все хорошо, то можно запустить ant.bat без параметров, сборка не дойдет до конца, но вы сгенерируете код src/ru/ifmo/vizi/%your_project%/%your_project%.java, который написан уже в стиле автоматного программирования и пригодится вам для написания визуализатора в вашей любимой IDE.

Пример функции

<auto id = "test" description = "факториал">
    <variable 
        description = "Переменная цикла для test"
        name ="testI"
        type = "int"
    />
    <step id = "testInit" description = "" level = "-1">
        <action>
            @testI @= 1;
            @testResult @= 1;
        </action>
    </step>
    <while
        id="testLoop"
        description="loop"
        test="@testI & lt;= @testArgument" <!--после амперсанда пробела не должно быть-->
        level="-1"
    >
        <step id = "testLoop1" description = "ololo" level = "-1">
            <action>
                @testResult @= @testResult * @testI;
                @testI @= @testI + 1;
            </action>
        </step>
    </while>
</auto>

По невыясненной причине все функции должны быть описаны в самом конце тега algorithm.

Пример вызова функции

<step id = "testArgs" description = "" level = "-1">
    <action>
        @testArg @= @n;
    </action>
</step>
<call-auto id = "test" />
<step id = "getFact" description = "" level = "-1">
    <action>
        @fact @= @testResult;
    </action>
</step>

%your_project%-configuration.xml

Из этого файла будут подгружаться все параметры для вашего визуализатора. Никаких констант, все должно конфигурироваться через XML! Опять же, начать можно с частей уже готовых проектов, оставив более тонкую настройку на потом.

src/ru/ifmo/vizi/%your_project%/%your_project%Visualizer.java

Рекомендуемый способ разработки: взять аналогичный код для поиска максимума и выкинуть из него все лишнее, запустить ant.bat без параметров, убедиться в том, что визуализатор собирается и запускается. Если все прошло успешно, то при запуске вы увидите окошко белого цвета с серой панелькой внизу. На заднем плане будет чернеть консолька, ее, как уже было ранее упомянуто, полезно использовать для debug-output'а.

На этом этапе полезно запустить ant.bat c параметром docs и почитать сгенерированный javadoc.

Если вам нужен какой-то компонент, которого нет в vizi, то ищите его в AWT. Если вам нужен какой-то графический примитив, то, возможно, придется написать его самостоятельно. Код некоторых графических примитивов можно посмотреть, например, в SegmentsTree\src\ru\ifmo\vizi\SegmentsTree\widgets.

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

Как дебажить визуализатор

Хинт для тех, кто хочет дебажить финальную версию своего визуализатора в своей IDE. Подключите к своему проекту исходники vizi и два jar файла: vizi-0.4b7.jar и jar вашего визуализатора. И создайте класс, где вы будете запускать FrameView.main(). В аргументах main укажите локаль.

ссылки

• [1] - моя папка vizi, со всеми необходимыми частями и всевозможным мусором;
• [2] - страничка vizi на neerc.ifmo.ru.