XC is a Javascript compression and library creation tool.
XC is a command-line program written in C. It can be compiled with VC++ for Windows or GCC for Linux and both executables are provided (Linux support as of version 1.06.01). XC is distributed under the terms of the GNU LGPL. The source code and project files are included in the X Library distribution file.
I welcome any comments/suggestions/bug-reports you may have about XC.
The XC revision history is at the end of this document.
XC scans your application files and creates a custom X library file (with optional compression) which contains only those X variables, functions and objects (X symbols) used in your application.
XC also allows you to create a general-purpose library file containing only the X symbols you specify in a list.
XC optionally compiles all your application '*.js' files into the output file. The compiled app files will follow the compiled library files, so your app code has access to X functions while being loaded (for example xAddEventListener).
For "*.htm*" files, only the contents of SCRIPT elements are searched for X symbols. Javascript in HTML files is not compiled to the output file and function name obfuscation is not performed. So if you want to use function name obfuscation, all your Javascript should be in "*.js" files and not in the HTML files.
XC uses several different techniques to achieve optimal compression of the output file.
XC's Javascript compression feature can be used without the X Library files. This is called Standalone Mode. It is supported starting with XC v1.05.
When compressing, header comments can be preserved.
X symbols of type 'function' can be prefixed with an object name you specify, so that they become methods of the object. By default the object name is 'X'. The symbol's 'x' is removed and the next character is made lower case. For example xLeft() becomes X.left(), xWidth() becomes X.width(), etc. The XC output file will have the code for the creation of the object: objprefix={};.
XC optionally obfuscates library function names with a single character prefix followed by an uppercase base 36 number and also changes those names in your application code.
XC is invoked in X Library Mode as follows:
xc prj_name[.ext]
You can use any extension for your project file. If you don't supply an extension on the command line, '.xcp' will be assumed. XC will open the file 'prj_name.ext' in the current directory and create the output files, 'prj_name.js' and 'prj_name.log', also in the current directory.
You can associate 'xc.exe' with all '.xcp' files and then simply double-click on a project file to compile the project.
XC looks for five directives in the project file: options, libpath, obfprefix, objprefix and appfiles. The general format of the project file is as follows.
; Comments are from ';' to the end of the line.
options cmp app obf ; See option descriptions below.
; This directive is optional.
obfprefix X ; This character is used as the obfuscation prefix.
; This directive is optional. The default is 'X'.
; It can only be a single character.
objprefix X ; This string is used as the object prefix.
; This directive is optional. The default is 'X'.
; It can be any legal Javascript identifier.
libpath ..\ ; X library files directory (requires trailing backslash).
; This directive is required.
appfiles ; Application file pathnames from next line to end of file.
; This directive is required.
App file pathname 1
App file pathname 2
...
App file pathname n
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.
cmp Compression applied to output file. Default = true.
app Compile application js files to output file. Default = false.
hdr Preserve header comments (everything prior to the first code character). Default = false.
obf Obfuscate symbol identifiers. The obfuscation prefix is given by the obfprefix directive. Forces -obj. Default = false.
obj Make functions methods of an object. The object name is given by the objprefix directive. Default = false.
dep Symbol dependents included in output. Default = true. When false it is useful for creating a general-purpose lib file from a list of X symbols. I use -dep to create x_core.js, x_event.js, etc. The list of symbols is put in the xcp file (commented with ';') and the only app file is the xcp file itself. See '/x/x_core.xcp' for an example.
log Generate log file. Default = false.
dbg Write debug info to log file. Forces +log. Default = false.
The following project file builds a library that I use for two demos, floater bar and floater box. In these demos all application Javascript is in the html (php) files. The compiled library is compressed, application js is not compiled, symbols are not obfuscated, and symbol dependents are included.
; XC Project: floater_xlib options +cmp -app -hdr +dep libpath ..\lib\ appfiles floater.php floater_bar.php
The above options correspond to the default option settings of XC, so the project file could also look like the following.
; XC Project: floater_xlib libpath ..\lib\ appfiles floater.php floater_bar.php
Here's another application example. In this example all application js is in the js file, not in the html file. The compiled library is compressed, application js is compiled, symbols are obfuscated, and symbol dependents are included. Additionally, the header comments at the top of "v3site_src.js" are not removed.
; XC Project: v3site options +cmp +app +hdr +obf +dep libpath x\lib\ appfiles v3site_src.js
Here's another 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.xcp" with the following contents:
options +cmp +dep libpath ..\lib\ appfiles xtable.html
If you don't want the library file to be compressed then use -cmp in the above options.
Also in the examples folder create another text file named "xtable.bat" with the following contents:
..\xc\xc xtable @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), XC will create a general-purpose library file. You simply provide XC with a list of symbol identifiers and a library consisting of those symbols (optionally compressed) is created.
All X variables, functions and objects (symbols) are in separate files, but initially they were categorized into x_core.js, x_event.js, etc. For backwards-compatibility I still provide those files, but now I generate those files with XC. In the /x/ directory you will find these files, along with the .xcp file for each. In that directory is also a batch file, build_all.bat, which will run XC on all .xcp files in that directory.
As of XC 1.03, 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 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 XC 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.
XC is invoked in Standalone Mode as follows:
xc [-hdr] output_file input_file1 input_file2 input_file3 ...
At least two file names are required: the output file name and at least one input file name.
The input files are expected to be Javascript source files. All of the input files will be compressed and written to the output file.
Currently (as of v1.07) there is one option for standalone mode.
-hdr Preserve header comments (everything prior to the first code character).
Note that standalone mode options are preceded with a dash but this does not indicate to disable the option (as in X Library mode) but rather simply indicates that this is an option and not a file name.
Since XC's compression option removes newlines, you cannot use implicit statement termination. For example in the following the ';' (semicolon) is required because this is an assignment expression.
myObject.prototype.method = function()
{
doStuff();
}; // <- this semicolon is required to support compression
Here is another example where a semicolon is required because it is an assignment statement.
function myObjectPrototype(id)
{
var img = document.getElementById(id);
img.onmouseover = function()
{
this.src = urlOver;
}; // <- this semicolon is required to support compression
function foo()
{
} // <- a semicolon is not required here
}
One more example of an assignment statement which will require a semicolon to support compression.
window.onload = function () {
init_app();
}; // <- this semicolon is required to support compression
app option is true then the application code will be appended to the library code. Previously it was prepended. This makes X functions available to the application code as it is loaded. Typically at this point you want access to xAddEventListener.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.