Jul
21

Setting Up Adobe Alchemy for Flash Jon Keon

Actionscript, Flash

If you aren’t aware, Alchemy is a tool made by Adobe that allows you to compile C or C++ code into AS3 Byte Code as a SWC or SWF file that you can then include in your traditional AS3 projects.

While this is pretty cool, Adobe dropped the ball in terms of documenting just how to set it all up!

After playing around with it for a few hours I was finally able to compile the samples and get it running but it was painful.

For anyone else interested in stating to play with Alchemy (and so I don’t forget), here are some setup and configuration instructions that are a little bit more in depth and useful.

*Note: These setup instructions are for Windows machines.

Prerequisites Setup:

Create a new folder on your C drive and call it alchemy.

The first thing we need is to download the Alchemy Toolkit.

  • You can download it from this page here.
  • Select the checkbox to say that you have read the license agreement and then download the Alchemy Toolkit for Cygwin on Windows
  • After the download is complete, extract the contents of the zip file to your alchemy directory on your C drive.
  • You should have one folder called alchemy-cygwin-v0.5a inside your base alchemy directory.

Next we need to download and install Cygwin which is essentially a Linux like environment for Windows.

  • You can download it from this page here.
  • Click on the Install or Update Now! button at the bottom of the screen.
  • Save the setup.exe file to your desktop. You can delete it later.
  • Once downloaded, double click to run the setup.
  • Click on Next.
  • Ensure that the radio button Install from Internet is selected and click on Next.
  • In the root directory, choose Browse…
  • Select the alchemy directory you created earlier and click OK
  • Add in the textbox \cygwin. The full path should now be C:\alchemy\cygwin.
  • Ensure that All Users is selected and click Next.
  • Leave the Local Package Directory as is and click Next.
  • Leave the internet options as Direct Connection unless you know otherwise and click Next.
  • Choose any mirror from the available download sites and click Next.
  • An Alert may popup alerting you that it’s the first time you’ve installed Cygwin. Just click Ok.
  • Now the fun part. We need to install Perl, gcc, and zip.
  • You’re going to see a list of packages that you can install Cygwin with. By Default only some of the packages will be installed and usually these means not very many of them. You can see in the screenshot below that each package has a Default written beside it.
  • First let’s install Perl. Click on the text Default in the menu beside the entry Perl (not the + button) and you’ll notice that Default will change to Install.
  • Then to install zip, click on the text Default in the menu beside the entry Archive.
  • To install gcc, you’ll need to expand the entry Devel.
  • Then scroll down to gcc-g++ and click on the word Skip on the right. This will install version 3.4.4-999 and also flip some other entries to install as well.
  • Next scroll down to gdb and again click on the word Skip on the right.
  • Finally scroll down to the make entry and just make sure that it doesn’t say Skip on the right.
  • Now click Next and be prepared to wait around for a while as it downloads and installs all the required files to get cygwin up and running.
  • Once that’s installed, just click on Finish.

The next prerequisite is Java. Odds are you probably already have this installed but if you don’t…

  • You can download it here.
  • You will need to install the JRE in order for the Flex Compiler to work properly.
  • Click on Download JRE.
  • On the next page you will select your platform from the drop down, and check the checkbox saying you agree to terms of service.
  • You will then be given a link to an exe file. Download that exe.
  • Once downloaded, run that exe to launch the Java installer.
  • Click on Install.
  • Java will then install on your machine. Once installed, click on Close.

Finally, the last prerequisite is the Flex SDK. The Alchemy documentation requires Flex 3.2 but at the time of writing this, Flex 4.0 has been released and is what I use. If you use FDT or Flash Builder you probably already have the SDK installed on your computer and can technically point Alchemy to that directory. For simplicity, we’ll assume we don’t know where that directory is or we’re too lazy to find it :)

  • You can download the Flex 4.0 SDK from here.
  • Select the latest Milestone Release. (Flex 4.1 Update)
  • Select the check box saying you agree to the terms of service.
  • Download the zip file by clicking on the link that appears at the bottom of the screen.
  • Once downloaded, extract the contents of the zip file to your alchemy directory in a new folder called flex4.

Just to double check, if you navigate to your C:\alchemy directory you should have 3 folders:

  • alchemy-cygwin-v0.5a
  • cygwin
  • flex4

Of course you can have these folders anywhere so long as you know the path to them, but it’s just easier for now to have them in one spot. Congratulations, you’ve finished the prereqs! Now you can actually setup Alchemy.

Actually Setting Up Alchemy:

Now that all the prereqs are complete we can finally begin to set up alchemy and get it working.

This largely involves setting up environment variables and paths in your cygwin profile which is peanuts for someone well versed in Linux and Bash but if you’ve never touched it, the Adobe documentation is a bit confusing.

  • The first thing to do is to start cygwin. Open the alchemy/cygwin folder and double click on Cygwin.bat
  • cygwin will open a command line window and install your user profile. You can see that in alchemy/cygwin/home there is now a new folder that is your user name on your computer.
  • Inside this folder are three files. A Bash Profile, BashRC file, and InputRC file. The one we’ll be concerned with is the BashRC file.
  • Close the cygwin command line window.
  • Open and edit your .bashrc file in a text editor like Notepad or Notepad++.
  • Scroll down to the line # Environment Variables
  • At the end of this block of text right before # Shell Options, enter the following lines.
    • export FLEX_HOME=/cygdrive/c/alchemy/flex4/bin
    • export ALCHEMY_HOME=/cygdrive/c/alchemy/alchemy-cygwin-v0.5a
  • Now restart cygwin by double clicking on the Cygwin.bat again.
  • Type cd $ALCHEMY_HOME
  • (For whatever reason, sometimes this doesn’t work for me. I have to try a few times before i’ll get yellow text with the path.)
  • Now type ./config
  • You’ll see some text appear warning you about adl.exe not being available. That’s ok.
  • Close your cygwin window again.
  • In your c:\alchemy\alchemy-cygwin-v0.5a\ directory there is a file called alchemy-setup. Open that file in notepad.
  • Locate the line that says # export ADL=/path/to/your/adl
  • Directly underneath this line, write:
    • export ADL=/cygdrive/c/alchemy/flex4/bin/adl.exe
  • Close your alchemy-setup file.
  • Open your .bashrc file again.
  • Under the line export ALCHEMY_HOME add the following line
    • source /cygdrive/c/alchemy/alchemy-cygwin-v0.5a/alchemy-setup
  • Under that line add the following lines
    • PATH=$ALCHEMY_HOME/achacks:$FLEX_HOME:$PATH
    • export PATH
  • Save the .bashrc file and close it.
  • Launch Cygwin.bat again.
  • Type printenv PATH and you should get a bunch of filepaths separated by colons (:). Ensure that you see the Alchemy Path with achacks and the Flex Path as well.
  • Type cd $ALCHEMY_HOME/bin
  • Type ln -s llvm-stub llvm-stub.exe
  • You’ll probably get a message saying the File exists.
  • To ensure everything is setup correctly, just type which gcc. You should get back a path pointing to alchemy-cygwin-v0.5a/achacks/gcc
  • Phew! Congratulations, Alchemy is now setup and ready to go!

Testing Alchemy:

Now that Alchemy is setup, we should probably test it just to make sure it’s good to go, along with familiarizing ourselves with the steps to compiling C code to use in Flash.

  • First open your command line by running Cygwin.bat
  • Type cd $ALCHEMY_HOME/samples/stringecho
    • In your future projects, you can navigate to where ever your C Code is being kept.
  • Next type alc-on;
    • This is very important, you must type this every time before you compile your C Code or it won’t work.
  • Now we’re going to compile the C Code.
  • Type gcc stringecho.c -O3 -Wall -swc -o stringecho.swc
    • gcc means use the gcc compiler for C  code. To compile C++ code, use g++
    • stringecho.c is the main C file we want to compile.
    • -O3 means to switch on all safe optimizing transformations, regardless of their impact in terms of size and compilation time. (source) NOTE: This is O-THREE, not ZERO-THREE.
    • -Wall is a warning level which i believe will show all warnings in your C program that GCC discovers. The addition of -swc afterwards means that it will suppress all warnings to do with outputing the file as a swc. (I’m not 100% sure on this though)
    • -o means to place the output in a file, in this case stringecho.swc. NOTE: This is the letter O.
  • GCC will then do it’s thing and compile your C code into a swc.
  • You can ensure it was created by navigating to your alchemy directory and then looking in samples/stringecho/. You should see a file called stringecho.swc.
  • Now the Adobe Documentation will show you how to compile and create a swf file via cygwin but that’s probably not most people’s workflow. I use FDT for all my Flash Development because quite simply, it’s the best development environment out there (end rant)
  • In order to test that it works in FDT, open FDT (I’m using FDT 4, milestone 3) and create a New Flash Project
  • Give it a name, and set up your project as you would normally.
  • Next you’ll need to link that swc you created with GCC. You’ll have to copy it over from the samples/stringecho/ directory
  • Next select your project and right-click to bring up the menu and then click on Properties.
  • Select FDT Build Path
  • Click on the Library tab
  • Click on Add SWCs… button
  • Navigate to where you placed the stringecho.swc, select it and then click OK.
  • Then click OK.
  • Now copy over the EchoTest.as from samples/stringecho/as3 to your Classes directory in your FDT project.
  • Right click on your project to bring up the menu and select Refresh.
  • You will now see the EchoTest class in your Flash Explorer.
  • You can now create a debug or run configuration for EchoTest and when you run it, an empty swf will open and you should see the word “foo” traced out in your console window.
  • You’ve successfully created an AS3 application that talks to an Alchemy generated swc and communicated between the two.
  • If you’re not too exhausted, you can create something cool!

This entry was posted on Wednesday, July 21st, 2010 at 12:44 pm and is filed under Actionscript, Flash. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.