Launch Configuration Tutorial

From FDT Documentation

Revision as of 00:37, 5 October 2010 by Aklement (Talk | contribs)
Jump to: navigation, search
001 0006x.png

An essential aspect of FDT is the Launch Configurations. If you don't understand how FDT builds your projects, you may find yourself not understanding why certain things are and are not happening. Also, not having a clear understanding of Launch Configurations will mean that you will be missing out on incredible features that other IDEs can't even touch.


Download arrow.png Visit the Downloads page to download the source code used in this tutorial!


Contents

Getting Started

Let's begin by downloading the project from the Basic AS3 Tutorial and then import it. If you're not sure how to import projects see the Sharing and Archiving Projects tutorial.

While you don't need to import the project to follow along, it will jump start things for us.

Why Launch Configurations

Customizable Launch Configurations gives developers a great deal of power and flexibility. While it would be much easier for beginners to have FDT force a particular file structure and naming conventions, as they become more and more familiar with FDT ( or any IDE ) they are eventually going to want to have things work their way. Here are some important concepts to understand when working with Launch Configurations:

  • Developers can set ANY class to act the Main or Document class of a project. As long as the Class exists within any source folder, it can be set as the Class to build your application (if it's a class that doesn't inherit from Sprite, FDT will throw a compile error).
  • You can easily change the name of the output .SWF to anything you want without having to alter any compiler arguments yourself.
  • A project does not itself contain launch or compile settings; instead, a project has one or more launch configurations (saved as files in your .settings folder) which contain the settings FDT will use to compile your .SWFs.

That last point is probably the most different when coming from other IDEs. The best way to explain this is to demonstrate it.

Getting Started

After importing the project created in the Basic AS3 Tutorial ( or creating your own ), expand the launch folder located within the .settings folder [1]. Here you can see the Main.launch file that contains launch settings for this project. Now, delete that file ( don't worry we'll make plenty more ) [2]. Make sure no file is open in the Editor ( if the Main.as class is open in the Editor close it ) then click on the Run button within the menu bar Run button.gif.

What should happen next is FDT will show an Unable To Launch dialogue box [3].

What's going on is, neither FDT nor our project themselves know how to compile a .SWF or .SWC. They rely on a Launch Configuration to tell them what settings to use in order to compile anything. FDT or a particular project are just like a plane and all your code are the passengers. In this scenario, think of the Launch Configurations as the pilot who know where to fly and how to get there. Just like a plane can have multiple pilots, FDT can have multiple launch configurations.

Creating Configurations

In both the Basic AS3 Tutorial and the Flex / Air Tutorial, it was demonstrated how FDT can create a Launch Configuration automatically by running the from the Flash Explorer [4] or by running from the Editor [5]. Instead we'll create a configuration completely from scratch. Begin by choosing Run Configurations... [6]. What will appear is FDT's Launch Configurations window. Select FDT SWF Application [7] and click on the New launch configuration icon at the top [8].

For this example, I didn't have the project selected in the Flash Explorer and FDT didn't automatically fill in the Project field and gave the configuration a generic name of New_configuration [9].

Fill in a name for the configuration, I'll name this one launch_1, and click the Browse button to choose a project [10]. FDT will ask you to choose a project for this configuration, we only have one project open so only one appears, and click OK [11]. FDT will now warn you that You must choose a Main Class! - choose one by clicking on the Browse... button [12]. Just like with choosing a Project before, chose your Main class here - only one file appears because our project only has one Class in it [13]. Now FDT tells us You must choose a swf output file! [14]. If you were to click Browse... this time, FDT will ask you to choose an already existing file. Let's not do this and instead create a new one. Fill in bin/launch_1.swf in the Output field. bin is the name and path of the folder I want to use and launch_1.swf is the name I want to give the .SWF [15].

Finally, press the Run button to compile our .SWF [16].

Working With Launchers

After hitting Run, FDT will compile your .SWF. What you'll notice is, you can see the compilation output in the Console View and see the launch_1.swf in the bin folder [17]. What you also probably notice is:

  • FDT didn't show the .SWF.
  • FDT didn't save a launch configuration in the .settings/launch folder.

While this may seem like an error or a hassle to deal with, this is actually a gem of a situation. We need to tell FDT what to do, if anything, after compiling our .SWF. As we'll soon see, we can start to do some really cool stuff. For now, lets get to viewing our .SWF.

Get back to the Run Configurations window and click on the Start tab [18]. Check the box next to Open URI after compilation and click Browse [19] to choose which .swf to launch after compilation [20]. Next choose what you want FDT to use to view the .swf, lets use the External SWF Viewer, and make sure that the viewer's width and height match your .SWF [21]. When ready, click Run to launch your .swf [22].

Saving Launch Configurations

One last thing we need to cover before getting into more advanced topics with launchers, is to learn about saving our configurations. Saving configurations is important when we want to share or archive our projects to use later. If we were to delete our project right now, we wouldn't have our launch configuration to use at a later time or if we hand off the project to someone else.

Saving configurations is straightforward and simple. Begin by once again opening the Run Configurations window and then choosing the Common tab [23]. Check the Shared file: radio button and then select Browse... [24]. Choose the launch folder ( you can choose any folder you like ) [25], and run the configuration once again [26]. After the configuration runs, your .swf will render and FDT will have created a launch configuration within the launch folder.

Changing Compiler Options

There's no doubt that at some point you're going to want to adjust some compiler settings. Some things you may want to change include:

  • Background color
  • Frame rate
  • Size

We'll do this via the Compiler Arguments tab [27]. Then select the Use launcher specific compiler arguments radio button [28]. Then add an argument to change the .SWF's default size to 800x600 [29]:

-default-size=800,600


*note: FDT's new compiler requires that the -default-size argument be inputed slightly differently than what is documented within the Flex API. Use the above syntax (note the comma: , ) as a template to change the width and height.

If you ever need to find out what compiler arguments to use, click on the Show compiler documentation link on the bottom [30]. FDT will then open up your browser and navigate to the documentation home page [31].

Run your launcher again and see the External SWF View pop up [32].

A quick note here, notice how the External SWF Viewer's size is still 550x400. Our .SWF is launching at 800x600 and this will cause some odd scaling issues. To correct this, return to the Start tab of the Run Configurations window and adjust the width and height of the External SWF View to match your .SWF's default size [33].

Creating Multiple Launch Configurations

If you remember earlier, we discussed how FDT's launcher setup doesn't force developers to have their project compile and launch in any specific way. Let's demonstrate this by simply creating another launch configuration that uses the same source code, but outputs a different .SWF name. Return to the Run Configurations window, select the launch_1 configuration and click the duplicate icon on the top [34]. Rename it to launch_2 and change the Output field to make a new .swf named launch_2.swf [35].

Notice how this is using the same Main.as class as before, but we are creating a different .SWF. Run this configuration and notice how FDT will create a new launch configuration for us and save it within the launch folder and create a new launch_2.swf for us.

Using The Launcher Chain

Now we are going to put all of this together and demonstrate a clever way of using multiple launch configurations, compiler options, and the new Launcher Chain.

To get started, I'm going to clean things up a bit and delete these launch configurations and output .SWFs [36]. Next I'll create a new class, Ball, and copy the code from Main.as.

Main.as

package {
	import flash.display.Sprite;
 
	public class Main extends Sprite {
		public function Main() {
		}
	}
}

Ball.as

package {
	import flash.display.Shape;
	import flash.display.Sprite;
 
	public class Ball extends Sprite {
		public function Ball() {
			var circle : Shape = new Shape();
			circle.graphics.beginFill(0xff0000);
			circle.graphics.drawCircle(150, 150, 100);
			addChild(circle);
		}
	}
}

Next, lets modify the source for Ball.as to include some compilation variables [37]:

Ball.as

package {
	import flash.display.Shape;
	import flash.display.Sprite;
 
	public class Ball extends Sprite {
		public function Ball() {
			var circle : Shape = new Shape();
 
			CONFIG::RED{
				circle.graphics.beginFill(0xff0000);			
			}
 
			CONFIG::BLUE{
				circle.graphics.beginFill(0x0000ff);						
			}
 
			circle.graphics.drawCircle(150, 150, 100);
			addChild(circle);
		}
	}
}


Next use a Quickfix to generate a namespace [38]. Then create a launch configuration named Red_Ball [39] that uses the Ball.as class and outputs a Red_Ball.swf. Next, jump to the Compiler Arguments tab and add these arguments to the list [40]:

-define=CONFIG::RED,true
-define=CONFIG::BLUE,false


and turn off Open URI after compilation within the Start tab [41].

Now, create a copy of this configuration [42], call it Blue_Ball and have it save to a .swf named Blue_Ball.swf [43]. Before closing this configuration, update the Compiler Arguments so it's a little different than the Red_Ball configuration [44]:


-define=CONFIG::RED,false
-define=CONFIG::BLUE,true


and again make sure you turn off Open URI after compilation within the Start tab [45].

Now, back to our Main.as class, update the code with the following [46]:


package {
	import flash.net.URLRequest;
	import flash.display.Loader;
	import flash.display.Sprite;
 
	public class Main extends Sprite {
		public function Main() {
			var red_loader : Loader = new Loader();
			var blue_loader : Loader = new Loader();
 
			red_loader.load(new URLRequest('Red_Ball.swf'));			
			blue_loader.load(new URLRequest('Blue_Ball.swf'));		
 
			blue_loader.x = 200;
 
			addChild(red_loader);
			addChild(blue_loader);	
		}
	}
}


Lastly, create a new configuration to compile our Main.as class [47]. Then jump over the the Launcher Chain tab [48], click the Add button and add the two other launch configurations [49]. Then reorder the chain so our other two configurations will compile before our Main launch configuration executes [50].

Before hitting Run, lets take a step back and think about what is going on:

  • We have one Ball.as class that draws a ball.
  • There are two different launch configurations that will each use the same Ball.as class but apply different compiler options and output options to create two different .SWFs.
  • A third launch configuration was created to compile our Main.as class which will load two other .SWFs ( which don't exist yet ).
  • The third launch configuration includes a custom Launcher Chain that will make sure the other two launch configurations (Blue_Ball and Red_Ball) will run first.

Whew. It's a lot but lets hit Run and see what happens [51]. What we see here is:

  • FDT compiled two .SWFs for us, and didn't open them up (because we disabled launch URI... ) - applying specific compiler arguments to each.
  • FDT then compiled our Main.swf which in turn loaded in the two .SWFs FDT created for us.

Wrap Up

As you can see, there's a lot of potential here within FDT's launcher, and launcher chain. Feel free to experiment and let us know what you do with it!

Download the demo files here. If you're not sure how to import or export projects, check out the Sharing and Archiving Projects tutorial.

Get FDT5