How to use this thing (README.txt)
Brought to you by:
evildave
Menu
▾
▴
INTRODUCTION
This is a command line build environment with Adobe Flex SDK ActionScript 3
sources fed through the C preprocessor before they go to mxmlc.
It is minimalistic and very suitable for use with easily scripted IDEs, or
just as a straight command line development environment.
1. All of the C preprocessor tools become a part of your ActionScript 3 build
environment. Assert, conditional compiles, hard constants, macros and code
generation templates/techniques galore.
2. Error call-outs refer back to the original line of source code, not the
preprocessed code. The preprocessed output is processed some more to make it
match up to the original code, and to remove those pesky '#line' statements
that MXMLC doesn't understand, as well as the tons of inserted white space that
some preprocessors dump in.
3. In the 'fdb' debugger, you are looking at the preprocessor output. This is
both bad and good. Sometimes it's very useful to see what a macro became.
Sometimes that can be a little confusing, too.
4. The preprocessor stage is very fast, and the make actually shortcuts around
the (occasionally very slow) mxmlc startup, so once you have a working build,
you can keep running/debugging without that long pause, at least until you
change something.
5. Dependencies for the source and header files are generated and maintained
automatically. If you touch any makefile script or header, everything gets
rebuilt. If you touch a particular file, only that file gets rebuilt. Add
'-compiler.incremental=true' to the mxmlc command line parameters if the
project is big enough to make a difference there.
6. The files you will be coding in will be '.AS3' files. They become '.AS'
files AFTER they have been preprocessed. If I were working with Actionscript 2
I would call them .AS2 files. They're literally completely different languages
and there's no point keeping a single file extension for completely different
code... and it needed to be 'different' so make could see they were different.
7. You will want to tell your editor about the extra .AS3 extension and
associate it with the correct language parser.
8. Debug and release mode builds and dependencies go into seperate bin/bind
folders.
9. Certain underlying preprocessor assumptions change. For instance, where
you might have used string concatenation like this: "One " "string.", your
macros will need to look like this: "One " + "string."
10. If you use the same libraries and general projects over and over again,
then the Makefile can be reused readily without modification.
PREREQUISITES
There are some prerequisites for this tool.
First off, you'll need that Free Flex 2 SDK from Adobe. Unzip it somewhere
permanent and add its 'bin' folder to your PATH.
http://www.adobe.com/products/flex/sdk/
While you're there with that account you had to make all logged in, you may
as well get the Flex Documentation. I recommend 'Documentation ZIP file', near
the bottom. It has most everything you need on a daily basis. You can short-
cut it to your desktop where you can get at it easily.
http://www.adobe.com/support/documentation/en/flex/
The installer.zip file (found one level up in the SVN repository) will install
every tool this needs (and then some) for a Windows/MinGW version of the build
except for the Adobe Flex SDK, which you need to log in to Adobe to download.
You'll need either Microsoft NMake and the tools that go with that, or a
version of gcc. If you have GNU gcc, you probably have GNU make and cpp
already, but not necessarily, especially if you're running under Windows.
The Makefile and tools will build with other preprocessors (see the comments in
the makefile), but you may as well play along with one set of tools, and the
gnu toolset is either already installed, or easy to find for pretty much EVERY
OS, and also free.
If you already have a compiler (such as MSVC), you probably also have a
make tool, and you might want to 'port' the GNU Makefile script to the
development tools you already are comfortable using.
For Windows, I recommend MinGW, and using the (MinGW-5.1.3.exe) installer.
This will get you a usable GNU compiler. Whether you add in other libs and
tools on top of it is up to you.
http://sourceforge.net/projects/mingw/
Finally, the last two tools you'll need are GNU sed and GNU indent. For most
POSIX-based operating systems, you'll already have it, or it's readily
available.
For Windows, you'll want to venture into the GnuWin32 project and have a look
for sed and indent, and don't forget to get their .dll dependencies.
There's no simple installer, so just grab the files and unzip them into your
MinGW 'bin' folder (or anywhere in your PATH), and they'll all get along fine.
You might also want 'Zip', as it's used in an optional Makefile target to wrap
up a copy of the project, and skips over any hidden .cvs/.svn folders when
doing so.
http://gnuwin32.sourceforge.net/packages.html
What's here...
MAKEFILE
This is the main GNU make script. It has some house-keeping targets and
settings, and invokes cpp2mxmlc.mak to do the preprocessed mxmlc builds.
Of special note are the variables...
TARGET - The final SWF output file name
ASMAIN - The name of the AS file
GAMEDIR - Where to find the AS3 project trees
LIBDIRS - One or more subdirectories under GAMEDIR for 'import'.
RESDIR - A directory tree that gets copied into bin/bind
make debug Build a debug version
make release Build a release version
make all Cleans, then builds debug and release
make run Run the game
make runhtml Run the game in web page
make rundebug Run the game in the debugger ***
make clean Wipes out intermediate files
make cleaner Invokes clean in any subdirectory nmake.mak
make zip Make a nice zip file (needs zip)
*** See the 'BUGS' section about what disables fdb...
CPP2MXMLC.MAK
This is called by the GNU Makefile, and does most of the dirty work. You
probably won't need to change any of it, unless you want to 'tinker'. You
may need to tinker outside of Windows, as a few things are 'stuck' that way.
NMAKE.MAK
This is the Microsoft NMAKE makefile. It's part of every version of Visual
Studio, and has been tested starting with MSVC 6 and .NET. If you invoke it
from the Game.vcproj, your errors will show up in the IDE just like Visual
C++ errors.
nmake -f nmake.mak clean Wipes out intermediate files
nmake -f nmake.mak cleaner Invokes clean in any subdirectory nmake.mak
nmake -f nmake.mak nuke Clean AND msvc files (nukes your run settings)
nmake -f nmake.mak zip Make a nice zip file (needs zip)
nmake -f nmake.mak cfg=debug Build a debug version
nmake -f nmake.mak cfg=release Build a release version
nmake -f nmake.mak cfg=[debug|release] run Run the game
nmake -f nmake.mak cfg=[debug|release] runhtml Run the game in web page
nmake -f nmake.mak cfg=[debug|release] rundebug Run the game in the debugger
*** See the 'BUGS' section about what disables fdb...
GAME.VCPROJ
This is a Microsoft Visual Studio.NET project file made with the first version
of .NET, so any current .NET should be able to import it. It invokes build,
rebuild and clean. The settings for running and invoking the debugger from the
IDE are described below in the 'Visual C/C++ Setup' section.
FILTERS/CPPFILTER.C
Built as a target in the Makefile, it is written in C. You can
remove the Makefile target for this if that's more convenient. There's a
make.bat there with examples of command lines that will build it with other
compilers. Whatever it takes to make the executable (not much), and you're
set. This runs through the preprocessor output and translates the '#line' spew
into blank space matching up with the original source code. The process was a
little more 'stateful' than I was willing to put up with in sed, and if anybody
can make a sed script do that, they can be a hero. There's nothing magic
there, and no dependencies outside of the standard C runtime library, and it
could as easily have been written in any language with good command line
streaming support. A BASH script and a few other tools could do it, or maybe
even a BAT file and similar, tools, but I'm not going to spend the time doing
that.
GNUBATCHES
These are just shorthand to invoke the various GNU make targets. Make them
into scripts, delete them, whatever.
MSVCBATCHES
These are just shorthand to invoke the various Microsoft NMAKE targets.
RES/
Whatever tree of folders/files you put here will end up in the bin/bind
directories. Add XML, HTML, whatever assets the app needs.
INCLUDE/
Handy preprocessor macros and definitions for the application.
SRC/
This is where the .AS3 files go, and there are a couple of sample ones in here.
If you understand how MXMLC and the 'import' keyword end up searching paths by
default, that's basically the tree that goes here. If you add different
'package' folders, they'll need to appear in the Makefile LIBDIRS entry.
AS/ASD/BIN/BIND
These are intermediate and output folders for release and DEBUG mode builds.
If you have 'special' authoring and time consuming diagnostic code to stuff in
the application that shouldn't go to the public, make it conditional on DEBUG.
These folders are destroyed when the 'clean' target is evaluated.
SETTING UP With VIM
The vim editor is nice, in that it's everywhere, but most people loathe it.
I use it all the time for minor edits and quick hacks when I'm too lazy to open
an IDE and make a project.
* Get the actionscript.vim.
* Put it in the 'syntax' folder.
* Edit 'filetype.vim'
* Add...
" Actionscript
au BufNewFile,BufRead *.as,*.as2,*.as3 setf actionscript
http://www.vim.org/scripts/script.php?script_id=1061
SETTING UP With jEdit
jEdit is yet another IDE/editor that I sort of like for dealing with command
line builds. It has a nice little command prompt plugin and error parser/list
plugin that makes setting it up simple, and you can just type the commands in
if you haven't recorded a 'Macro' and assigned a hot key to every possible
thing in the universe that could be done with your code.
http://www.jedit.org/
Plugins you'll need: Console, ErrorList
Plugins you'll want: BufferTabs, Project Viewer
Things you'll need to do:
1. Add an 'mxmlc' error pattern to the Console plugin in
Plugins->Plugin Options->Console->Error Patterns
Click the '+' at the bottom of the Error patterns list.
* Name: mxmlc
* Error Regexp: (.*)[(](\d+)[)]: col: (\d+) Error: (.*)$
* Warning Regexp: (.*)[(](\d+)[)]: col: (\d+) Warning: (.*)
* Filename: $1
* Line number: $2
* Error message: $4
2. Go into Utilities->Global Options->Editing
* Set up your tab and editing preferences
* Set up 'actionscript' settings to recognize '.as3' (File name glob: *.{as,as2,as3})
3. You'll probably also want to go to Utilities->Global Options->Shortcuts and
add these keyboard shortcuts, if you're a Windows user.
* Close: Ctrl-F4
* Go to Next Buffer: Ctrl-Tab
* Go to Previous Buffer: Ctrl-Shift-Tab
When you build in the 'Command' window, the errors will pop up in the Errors
list, and the file will be brought up and the error line will be highlighted
correctly. It takes a little groping around to get all the windows up and
parked on the IDE the way you'll like. Expect to spend a whole day on it.
VISUAL STUDIO.NET SETUP
Open the Game.vcproj, right click on the 'Game' project and pick 'Properties'.
When prompted to (the first time you build), save a .sln file.
To DEBUG (Debug configuration)
Command: cmd.exe
Command Arguments: /c fdb.exe $(TargetPath)
Working Directory: bind
To EXECUTE (Release configuration)
Command: SAFlashPlayer.exe
Command Arguments: $(TargetPath)
Working Directory: bin
SAFlashPlayer.exe is the player in the Flex SDK player folder.
You could also fit "cmd.exe" and "/c start bin\test.html", if you wanted to
run under the web browser.
There aren't any instructions for Visual C/C++ before .NET, because the IDE
just doesn't work very well with an external make with a non-windows target.
You can get it to build, but you can't get it to run.
BUGS
The MinGW GNU cpp (I don't know about other GCC revisions) that I use will
double-space the comments if the input file is DOS encoded (\r\n for newlines).
This naturally buggers the line count, and errors mismatch the original source.
It's a known bug in MinGW's CPP. Making the source files 'unix encoded'
(\n newlines) makes the problem go away. This is a common setting in
programmer's editors, and the default for vim.
To successfully debug with fdb, you'll have to go into the FlexSDK/player
folder and run the 'SAFlashPlayer.exe' once. That will register it as the
default player for fdb to find. It will also make all of your flash playbacks
run a little slower.
Invoking Flash 8 player (i.e. by running/debugging AS2 code under Flash 8) or
the release-mode Flash 9 player will break the associations that fdb uses.
This can be corrected by running the 'debug' SAFlashPlayer.exe again.
You can get a 'release' mode SAFlashPlayer.exe by downloading and installing
the Flex Builder demo, and grabbing the release one out its player folder. It
runs significantly faster than the debug, and you will want to switch between
debug and release players to test/profile the game.