Written by Simon Bailey

This post is a mental note I needed to jot down as the specific logic could be something that people may get confused with or misinterpret as I previously have. This is my moment of clarity on the subject of linking external libraries using mxmlc, in my situation it’s within an ANT script.

The scenario is that you have one or multiple external libraries e.g. RobotLegs, PureMVC, Pipes, StateMachine to be included in your application, below are what I see as the core compiler options to be considered and explanations.

Adobe Reference

• library-path - This is the ideal option for a standard non-modular application as it links SWC files to the resulting application SWF file. The compiler only links in those classes for the SWC file that are required. You can specify a directory or individual SWC files.
• include-libraries - Links all classes inside a SWC file to the resulting application SWF file, regardless of whether or not they are used. This I would recommend to use for framework libraries i.e. PureMVC, RobotLegs etc within an application utilising modules as there is a very high chance a lot of the library will be utilised across the application as a whole. You would hard bake the libraries into the core shell application allowing the modules to access the classes using external-library-path compiler option.
• external-library-path - Specifies a list of SWC files or directories to exclude from linking when compiling a SWF file. This option provides compile-time link checking for external components that are dynamically linked. This would be used for example in a module compile, it would type check the module against the classes but ultimately not compile them into the application regardless. This is sensible logic if you were using the second option in this list as we know that these classes are already in the host shell application. I would also use this option in a compc compilation i.e. SWC library for the flex SDK framework classes etc.
• load-externs - Specifies the location of an XML file that uses the same syntax as the one produced by the link-report option. This is once again ideal in a modular based application. The host shell would generate a link report using the link-report * option and you would then compile your module against this report using load-externs*. This prevents your module from including classes your host shell will already have compiled in thus preventing duplication and a potential increase in SWF size.
• runtime-shared-library-path - Specifies the location of a runtime shared library (RSL). The compiler externalizes the contents of the application that you are compiling that overlap with the RSL. This basically does what it says on the tin and is ideal for signed libraries i.e. the flex framework and rpc libraries. Be aware that if you are using this option within ANT then there currently is no specific option to declare failover-url similar to what you would expect in the flex-config.xml. This is, however, something that is being addressed and we should hopefully see an update to the flex ant jar - see my adobe bug report.