Skip to content

Documentation (ru)

Jump to bottom Edit New page
dima.kruk edited this page Oct 8, 2013 · 36 revisions

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

Ливкодинг

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

COLT

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

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

Установка COLT

На сайте Code Orchestra скачать версию COLT для вашей операционной системы.

  • Win: Запустить установщик и следовать инструкциям.
  • Mac: Запустить dmg файл и перенести папку COLT в папку Applications.

При необходимости установить Java. Если вы используете Firewall, то необходимо добавить порты 6126 и 8091 в список разрешенных.

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

  • Не установлена java.
  • Недоступен порт начиная с 9091. Необходимо настроить firewall.
  • Не запускается приложение или компиялтор. Текущий пользователь должен иметь права на запись в папке программы и проекта (Windows). Необходимо установить папке с ее саб-директориями необходимые права.
  • Не запускается флэш приложение. Не установлен Standalone Flash Player. Установить c сайта http://adobe.com.
  • Неожиданные ошибки компиляции. Отключить autobuild в вашем IDE. В некоторых редакторах при изменении кода автоматически запускается процесс сборки приложения (Flash Builder). Так как вы собираете приложение через COLT, такая возможность редактора будет лишней.
  • В путях к исходникам находятся не поддерживаемые средой исполнения COLT символы, например символ решетки (#).

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

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

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

Обратите внимание на настойки проектов. Настройки находятся в закладках «Project 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(). Для того чтобы добавить такой код вы должны добавить в вашем IDE в проект colt.swc, который вы найдете в папке приложения COLT.

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

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 ресурсов

Кроме изменения кода COLT поддерживает доставку картинок и других файлов, которые вы указали в полях с аннотацией [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 
    } 
     
  });

Объекты класса AssetUpdateEvent имеют следующие свойства:

source (String) - путь к файлу ресурса, соответствующий параметру source аннотации [Embed(...)];

mimeType (String) - тип MIME, соответствующий параметру mimeType аннотации [Embed(...)];

assetClass (Class) - класс с обновлённым ресурсом (например Bitmap, ByteArray, и т.п.).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Какие трансформации кода происходят, чтобы избежать таких случаев:

  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 запустит процесс установки на следующее устройство).

##Какие изменения live кода доставляются во flash приложение

Изменение Поддержка
изменение тела метода √
добавление метода √
добавление статического метода √
добавление поля √
добавление статического поля √
создание нового класса X
изменение сигнатуры метода* Х
изменение конструктора X
изменение констант X
изменение значений полей X
изменение mxml классов X

*методы добавленные во время live сессии имеют возможность изменять сигнатуру и такое изменение будет доставлено в приложение

Add a custom footer
Add a custom sidebar
Clone this wiki locally