Alchemy:Documentation:Getting Started
From Adobe Labs
This article will walk through the steps of getting the Alchemy tool-chain setup, show how to compile C / C++ code into a SWC, and then use that SWC within a simple ActionScript example.
Alchemy (formerly referred to as FLACC) is a project from Adobe that allows users to compile C/C++ code that is targeted to run on the open source ActionScript virtual machine (AVM2). The C/C++ code is compiled to AS3 as a SWF or SWC that runs on Flash Player 10 or AIR 1.5. Alchemy is primarily intended to be used with C/C++ libraries that have few OS dependencies. The generated content is within the security constraints of the AVM2, and cannot bypass Flash Player security protections.
| Table of contents |
Macintosh
This section will show how to setup and use Alchemy on Mac OS X, although the general steps are also applicable on both Windows and Linux.
Requirements
- Alchemy Toolkit Package for your operating system
- XCode 2.4+
- Flex 3.2 SDK
- Flex Builder or Flex SDK setup to target compilation for Flash Player 10
Steps
Step 1 Download the Flex 3.2 SDK and make sure that the $FLEX_HOME/bin directory is in your system path.
Step 2 To test this, open a terminal and run
adt -version
You should see output similar to:
adt version "1.5.0.7220"
Step 3 Download the Alchemy Package for your system from the pre-release site. For this example, we will assume that Mac OS X is being used.
Step 4 Unzip the package and copy the alchemy folder to you system. We will refer to this path as $ALCHEMY_HOME
Step 5 Open a terminal and change to the $ALCHEMY_HOME/ directory.
Step 6 Run the $ALCHEMY_HOME/config script
./config
Step 7 Open your bash setup script to edit. This can usually be found in the (~/.profile directory).
Step 8 Edit the the .profile script so that alchemy-setup is run when the script is run:
source /Users/mesh/alchemy/alchemy-setup
This should be added before your PATH is modified.
Step 9 Add $ALCHEMY_HOME/achacks to your path.
PATH=$PATH:$ALCHEMY_HOME/achacks
You .profile file should look similar to:
source ~/alchemy/alchemy-setup PATH=$PATH:~/bin:/usr/local/bin:~/bin/flex/bin:~/bin/astmp:$ALCHEMY_HOME/achacks export PATH
The file may contain other commands specific to your system.
Step 10 Save the file, and restart your terminal.
Step 11 Change to the $ALCHEMY_HOME/samples/stringecho directory
Step 12 Type the following commands in the terminal
alc-on; which gcc
It should print out the path that points to the gcc contained with the $ALCHEMY_HOME/achacks/ directory.
Step 13 Enter the following command to compile the c program into a SWC:
gcc stringecho.c -O3 -Wall -swc -o stringecho.swc
You should see output similar to:
c-24-5-187-95:stringecho mesh$ gcc stringecho.c -O3 -Wall -swc -o stringecho.swc WARNING: While resolving call to function 'main' arguments were dropped! 1580.achacks.swf, 370415 bytes written frame rate: 60 frame count: 1 69 : 4 72 : 370345 76 : 33 1 : 0 0 : 0 frame rate: 24 frame count: 1 69 : 4 77 : 506 64 : 31 63 : 16 65 : 4 9 : 3 41 : 26 82 : 471 1 : 0 0 : 0 adding: catalog.xml (deflated 75%) adding: library.swf (deflated 60%)
Step 14 Type ls -l You should see output similar to:
drwxr-xr-x@ 3 mesh staff 102 Oct 20 15:49 as3 -rw-r--r--@ 1 mesh staff 435 Oct 20 15:49 readme.txt -rw-r--r--@ 1 mesh staff 1221 Oct 20 15:49 stringecho.c -rwxr-xr-x 1 mesh staff 143860 Oct 21 10:04 stringecho.swc
Make sure stringecho.swc is present in the directory.
Step 15 The stringecho.swc SWC can now be used in a Flash Player 10 ActionScript or Flex project. Just link it in when compiling like your would link in any other SWC.
Step 16 Here is a simple example that uses the stringecho.swc:
package
{
import flash.display.Sprite;
import cmodule.stringecho.CLibInit;
public class EchoTest extends Sprite
{
public function EchoTest()
{
var loader:CLibInit = new CLibInit;
var lib:Object = loader.init();
trace(lib.echo("foo"));
}
}
}
Step 17
Use the following command to compile the ActionScript code using MXMLC:
mxmlc -library-path+=../stringecho.swc --target-player=10.0.0 EchoTest.as
Step 18 This will generate a Flash Player 10 SWC that traces "foo" when run in the debug player.
Troubleshooting
- Make sure that you are compiling with the Alchemy version of the gcc tools. You can confirm this by typing
which gcc
- Make sure to run the
alc-on
command prior to compiling a project.
Windows
This section will show how to setup and use Alchemy on Windows using Cygwin.
Requirements
- Alchemy Toolkit Package for your operating system
- Cygwin with the following packages installed
- Perl
- zip
- gcc / g++
- Java
- Flex 3.2 SDK
- Flex Builder or Flex SDK setup to target compilation for Flash Player 10
Steps
Step 1 Download and install Cygwin. Make sure to install the following packages:
- Perl
- zip
- gcc / g++
Step 2 Download and install Java.
Step 3 Make sure to restart the Cygwin terminal after installing Java.
Step 4 Download and install the Flex SDK, and add the $FLEX_HOME/bin directory to your Cygwin environment's path (within ~/.bashrc) (See below for an example).
Step 5 Download the Alchemy Package for your system from the pre-release site. For this example, we will assume that Windows is being used.
Step 6 Unzip the package and copy the alchemy folder to you system. We will refer to this path as $ALCHEMY_HOME
Step 7 Open a Cygwin terminal and change to the $ALCHEMY_HOME/ directory.
Step 8 Run the $ALCHEMY_HOME/config script
./config
Step 9 Open alchemy_setup for editing and add the path to the ADL executable (included in the Flex SDK):
export ADL=/cygdrive/c/flex/bin/adl.exe
Make sure to uncomment this line, and that it contains the path to ADL.exe on your system.
Step 10 Open your bash setup script to edit. This can usually be found in the ~/.bashrc file.
Step 11 Edit the the .bashrc script so that alchemy-setup is run when the script is run:
source /cygdrive/c/alchemy/alchemy-setup
This should be added before your PATH is modified.
Step 12 Add $ALCHEMY_HOME/achacks to your path.
PATH=$ALCHEMY_HOME/achacks:/cygdrive/c/flex/bin:$PATH
You .bashrc file should look similar to:
source /cygdrive/c/alchemy/alchemy-setup PATH=$ALCHEMY_HOME/achacks:/cygdrive/c/flex/bin:$PATH export PATH
The file may contain other commands specific to your system.
Step 13 Save the file, and restart your cygwin terminal.
Step 14 Change to the $ALCHEMY_HOME/bin directory, and run the following command:
ln -s llvm-stub llvm-stub.exe
Note that this step wont be necessary in future builds.
Step 15 Change to the $ALCHEMY_HOME/samples/stringecho directory
Step 16 Type the following command in the terminal
alc-on; which gcc
It should print out the path that points to the gcc contained with the $ALCHEMY_HOME/achacks/ directory.
Step 17 Enter the following command to compile the c program into a SWC:
gcc stringecho.c -O3 -Wall -swc -o stringecho.swc
You should see output similar to:
$ gcc stringecho.c -O3 -Wall -swc -o stringecho.swc WARNING: While resolving call to function 'main' arguments were dropped! 2544.achacks.swf, 363806 bytes written frame rate: 60 frame count: 1 69 : 4 72 : 363736 76 : 33 1 : 0 0 : 0 frame rate: 24 frame count: 1 69 : 4 77 : 506 64 : 31 63 : 16 65 : 4 9 : 3 41 : 26 82 : 471 1 : 0 0 : 0 adding: catalog.xml (deflated 75%) adding: library.swf (deflated 61%)
Step 18 Type ls -l You should see output similar to:
labuser@LABVM-VU32EN /cygdrive/c/alchemy/samples/stringecho $ ls -l total 1181 -rw-r--r-- 1 labuser None 344376 Oct 22 12:28 1664.achacks.exe.bc -rw-r--r-- 1 labuser None 956 Oct 22 12:28 1664.achacks.o -rw-r--r-- 1 labuser None 344376 Oct 22 14:38 2232.achacks.exe.bc -rw-r--r-- 1 labuser None 956 Oct 22 14:38 2232.achacks.o -rw-r--r-- 1 labuser None 344376 Oct 22 11:15 3688.achacks.exe.bc -rw-r--r-- 1 labuser None 956 Oct 22 11:15 3688.achacks.o drwx------+ 2 Administrators None 0 Oct 22 11:59 as3 -r-x------+ 1 Administrators None 435 Oct 20 20:41 readme.txt -r-x------+ 1 Administrators None 1221 Oct 20 20:41 stringecho.c -rwxr-xr-x 1 labuser None 144099 Oct 22 14:38 stringecho.swc
Make sure stringecho.swc is present in the directory.
Step 19 The stringecho.swc SWC can now be used in a Flash Player 10 ActionScript or Flex project. Just link it in when compiling like your would link in any other SWC.
Step 20 Change to the $ALCHEMY_HOME/samples/stringecho/as3 directory.
Step 21 This directory contains a simple ActionScript file that contains the following code which uses the SWC we just created:
package
{
import flash.display.Sprite;
import cmodule.stringecho.CLibInit;
public class EchoTest extends Sprite
{
public function EchoTest()
{
var loader:CLibInit = new CLibInit;
var lib:Object = loader.init();
trace(lib.echo("foo"));
}
}
}
Step 22 Use the following command to compile the ActionScript code using MXMLC:
mxmlc.exe -library-path+=../stringecho.swc --target-player=10.0.0 EchoTest.as
This will generate a Flash Player 10 SWC that traces "foo" when run in the debug player.
Troubleshooting
- Make sure that you are compiling with the Alchemy version of the gcc tools. You can confirm this by typing:
which gcc
- Make sure to run the
alc-on
command prior to compiling a project.
