XC is a Javascript compression and library creation tool.
XC is a Win32 console (command-line) program written in C. XC is distributed under the terms of the GNU LGPL. The source code and VC++ 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.
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'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.
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 Compiles application js files to output file. 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 +lib +cmp -app -obf -obj +dep -log -dbg 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.
; XC Project: v3site options +lib +cmp +app +obf -obj +dep -log -dbg libpath x\lib\ appfiles v3site_src.js
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 id
s 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 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.
That's it! XC Standalone is extremely easy to use.
Currently (v1.05) there are no options. I may add some later.
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 Index - X Library Index.
X Quick-Start - Getting Started with the X Library.
X Structure - X Library Structure.