Документация COLT

Ливкодинг

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

COLT

Code Orchestra Livecoding Tool (COLT) инструмент для ливкодинга на флэш, созданный компаний Code Orchestra. COLT - первый инструмент такого рода для Flash. В нем используется несколько новых решений, которые позволили реализовать ливкодинг для среды исполнения Flash. Ранее считалось что ливкодинг для среды Flash реализовать невозможно, так как среда не поддерживает перегрузку классов.

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

Установка COLT

На сайте http://codeorchestra.com скачать версию COLT для вашей операционной системы.

Win: Запустить установщик и следовать инструкциям.

Mac: Запустить dmg файл и перенести папку COLT в папку Applications.

При необходимости установить Java (http://java.com/). Если вы используете Firewall, то необходимо добавить порт 6126 в список разрешенных.

Возможные проблемы при запуски и их решение

1. Не установлена java. (http://java.com)
2. Недоступен порт 6126 и 8091. Необходимо настроить firewall.
3. Папка с программой должна иметь права администратора (Windows). Приложение установлено из под аккаунта у которого нет прав администратора. Необходимо установить папке с ее саб-директориями необходимые права.
4. Не установлен Stand Alone Flash Player. Установить на сайте http://adobe.com.
5. Отключить autobuild в вашем IDE. В некоторых редакторах при при изменении кода автоматически запускается процесс сборки приложения (Flash Builder). Так как вы собираете приложение через COLT, такая возможность редактора будет лишней.
6. В путях к исходникам находятся не поддерживаемые средой исполнения COLT символы, например символ решетки (#).

Запуск приложения в режиме livecoding

Запустите любой из примеров проектов COLT. Примеры вы можете найти в папке «projects» в директории приложения COLT. После открытия проекта нажмите кнопку «Run» в верхней панели COLT. Приложение будет скомпилировано и открыто окно плеера. Если внизу, в статус баре появилось сообщение о начале сессии (зеленая иконка) и откроется дополнительная закладка с логами приложения, то все в порядке. Flash приложение работает в режиме livecoding. Если компиляция не прошла вам необходимо прочитать сообщений компилятора - закладка «FCSH».

Прочитайте readme.txt, который прилагается к каждому проекту. В readme.txt вам будет предложено открыть в текстовом редакторе файлы с классами и изменить в них строчки кода. При изменении кода и сохранении изменений на диск, флэш приложение должно изменять свой вид.

Обратите внимание на настойки проектов. Настройки находятся в закладках «Projects Paths», «Compiler Settings», «Live Settings» далее мы рассмотрим эти настройки более подробно.

Процесс изменении программы в режиме ливкодинга

При нажатии на кнопку «Run» запускается специальная компиляция, которая видоизменяет исходный код приложения так, чтобы каждый метод, который будет иметь возможность доставки изменений (live-method) перемещается в отдельный класс.

Терминология

Livecoding session - сессия ливкодинга. Запускается при нажатии кнопки «Run» в COLT. Приложение специальным образом собирается и открывается сокетное соединение между COLT и флэш-приложением.

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

Соединение - при подключении клиента открывается новое соединение. При открытии нового соединения открывается новая вкладка с логами.

Базовая компиляция - сборка приложения для начала ее работы в режиме ливкодинга и начала сессии. Базовый SWF.

Инкрементальная компиляция - компиляция только изменений кода, которые были совершены пользователем. По окончании такой компиляции создается swf файл («package_N») который помещается на диск рядом с базовым swf в папку «livecoding».

Live-class - класс все методы которого имеют поведение live.

Live-method - метод который имеет поведение доставки обновления кода на клиент.

Live Code Update Listener - специальный метод который отслеживает изменение кода.

Method registry - регистр live-методов. ActionScript класс, который хранит регистр методов.

Аннотации ливкодинга - специальные метаданные, которые позволяют управлять правилами, какой метод или класс будет иметь поведение ливкодинга.

Управление правилами покрытия кода ливкодинга

В большинстве случаев нет необходимости «ливкодить» весь код. Увеличивается время компиляции, возможны эффекты связанные с перехватом исключений и другое. Скорее всего вы будете работать всего с несколькими классами и методами. И вам важна доставка изменений именно в нужных вам методах.

Если же вы хотите, чтобы все методы вашего кода имели поведение ливкодинга вам нужно выбрать режим «All Methods» в закладке «Live Settings». Но мы все же рекомендуем режим ручного выбора.

Вы можете включить ливкодинг в методах, указав аннотацию [Live].

Чтобы включить все методы в классе (самая распространенная практика) нужно добавить аннотацию [Live] классу.

Для того чтобы отключить ливкодинг для отдельного метода нужно добавить аннотацию [LiveCodeDisable]. Так же этой аннотацией можно помечать весь класс (например, когда вы работаете в режиме «all methods» и хотите отключить отдельные классы).

Подписка на событие доставки изменений

Когда класс изменил свою реализацию приложение не сможет волшебным образом изменить свое состояние и вид на экране. Вы должны описать логику такого обновления. Обычная практика - выполнить специальный код во всех экземплярах такого класса, чтобы обновить состояние объекта. Например, перерисовать его на экране.

Самый постой способ такое сделать - это добавить метод с аннотацией [LiveCodeUpdateListener]. [LiveCodeUpdateListener] public function codeUpdate() : void { trace («code update!!!»); }

При добавлении такого метода-обработчики вам нужно перезапустить текущую лив-сессию.

Такой метод не должен иметь параметров. В противном случае вы получите ошибку компиляции.

Пример выше реагирует на все изменения кода внутри текущего класса. Всех методов.

Аннотация [LiveCodeUpdateListener] более простой способ добавления обработчика доставки изменения. Но в некоторых случаях удобно обратиться к регистру лив-методов и добавить обработчик обычным образом, через «addEventListener()». Для того чтобы добавить такой код вы должны добавить в ваш проект colt.swc, который вы найдете в папке приложения.

Для подписки на событие доставки кода добавьте следующий код -

`` LiveCodeRegistry.getInstance().addEventListener(MethodUpdateEvent.METHOD_UPDATE, function(e : MethodUpdateEvent) : void {

if (e.classFqn == "com.myPackage.MyClass" && e.methodName == "myMethod") { 
  // your logic 
} 

}); ``

На самом деле аннотация [LiveCodeUpdateListener] превращается компилятором COLT в практический такой же код. Но мы рекомендуем пользоваться именно аннотацией. Имя класса или метода вы можете указать в виде параметров:

[LiveCodeUpdateListener(classFqn="com.myPackage.MyClass", method="myMethod")] public function codeUpdate() : void { trace («code update!!!»); }

Доставка изменений EMBED ресурсов

Кроме изменения кода кольт поддерживает доставку картинок и других файлов, которые вы указали в полях с аннотацией [Embed].

Для того, чтобы обработать событие доставки любого ресурса, который описан в полях текущего класса вам нужно добавить аннотацию [LiveAssetUpdateListener].

`` [Embed(source="../assets/live_pic.png")] private var myEmbedField : Class;

[LiveAssetUpdateListener] public function assetUpdate() : void { trace "asset updated"; } ``

Чтобы подписаться на изменение конкретного Embded поля, вам нужно указать параметр «field»

`` [Embed(source="../assets/live_pic.png")] private var myEmbedField : Class;

[LiveAssetUpdateListener(field="myEmbedField")] public function assetUpdate() : void { trace "embedField updated"; } ``

Так же вы можете воспользоваться подпиской через AS3:

`` LiveCodeRegistry.getInstance().addEventListener(AssetUpdateEvent.ASSET_UPDATE, function(e : AssetUpdateEvent) : void {

if (e.source == "../assets/live_pic.png") { 
  var img : * = new e.assetClass(); 
  // your logic 
} 

}); ``

Описание аннотаций и их параметров

[Live] - Добавить поведение live методу или всем методам класса

[LiveCodeDisable] - запретить ливкодинг у метода или класса

[LiveAssetUpdateListener] - метод обработчик события доставки в флэш приложение обновления кода.

classFqn - полное имя класса, в котором произошли изменение. По умолчанию - текущий класс. Поддерживается значение «*» - все классы.

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

weak - мягкая ссылка при подписке. По умолчанию «true». Во избежании утечек памяти использовать другое значение параметра не рекомендуется.

priority - иногда нужно управлять порядком обработки событий обновления кода.

[LiveAssetUpdateListener] - метод обработчик события доставки изменений EMBED ресурсов.

field - имя EMBED поля (в текущем классе)

[LiveConsole] - аннотация аналогична [LiveAssetUpdateListener] в которой в параметре «method» указан метод, которым помечен этой аннотацией. Такой подохоод удобен тогда, когда вам нужно выполнить конкретный код один раз и тут же его стереть. Своеобразная консоль.

Автоматическое отключение поведения Live

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

1. Код в конструкторах классов. Код должен быть выполнен именно в конструкторе класса, поэтому чтобы поддержать изменение кода внутри конструктора вам нужно вынести такой код в отдельный метод;
2. Приватные методы, которые были «перегружены» в наследниках. То есть наследники класса имеют методы, которые имеют те же имена что в классе предке. Методы наследника будут иметь поведение ливкодинг, а в предке - нет.
3. Код в котором локальные переменные которого имеют аннотацию [Embed]
4. Геттеры и сеттеры не имеют поведение livecoding.(Вы можете его включить ливкодинг в геттерах и сеттерах в настройках «Live Settings»)
5. Методы с обращением к текущему методу - arguments.calle. Код из методов классов выносится в отдельный методы и вы не можете использовать arguments.calle в ливкодинге. Поведение Live будет отключено автоматически в таких классах.

Поведение автоматического перехвата ошибок и работа с «опасным кодом»

В процессе написания нового кода в лив-методе, вы можете допустить логическую ошибку, которая может привести к остановке приложения. Например, бесконечный цикл, бесконечная рекурсия и другое.

1. COLT автоматически оборачивает код в лив-методах в блок try/catch. При перехвате Exception в логе COLT появится сообщение (двойной клик на сообщении покажет stacktrace ошибки)

2. Ограничивает количество итераций циклов (по умолчанию 10000 итераций).

3. Вызов бесконечной рекурсии приведет к переполнению стэка и генерации ошибки флэш-плеером. Ошибка будет перхвачена и послана в лог.

Air. Мобильная разработка

В настройках «Live Settings» в target есть три варианта запуска. Выбрав третий вариант - «AIR», вы включите режим запуска лив-приложения на IOS устройстве.

Подключите IOS устройство по USB.

В настройках AIR приложения укажите пути к Apple сертификату и ваши имя пароль.

Укажите другие параметры (документацию по параметрам запуска AIR приложения вы можете найти на сайте adobe.com).

Удостоверьтесь что ваше IOS устройство находится в одной wifi сети с вашим рабочим компьютером.

При запуске ливкодинг сессии, будет установлено приложение на IPAD/IPhone и в COLT появится закладка с логами вашего приложения . Вы можете изменять исходный код приложения и Embed графику как в обычном flash приложении.

Немного дополнительной информации для понимания процесса ливкодинга на IOS устройстве.

Приложение на устройстве запускается в режиме development. Вы не можете использовать live режим в «продакшене».

AIR работает в режиме интерпретатора. Это может означать, что в реальном приложении скорость выполнения кода будет выше.

Приложение на устройстве общается с вашим компьютером по локальной сети, вы можете отключить подключение USB к компьютеру после старта лив-сессии, но устройство обязательно должно быть в той же локальной сети, и ваш компьютер должен разрешить доступ к нему по http (порт 8091) и через сокет (порт 6126).

Вы можете запустить несколько устройств к COLT (кнопка «+» рядом с кнопкой «Run» в верхней панели COLT запустит процесс установки на следующее устройство.