AS3 -load-externs

Jan 11 2007 Published by under Flash

[Important Warning: the technique described here will not work in Flex Builder 2 or the original Flex 2 SDK. Although this was a documented feature, it did not work very well. And by “not very well”, I mean it did absolutely nothing. This has been fixed in Flex Builder 2.01, and I assume the Flex 2 SDK has also been updated, but you should verify that if that’s what you are using.]

Took me a bit to figure this out today, but it’s pretty cool.

You are probably familiar with this situation: You have a SWF which loads another SWF. The child SWF shares some of the classes that have already loaded in with the parent. Say the parent is 100k, and the child is 60k, but 30k of that 60 is already compiled into the parent. You need to have those classes at compile time, but you know the child is only going to exist in the parent, so there’s no need for it to carry along all that byte code. Furthermore, you might have a dozen or more child SWFs, all of which share that same 30k from the parent. It starts to add up.

In AS2 we had exclude.xml files. You had to manually figure out which classes were in the parent and which were in the child and type out an xml file that said which ones you wanted to exclude while compiling the child. I’m sure a few figured out how to automate the process somewhat, but I bet 90% of developers opened up their xml editor and type away.

AS3 actually has a few ways of tackling this situation. Actually, there are about a half dozen compiler options solely related to specifying which classes get compiled into the SWF and which will just be available for compile time checking. The one that most resembles the AS2 method is -load-externs. Here’s how it works.

First, you compile your parent SWF as usual, but you add one command line switch, either in the command line, the ant target, or in the compiler args in Flex Builder. This is -link-report=parentLinkReport.xml, of course, giving it whatever file name you want. This generates a complete report, in xml format, of all the classes that are compiled into the SWF. It also includes what classes those classes have dependencies on, what classes must be linked to prior to that class being compiled, and any classes that are externally linked to. It’s a pretty comprehensive diagnostic tool in and of itself. But the really awesome part is next.

You remember that old exclude.xml file you used in AS2? Well, there’s a new format for how that is all structured. And it just so happens that the format is the exact format that is output by the -link-report option! So, you take that link report xml that was generated when you compiled the parent SWF, and when you pass that in to the -load-externs option when you compile the child SWF, like so: -load-externs=parentLinkReport.xml.

The child is now compiled, and all the classes that are in the parent are automatically excluded from that SWF. You don’t have to analyze it and write up a list of classes. You don’t even have to think about it. In fact, you can easily set it up to be fully automated with Ant. Compile the parent and generate the report, compile the child using the report. If your parent SWF changes, adding or removing classes, the child SWF is automatically kept up to date as part of the process.

This may or may not be the ideal option for what you are doing. As I said, there are several other options, such as -externs, -external-library-path, -include-libraries, -includes, -library-path, -runtime-shared-libraries, and -source-path, that all have to do with what classes are included or not, and give you a lot of flexibility in how your apps are compiled.

22 responses so far. Comments will be closed after post is one year old.

  • Tim says:

    This is great when used in conjunction with the Module feature in 2.01. I was able to cut down on the loaded module SWF size considerably.

  • sascha/hdrs says:

    Sweet! I’m sure this will come in handy!

  • sascha/hdrs says:

    Is there a way to have the xml file being created in the project folder instead in the Eclipse folder? With -link-report=${DOCUMENTS}\projectfolder\linkreport.xml it doesn’t work as and complains about the unknown token ${DOCUMENTS}. Sure, I could just give him the absolute path but that would be not nice.

  • Miha says:

    That’s pretty interesting 🙂

  • Great post Keith! I wasn’t sure how this worked in Flex yet, and this certainly is much easier than what I was used to dealing with in the IDE.


  • Tink says:

    Well fathomed out.

  • Chris Allen says:

    Ahh, now I know why you were asking me those Ant questions the other day. 😉 Cool stuff!

  • Matt Garland says:

    FYI: Using Flex Builder 2.01/OS X/compiler args, I could only get this to work with an absolute address, i.e, -link-report=/Documents/Workspace/MyProject/classes/linkReport.xml.

  • felix says:

    good stuff. Is it possible to use any of these options when compiling via the Flash IDE?

  • Elango says:

    Is there a way I can use “-load-externs=parentLinkReport.xml” to reduce my main application size?


  • Steve says:

    Anyone had any luck doing this with the Flash CS3 IDE. I can’t find documentation or any other notes on this anywhere.


  • Steve Bond says:

    For anyone looking for how to do this in Flash CS3, I’ve just finished speaking with an Adobe support engineer regarding this issue and I just thought I’d update this thread. It seems, at present, the exclusion functionality available when publishing AS2 does not exist when publishing AS3. The engineer suggested that additional functionality might be added in an update to the software, and would be reflected in the support documentation.

  • Michael Prescott says:

    Wow, you wouldn’t believe how hard it was to learn that we can no longer use exclude files. I really disliked maintaining dozens of exclude files in our large projects, but I’m just as disappointed that every referenced class is going to be compiled into every loadable module (swf) now. Besides switching production to Flex, or creating loose references, does anyone have any ideas on what to do about this?

  • Tom Vian says:

    Any classes compiled into an .swc which lies in the same folder as the .fla you’re trying to publish will be included for type checking at compile time, but will actually be excluded from the .swf. The method is a little more complicated than the _exclude.xml, seeing as how you have to recompile the .swc each time you need to update it. With a little experimentation, its just about workable though and it looks like it’s all we’ve got for now…


  • […] Exclude.xml, functionality in Flash 8 and MX 2004 that allowed you to exclude ActionScript 2 classes compiled into your SWF, does not work in Flash CS3 for ActionScript 3. A similar function is available in Flex 2 via the load-externs option. This is the basis of how Flex modules work. The lack of this functionality just adds another challenge to Flash Developers who have expectations coming from AS2; this actually makes AS3 usage in Flash worse than AS2 when creating Flash sites, or large Flash applications. […]

  • Zach says:

    Hey Keith,

    This is good info, but I am running into RSL-heck here like crazy. I am trying to set up a large, but pretty well-architected pure as business application. We have 5 proprietary swcs whose dependencies I have a grasp on, but then with the 5 framework rsls that we use (playerglobal, framework, flex, automation, utilities) I am totally lost regarding their dependencies and whether they should be loaded with the eternal-library-path or the runtime-shared-library patch attribute. Do you know of a resource that explains these dependencies and compile switches effectivley? Your blog seems to allude that you may know this, so any help would be very appreciated.


  • Michael Prescott says:

    Years later, and we’ve finally brought flex into our workflow. So, using mxmlc from flex sdk to compile a and that includes the same classes I find that Child.swf is actually a few bytes larger. The report looks ok, documenting all classes included in Parent.swf, so the question is does -load-externs work with ActionScript projects in this version of the sdk?

  • […] The process is pretty straight forward, compile your main application supplying the link-report flag, this will dump out an XML file. Next, compile all your subapps supplying the load-externs flag. Keith Peters goes into more detail on his blog. […]

  • Diego says:

    Great explanation! It´s just what I need

  • […] 模块化等等,在此就不一一赘述了。 相关链接如下: […]

  • […] The process is pretty straight forward, compile your main application supplying the link-report flag, this will dump out an XML file. Next, compile all your subapps supplying the load-externs flag. Keith Peters goes into more detail on his blog. […]

  • […] found references on how to do this when compiling with the command-line compiler (detailed here:, but so far I’ve haven’t been able to find anything that details how to do this in the […]