Continuous Integration for CS Extension Builder
So you have some awesome extensions for the Creative Suite, built with Adobe CS Extension Builder 1.5, but you are still exporting them via Flash Builder…
It is high time to build them automatically: if it can’t be automated, it ain't real...
Well, good news, the Adobe Creative Suite team has thought about it, and all the required pieces are available. (They just might be spread a bit all over the place… therefore I compiled the following manual to get started more quickly.) As for Flex or Air applications, ANT is the tool of choice, with specific compilations tasks available in the Flex SDK.
Preliminaries
First thing, even though you already downloaded and installed Flash Builder 4.5 and the Extension Builder, it doesn’t include the command line tools and libraries in a direct manner. Like a cooking recipe, let’s start with the ingredients:
-
One full package of CS SDK Free 1.5 (http://www.adobe.com/devnet/creativesuite/sdk/eula_cs5.html). The Flex SDK is embedded in it.
-
A good old installation of Apache Ant
-
A few drops of Signing Toolkit (http://www.adobe.com/devnet/creativesuite/sdk/eula_cs5_toolkit.html)
-
Flash Builder 4.5 and CS Extension Builder already installed. You shouldn’t need them, but you still need them, at least for the preparation, fortunately not at the end on your build server. (Hudson or Cruise Control for example will do fine with your Ant script and the SDKs.)
First wonder, why do we need to download both the CS SDK and the signing toolkit, while these are probably embedded in some mysterious and hidden way in the CS Extension Builder? I would like Adobe to ship the CS SDK with the signing toolkit in a first step, and even to see the full CS SDK embedded in the CS Extension Builder in a second step. It would make things clearer, so that we can find the SDK on the file system after having installed CS Extension Builder only. We would avoid downloading all three of them.
Compiling SWF
Let’s start with the basic, if you’re not new to Flex/Air, it should look familiar.
We can first declare some variables to refer to the different SDKs. Fortunately the required Flex SDK is embedded in the CS SDK:
<!-- Adobe SDKs -->
<property name="CSSDK_HOME" value="c:\\dev\\Flex\\SDKs\\CSSDK 1.5.0"/>
<property name="FLEX_HOME" value="${CSSDK_HOME}/CS Flex SDK 3.4.0"/>
<property name="SIGNING_TOOLKIT_HOME" value="c:\\dev\\Flex\\SDKs\\signingtoolkit"/>
Then, we can load the required Flex tasks to compile our extension, and these too are found in the Flex SDK:
<!-- Flex compilation tasks -->
<taskdef resource="flexTasks.tasks" classpath="${FLEX_HOME}/ant/lib/flexTasks.jar"/>
And we are ready for a good old “mxmlc” compilation, pointing to your main mxml file:
<mxmlc
file="${SRC}/main.mxml"
keep-generated-actionscript="false"
actionscript-file-encoding="UTF-8"
allow-source-path-overlap="true"
debug="false"
incremental="false"
verbose-stacktraces="true"
output="${BUILD}/CtrlPublishing_CI.swf">
<source-path path-element="${SRC}"/>
</mxmlc>
Now running that via ant should return a few compilations errors, we need to add the Flex libraries. You need to point to the air-config compilation profile, that will refer to the proper libraries. If you do so, do not add the framework libraries from the Flex SDK to your compilation path.
<load-config filename="${FLEX_HOME}/frameworks/air-config.xml" />
Still some compilation errors, we also need the CS specific Flex libraries, also depending on what your extension uses: CS Host adapter libraries, CSXS libraries, and CSAW libraries. You can find all of them in the CS SDK (almost, see further).
My advice is to use Flash Builder, and go to your project properties. In the Build Path view, you will see all the libraries that your project needs:
For example, for my InDesign extension, here are the libraries I need:
<compiler.external-library-path dir="${CSSDK_HOME}/libs/cslibs/1.0/3.4/release" append="true">
<include name="apedelta.swc"/>
</compiler.external-library-path>
<compiler.library-path dir="${CSSDK_HOME}/libs" append="true">
<include name="id_host_adapter.swc"/>
<include name="CSXSLibrary-2.0-sdk-3.4-public.swc"/>
</compiler.library-path>
<compiler.library-path dir="${CSSDK_HOME}/libs/cslibs/1.0/3.4/release" append="true">
<include name="csaw_indesign.swc"/>
</compiler.library-path>
Notice here that you have to import apedelta.swc as an external library, else the extension will install, but the UI will never show up...
Be careful, the CS SDK provides two versions of the CSAW libraries, 1.0 and 1.5. It seems that it is only possible to link to the 1.0 version through CS Extension Builder, even though you install the 1.5 version… I am not sure why, but let’s just do the same in our ANT script.
As for the CS host adapter libraries, they are unfortunately missing from the CS SDK… I am wondering if it is a simple miss from the Adobe team, or if it will never be embedded?
Well, we can solve it for ourselves now, hoping that it will be included in the next release. And this is where we need the Extension Builder anyway. Locate your installation folder (the one you pointed to when installing it in Flash Builder). In the “plugins” folder, find the JAR file named "com.adobe.cside.libsinstaller_1.5.0.201103311826". Unzip it, and browse to "archive/csar-1.0/release/". Copy the ones you need inside your CS SDK libs folder (id_adapter.swf in my example), where they should have been in a first place. (Or should they?)
Last compilation step, you need to include all files your extension is using at runtime, such as external scripts, CSS files… as well as the CSXS folder with your manifest. If you are unsure, look in your project “bin-debug” folder created by Flash Builder, you need to obtain the same structure via the ANT script:
<copy todir="${BUILD}" file="${SRC}/main.css"/>
<copy todir="${BUILD}/scripts">
<fileset dir="${basedir}/src/scripts"/>
</copy>
<copy todir="${BUILD}/CSXS">
<fileset dir="${basedir}/.staged-extension/CSXS"/>
</copy>
Signing the extension
The Signing Toolkit contains the required documentation for this step, so I just jump over the whole certificate generation and required structure, and here’s how you can do it via ANT:
<java jar="${SIGNING_TOOLKIT_HOME}/ucf.jar" dir="${basedir}" failonerror="true" fork="true">
<arg line="-package" />
<arg line="-storetype PKCS12" />
<arg line="-keystore "${CERTIFICATE_PATH}"" />
<arg line="-storepass ${CERTIFICATE_PASSWORD}"/>
<arg line="${OUT}/CtrlPublishing_CI.zxp"/>
<arg line="-C ${BUILD} ." />
</java>
Now you may have some extra problems (I did), your extension installs nicely with the Extension Manager, appears in the Windows menu of the CS application, but the panel never seems to load the Flash UI… you have probably some errors in the list of SWF libraries that you included, verify them carefully, make sure you didn't include AIR libraries or the mentioned apedelta.swc library.
Creative Suite Theme
Now a last issue to solve, the proper theme is not used when you installed your home-compiled extension.
You also need to refer to the desired theme while compiling your Flex app.
The problem is: The Creative Suite SDK doesn't include the Creative Suite Theme, only the CS Extension Builder does. Why is that? I would like everything in the CS SDK...
Well, we can solve it ourselves again by digging inside the extension builder. Locate your installation folder (the one you pointed to when installing it in Flash Builder). In the “plugins” folder, find the JAR file named " com.adobe.cside.project_1.5.0.201103311826". Unzip it, and browse to "themes/Creative_suite_CS5". Copy the swc file to your project folder:
<compiler.theme dir="${basedir}/themes" append="true">
<include name="Creative_Suite_CS5.swc"/>
</compiler.theme>
Run your ANT script once again, and you should get a working extension.
Now you just have to install the CS SDK (modified with the missing libs) and the signing toolkit on the server, and make sure your script points to them correctly.
Et voilà, an extension ready to be consumed by your hungry Hudson/Jenkins/CruiseControl integration server!
Source Download
Download the source for the article: build.xml.zip
