README

Sun, 10 Oct 2010 13:05:48 +0100

author
Matthew Wild <mwild1@gmail.com>
date
Sun, 10 Oct 2010 13:05:48 +0100
changeset 79
b697568aad71
parent 64
4beddef56d73
permissions
-rw-r--r--

README: Add 'Building and installing' section

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

mercurial