Alchemy:Documentation:Developing with Alchemy:Tools
From Adobe Labs
| Table of contents |
Overview
The Alchemy SDK contains a number of command line tools. Some are used to build Flash compatible output from your C/C++ files. Some are used for debugging. And some are just conveniences. I will described the important ones below.
Aliases
There are three aliases added to your environment when Alchemy is configured:
alc-home: This takes you to your Alchemy install directory
alc-on/alc-off: These will add $ALCHEMY_HOME/achacks to the front of you path. See $ALCHEMY_HOME/achacks for why you may not want this on all the time.
Tools in $ALCHEMY_HOME/achacks
This is to replace the existing gcc build related tools with their Alchemy equivalents. You will not want this on all the time, since it will make your system respond in many ways as if it were vanilla BSD. This is probably not something you want when installing native software. With the exception of gcc/g++ you will not generally need to call these tools directly.
gcc: This is the most important in this group of tools.
It serves the following functions:
- It remaps include and library paths under /usr/local to $ALCHEMY_HOME/usr/local
- It calls llvm-gcc and llvm-g++ to produce LLVM bytecode
- It calls the llvm tools with the correct parameters to produce ActionScript
- It calls the Alchemy ActionScript compiler to produce ABC files
- It packages the ABC as either SWF or SWC depending on whether "-swc" was passed
It has one option of significance: -swc This tells the tool to package the output as a SWC. The default is to package it as an "executable" which is really a SWF with a pre-pended shabang for launching swfbridge.
All other options will be passed through to llvm-gcc.
It has a few environment variables it looks for which control the output:
- LOG - this will turn on logging at runtime. Look in /tmp/adl.trace if you are using SWFBridge, the trace console if you are using FlexBuilder
- LOGLEVEL - this controls the level of logging. Higher numbers means more stuff is logged. The range is currently 0-5.
- ACHACKS_TMPS - this leaves intermediate files around after compiling. Specifically the generated ActionScript files (which can be quite large). Files have "achack" in the name.
g++: This just calls gcc with the same set of arguments, but remembering the original name that was used to allow for libraries to be linked properly.
uname: This will report as if the operating system is FreeBSD 6.2.
pkg.pl, tmpl.pl, swctmpl.swf: These are helper routines for building SWFs and SWCs;
all other scripts: These scripts will generally perform path munging to map paths under /usr to something under $ALCHEMY_HOME. They will usually end of calling an llvm equivalent of their native functionality.
Tools in $ALCHEMY_HOME/bin
These are the tools that will always be in your path once Alchemy is configured. They should not interfere with any other development you are doing.
alc-util: This tool will show the current environment variables that directly impact Alchemy. If a variable is shown but has no value - that usually means it is not defined in your environment.
swfbridge: This tool is called when running an Alchemy-generated executable. It is triggered by the "shabang" placed at the head of each Alchemy executable. Its main purpose is to generate a temporary AIR application package to allow the SWF to be launched using adl (the AIR Debug Launcher). It currently has a secondary purpose which is to allow certain API calls to be routed over a local socket connection. That function will probably not be present in later releases.
gluegen: This is a build tool for exposing C/C++ libraries to ActionScript with minimal extra work. Its input files have an extension of .gg. You can look at the AS3 Crypto Wrapper example for a good example of usage.
zpipe: This tool takes input from STDIN compress or decompresses using the ZLib compress algorithm and streams it to STDOUT. It has two options: zpipe -h -- shows the usage zpipe -d -- decompress input from STDIN to STDOUT
Example: zpipe < uncompressed > compressed
zpipe.pl: This does exactly the same thing as zpipe, but it uses Perl and Compress::Raw::Zlib to do it. Usage is exactly the same.
ExplSWF.pl: This will "inflate" a SWF passed in. The tags within the SWF are turned into files in the current directory.
Example: ExplSWF.pl src.swf
ImplSWF.pl: This will "deflate" a SWF passed in. The tag files within the current directory are turned into a SWF.
Example: ImplSWF.pl dst.swf
GetABC2.pl: This will extract the ABC data from a SWF.
Example: GetABC2.pl src.swf dst.abc
PutABC2.pl: This will take a source SWF and create a new target SWF replacing the ABC content with the passed in content.
Example: PutABC2.pl src.swf dst.swf newabc.abc
PutBIN.pl: This will take a source SWF and create a new target SWF with an additional binary resource.
Example: PutBIN.pl src.swf dst.swf data.bin symname
ShrSWF.pl: This will take a source SWF and compress it.
Example: ShrSWF.pl src.swf dst.swf
V10.pl: This will change the version tag of a SWF to version 10.
Example: V10.pl src.swf dst.swf
GlueGen Documentation
GlueGen is a command line tool ($ALCHEMY_HOME/bin/gluegen) that takes a glue description (.gg) file and and produces complementary .c and .as files defining an Alchemy interface between a C/C++ library and ActionScript. The goal of GlueGen is to allow you to take a C library header for an existing library and with some minimal work expose the functions to ActionScript. Compiling the C output file will produce a SWC. This SWC along with the .as file created with the .c file can be imported into a Flex or Flash project to allow you to use the C library functionality within your project.
The GlueGen format is a mix of ActionScript and C/C++ semantics. There are a couple of samples available, one in the as3_crypto_wrapper library (available as a download) and another in the samples/libpng folder.
GlueGen options
Running gluegen and passing -help you will see the following options are available.
Usage: gluegen [options] [gluedesc] Options: -help -functions-only -oc cfile (def: glue.c) -oas asfile (def: glue.as) -cpackage cpackagename (def: cmodule.test) -package packagename (def: cassava.test) -class classname (def: Test) -class-protection classprotection (def: public) -lib-var-name varname (def: _lib) -lib-var-protection varprotection (def: protected)
Generating output files with GlueGen
This example call to gluegen will generate an ActionScript file and a C file from the glue description file fooLib.gg.
gluegen fooLib.gg -oc fooLib.c -oas fooLib.as -cpackage cmodule.fooLib -package alchemy.foo -class fooLib
The ActionScript file fooLib.as will contain a package called alchemy.foo containing a class called fooLib. When this class is instantiated, it will instantiate cmodule.fooLib.CLibInit and call init() on it to get back the library object. The methods exposed will be the methods as defined in the glue description.
The C file fooLib.c will contain some prefix code, the implementation functions plus their accompanying code blocks (if any) and the thunking functions doing argument marshaling to call into your 'implementation functions. The C file will be compiled into a SWC fooLib.swc which will contain the package cmodule.fooLib with a single class CLibInit containing all of the exposed methods.
Exposing a C method to ActionScript
Exposing a C method directly to ActionScript is possible with nothing other than a prototype if:
- The name can be the same on both sides
- The parameter and return types can be marshaled by GlueGen directly
- int, uint, void*, char*, double
- No additional C calls need to be made prior to calling the function from ActionScript
public function foo(arg1:int):void;
This exposes the C function foo as an ActionScript method foo taking an int and returning nothing. You do not need to add a code block after as GlueGen will generate the marshaling code for you.
Adding a C/C++ code block for the file
Straight C/C++ code should be placed in a code block at the top of the file, delimited with { } braces. This code will only show up in the C file. Typical uses are: #includes, global variables, helper functions.
Adding a C/C++ code block for a function
You can add a code block following the prototype if you need to do special argument marshaling or if you want to make additional C calls.
public function foo(arg1:int):void
{
theRealFoo(doSomethingFirst(arg1));
}
The code block will only appear in the C output file.
Overriding the name exposed to ActionScript
You can override the name exposed to ActionScript by adding a forward slash after the C function name, followed by the ActionScript method name.
public function foo/bar(param:int):int;
This exposes C function foo as ActionScript method bar.
Overriding the C function types
You can override the return type for the C function using parentheses preceding the ActionScript return type surrounding the C function return type.
public function foo(param:int):(unsigned)int;
This exposes C function foo returning unsigned as ActionScript method foo returning int.
You can override the argument type for the C function using parentheses preceding the ActionScript argument type surrounding the C function argument type.
public function baz(ptr:(void*)uint):void;
This exposes C function baz taking a void* as ActionScript method baz taking a uint.
