XAG is a library file creation tool. XAG scans your application files and creates a custom X library file which contains only those X variables, functions and objects (X symbols) used in your application.
XAG also allows you to create a general-purpose library file containing only the X symbols you specify in a list.
XAG optionally appends all your application '*.js' files into the output file. The app code will follow the library code, so your app code has access to X functions while being loaded.
For "*.htm*" files, only the contents of SCRIPT elements are searched for X symbols. Javascript in HTML files is not appended to the output file.
20Dec09: There are now Ant build files that automate the use of XAG. See X Tools.
XAG is invoked as follows:
xag prj_name[.ext]
You can use any extension for your project file. If you don't supply an extension on the command line, '.xag' will be assumed. XAG will open the file 'prj_name.ext' in the current directory and create the output file, 'prj_name.js', also in the current directory.
In Windows you can associate 'xag.exe' with all '.xag' files and then simply double-click on a project file to compile the project.
The general format of the project file is as follows.
; line comments start with ';' options [+|-]lib [+|-]app [+|-]dep [+|-]xpp [+|-]dbg ; optional output; optional. default " .js" libpath ; x/lib directory (with trailing slash). required obfprefix ; xpp file obfuscation prefix. optional. default "X" appfiles ; app file pathnames from next line to end of file. required
Following the 'options' directive is a space-delimited list of zero or more of the following. Prefix with '-' for false or '+' (or no prefix) for true.
lib Generate output file. Default = true.
app Append application js files to output file. Default = false.
dep Symbol dependents included in output. Default = true. When false it is useful for creating a general-purpose library file from a list of X symbols. I use -dep to create "/x/x.js". The list of symbols is put in the xag file (commented with ';') and the only app file is the xag file itself.
xpp Write xpp obfuscation file to stdout. Default = false.
dbg Write debug info to stdout. Default = false.
Here's an application example. Let's say you want to compile a library file for the xTable demo. After unzipping the X distribution file, visit the online xTable demo and "save as HTML" into your local cross-browser.com\x\examples folder. In that folder create a text file named "xtable_xlib.xag" with the following contents:
options -app +dep libpath ..\lib\ appfiles xtable.html
Also in the examples folder create another text file named "xtable.bat" with the following contents:
..\xc\xag xtable_xlib @pause
Now just run the "xtable.bat" file. It will create a file named "xtable_xlib.js" and that file will contain all the X functions and objects needed by the xTable demo. In the demo file "xtable.html" all you need is this:
<script type='text/javascript' src='xtable_xlib.js'></script>
The file names I used above are just examples. You can choose your own file names.
By setting the 'dep' option to false (symbol dependents not included), XAG will create a general-purpose library file. You simply provide XAG with a list of symbol identifiers and a library file consisting of the source code of those symbols is created.
In the /x/ directory you will find the "build_x.bat" and "x_src.xag" files which are used to build "x.js". The file "build_x.bat" shows how to integrate XPP and YUI Compressor into the build process.
@echo off set outputFileName=x.js echo. echo Building %outputFileName% xc\xag x_src rem This is where you run XPP if you need it. For example: rem xc\xpp x_xpp.js obfs_demo.xpp x_src.js rem java -jar "C:\Program Files\yuicompressor\yuicompressor-2.4.2\build\yuicompressor-2.4.2.jar" x_xpp.js -o %outputFileName% rem del x_src.js rem del x_xpp.js java -jar "C:\Program Files\yuicompressor\yuicompressor-2.4.2\build\yuicompressor-2.4.2.jar" x_src.js -o %outputFileName% del x_src.js
; XAG Project: x_src ; x.js will contain the contents of both x_core.js and x_event.js options +lib -app -dep libpath lib\ appfiles x_src.xag ; This project file is the only app file fed to XAG. ; The following X symbols will be included in the ; library file. They are commented-out so XAG will ; not see them as more app files. No dependents ; are included, only the following symbols. ; xGetElementById, xGetElementsByTagName, xGetElementsByClassName, ; xMoveTo, xLeft, xTop, xPageX, xPageY, xScrollLeft, xScrollTop, xHasPoint, ; xResizeTo, xWidth, xHeight, xClientWidth, xClientHeight, ; xStyle, xOpacity, xGetComputedStyle, xCamelize, ; xDef, xStr, xNum, xLibrary ; xAddEventListener, xRemoveEventListener, xEvent, xStopPropagation and xPreventDefault.
Symbols of type 'property' or 'method' are supported - but with a slight limitation. For a symbol's source to be included in the output library the symbol's id (see x_symbol_template.xml) must be found in your application code. For symbols of type 'P' or 'M' their ids are objectName.propertyName and objectName.methodName. So for example if you want to use the rgb animation method of the xAnimation object then XAG must find xAnimation.rgb in your code. So the solution (for now) is to put xAnimation.rgb in a comment in your application code.
Adding your own functions to the library is easy once you understand the X library structure.
X Library Viewer - View documentation, source code, revision history and more for all X symbols.
X Quick-Start - Getting started with the X Library.
X Tutorial - Collapsible/expandable sections.
X Structure - Describes how an X symbol is defined by an xml and js file.
X Tools - Summary and revision history for the X build tool chain.
XAG Reference - X Library Aggregator.
XPP Reference - General Purpose Text Preprocessor.
Forum support is available at the X Library Support Forums.