README

   1
   2 # Squish - One language to write them all, one squisher to squish them
   3
   4 Squish is a simple script to build a single file out of multiple scripts, modules, and other files.
   5
   6 For example if you have a script called A, and it requires modules X, Y and Z, all of them could be squished
   7 into a single file, B.
   8
   9 When run, Squish reads a file called 'squishy' in the current (or specified) directory, which contains
  10 instructions on how to squish a project.
  11
  12 For an example you can see Squish's own squishy file, included in this package. For reference, see below.
  13
  14 ## Building and installing
  15
  16 Squish uses itself to squish itself and its components into a single 'squish' utility that can be run anywhere.
  17 To build squish, just run "make" - there are no dependencies other than Lua.
  18
  19 You can run "make install" to copy squish to /usr/local/bin/ if you have permission.
  20
  21 ## Squishing
  22
  23 Running squish will search for a 'squishy' file in the current directory. Alternatively you can pass to squish
  24 a directory to look in.
  25
  26 Command-line options vary depending on what features squish has been built with. Below are the standard ones.
  27
  28 ### Minify
  29 'Minification' is the act of condensing source code by stripping out spaces, line breaks, comments and anything
  30 that isn't required to be there. Although the source code is re-organised and changed, the program is still the
  31 same and runs without any changes.
  32
  33 #### --no-minify
  34 Disable minification of the output file after squishing. Default is to minify.
  35
  36 #### --minify-level=level
  37 The level may be one of: none, basic, default, full
  38
  39 They vary in effectiveness, and the time taken to process large files. Experiment!
  40
  41 ### Uglify
  42 'Uglification' is the name Squish gives to a certain basic form of compression. With large files it can reduce the
  43 size by some kilobytes, even after full minification. It works by replacing Lua keywords with a single byte and
  44 inserting some short code at the start of the script to expand the keywords when it is run.
  45
  46 #### --uglify
  47 Enable the uglification filter. Default is to not uglify.
  48
  49 #### --uglify-level=LEVEL
  50 If the level specified is "full" then Squish will extend its replacement to identifiers and string literals, as
  51 well as Lua keywords. It first assigns each identifier and string a score based on its length and how many times
  52 it appears in the file. The top scorers are assigned single-byte identifiers and replaced the same as the keywords.
  53
  54 ### Gzip
  55 Gzip, or rather the DEFLATE algorithm, is extremely good at compressing text-based data, including scripts. Using
  56 this extension compresses the squished code, and adds some runtime decompression code. This decompression code adds
  57 a little bit of time to the loading of the script, and adds 4K to the size of the generated code, but the overall
  58 savings are usually well worth it.
  59
  60 #### --gzip
  61 Compress the generated code with gzip. Requires the gzip command-line utility (for compression only).
  62
  63 ### Compile
  64 Squish can compile the resulting file to Lua bytecode. This is experimental at this stage (you may get better results
  65 with luac right now), however it's a work in progress. Compiling to bytecode can actually increase the size of
  66 minified output, but it can speed up loading (not that you would notice it anyway, since the Lua compiler is so fast).
  67
  68 #### --compile
  69 Enables compilation of the output file.
  70
  71 ### Debug
  72 Due to the way Squish combines multiple scripts into one, sometimes when a squished script raises an error the traceback
  73 will be fairly unhelpful, and point to a line in the unreadable squished script. This is where the debug extension comes in!
  74
  75 #### --debug
  76 This option includes some code into the squished file which will restore the filenames and line numbers in error messages and
  77 tracebacks. This option will increase the size of the output by no more than about 6KB, so may be very much worth it when
  78 squishing large tricky-to-debug applications and libraries.
  79
  80 **Note:** Minification may interfere with the line number calculation, use --minify-level=debug to enable all features of minify
  81 that don't change line numbers, and everything will be fine.
  82
  83 ### Virtual IO
  84 Squish allows you to pack resources (any file) into the squished output. Sometimes it would be convenient to access these through
  85 the standard Lua io interface. Well now you can! :)
  86
  87 #### --virtual-io
  88 Inserts code into the squished output which replaces io.open, io.lines, dofile and loadfile. The new functions will first check
  89 whether the specified filename matches a packed resource's name. If it does then it will operate on that resource instead of an
  90 actual file. If the filename does _not_ match a resource then the function passes on to the real Lua functions.
  91
  92 ## Squishy reference
  93
  94 A squishy file is actually a Lua script which calls some Squish functions. These functions are listed here.
  95
  96 ### Module "name" "path"
  97 Adds the specified module to the list of those to be squished into the output file. The optional path specifies
  98 where to find the file (relative to the squishy file), otherwise Squish will attempt to find the module itself.
  99
 100 ### Main "script.lua"
 101 Adds a script into the squished output. Scripts are executed in the order specified in the squishy file, but only
 102 after all modules have been loaded.
 103
 104 ### Output "filename.lua"
 105 Names the output file. If none is specified, the default is 'squished.out.lua'.
 106
 107 ### Option "name" "value"
 108 Sets the specified option, to 'true', or to the optional given value. This allows a squishy file to set default
 109 command-line options.
 110
 111 ### GetOption "name"
 112 Returns the current value of the given option.
 113
 114 ### Resource "name" "path"
 115 Adds a 'resource' to the squished file. A resource may be any file, text, binary, large or small. Scripts can
 116 retrieve the resource at runtime by calling require_resource("name"). If no path is given then the name is used
 117 as the path.
 118
 119 ### AutoFetchURL "url"
 120 **Experimental** feature which is subject to change. When specified, all the following Module statements will be
 121 fetched via HTTP if not found on the filesystem. A ? (question mark) in the URL is replaced by the relative path
 122 of the module file that was given in the Module statement.
 123
 124 ## make_squishy
 125
 126 Squish includes a small utility which aims to help with converting a project to use Squish. Pass it a list of files
 127 and it will scan those files looking for calls to require(). It will then attempt to resolve the module names to
 128 files relative to the directory of the first filename passed to make_squishy.
 129
 130 It generates a 'squishy.new' file in the current directory. Modify accordingly and rename to just 'squishy'.