The X Library Compiler

Summary

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.

Features

Optimized Libraries

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.

Compiled Application Code

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.

Compression

XC uses several different techniques to achieve optimal compression of the output file.

  • Removes newlines.
  • Replaces tabs with spaces.
  • Removes leading whitespace.
  • Removes sequential spaces when not in a string or RegExp literal.
  • Removes spaces that have a delimiter on one side of them, when not in a string or RegExp literal.
  • Removes single-line ("//") and multiple-line ("/* */") comments. JScript conditional compilation comments are not removed.

Standalone Mode

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.

Header Preservation

When compressing, header comments can be preserved.

Objectification

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={};.

Symbol Obfuscation

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.

Using XC In "X Library Mode"

XC Invocation

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 Project File

Format

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

Options

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.

Building Application Libraries

Example 1

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
Example 2

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
Example 3

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.

Building General-Purpose Libraries

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.

Symbols of Type 'P' or 'M'

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 X Library

Adding your own functions to the library is easy once you understand the X library structure.

Using XC In "Standalone Mode"

XC 'Standalone' Invocation

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.

XC 'Standalone' Options

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.

Not Supported

Implicit Statement Termination

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

XC Revision History

XC 1.07

  • This version of XC is in the X 4.18 distribution file.
  • Thanks to ChrisNelson for ideas on the new hdr option. See this topic.

XC 1.06.01

  • Thanks to clowncoder (from the X forums) XC will now compile on Linux as well as Windows! See this topic for details. Thanks also to ChrisNelson.

XC 1.06 (23Jun07)

  • This version of XC will be released in the X 4.16 distribution file.
  • I found a problem with my previous update to the REL (regular expression literal) detection logic. Now I assume that the only characters that could be to the left of a REL are '=', '(' or ','. A '/' found with one of those characters to its left could not be a division operator. Am I missing anything? Please let me know if you think this is not complete.
  • Now if the 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.

XC 1.05 (1Jun07)

  • This version of XC will be released in the X 4.15 distribution file.
  • XC has a great new feature - Standalone Mode! You can now use XC's compression feature without needing the X Library files.
  • Previously, if you chose the "-cmp" option then XC would not fully compress but would still remove blank lines and single-line comments that started at the beginning of a line. Now when you choose "-cmp" XC will remove nothing at all.
  • Big changes! I've been doing some rigorous testing on XC and discovered a few problems: (1) The compressor was too agressive in removing sequential spaces - that is now fixed. (2) The compressor did not recognize RegExp literals and removed spaces from them - that is now fixed (but needs more testing). It also properly recognizes escaped foreslashes in RegExp literals. (3) The compressor would sometimes append the first char of one line onto the last char of the previous line, even tho sometimes a space should have been inserted - that is now fixed. This problem was showing itself in the way JScript conditional compilation sections were compressed - but XC now handles them properly.

XC 1.04 (21May07)

  • get_symbol_dependents no longer excludes symbols found in "//" comments. In certain situations it was doing it incorrectly. Thanks very much to Cyrillus for the bug report.
  • Rewrote processing of start and end of strings. This fixed a problem with detecting escaped backslashes.
  • Fixed a problem with ignoring single-line comments inside multi-line comments.

XC 1.03 (26Apr07)

  • I caused problems by trying to have xAnimation methods as separate symbols. Now those methods will have symbols like this: "xAnimation.methodName". I modified get_symbol_index and wrote str_tok. This is not a solution, but just a quick bandaid because to get, for example, "xAnimation.css" included in the output library XC must find the symbol "xAnimation.css" somewhere in the source. It can be put in a comment for this purpose. After this I saw that methods could possibly be ouput before their object. I used qsort and wrote compare_fn. Symbols are sorted by type and then by id. The type precedence is: V, O, P, M, F.

XC 1.02 (20Jan07)

  • When removing comments, JScript conditional compilation comments are not removed.

XC 1.01 (31Oct06)

  • New option: obj - objectify function names. will prefix all X functions with an object name you specify. The xSplitter demo is now using this feature.
  • Now +cmp is not required for +obf.
  • Wrote stricmp and uitoa to remove some non-ansi functions. Current non-ansi usage (all from io.h): struct _finddata_t, _findfirst, _findnext, _findclose. It should be relatively easy to port to some *nix now.
  • Fixed a bug that was in XC 1.0 which prevented a symbol file from being included if there was an app file with the same name and option +app was set.

XC 1.0 (24Oct06)

  • Release.

XC 0.34b (5Oct06)

  • Replaces tabs with spaces.
  • Now gets version from xLibrary object in xlibrary.js.
  • During compression it now checks if a comment directive is in a string.
  • Now compression also skips multi-line comments.
  • Removed support for these options: lws, nln, and bln.
  • For *.htm* app files, only the script elements are parsed for X symbols.
  • Now compression also skips sequential spaces, when not in a string.
  • Cmp now removes spaces that have a delimiter on one side of it.
  • New option: obf - obfuscate function names.
  • New option: app - compresses and adds app js files to output.
  • Support for the glb option is disabled.
  • Now X symbols are not required to have an 'x' prefix.

XC 0.29b (21Sep06)

  • Allow .xcp extension on command line arg. Thanks to gagenellina for code.

XC 0.28b (8Aug05)

  • Now parses x symbols in quotes. Thanks for bug report from Miguel Angel Alvarez.

XC 0.24b (25May05)

  • Removed all txt doc support for now.

X Documentation

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.

Search

Cross-Browser.com

World Wide Web

Tech Support

Forum support is available at the X Library Support Forums.

License

By your use of X and/or CBE and/or any Javascript from this site you consent to the GNU LGPL - please read it. If you have any questions about the license, read the FAQ and/or come to the forums.