From: Mihai Bazon Date: Sun, 29 Mar 2015 10:13:40 +0000 (+0300) Subject: Update README X-Git-Url: https://git.ndcode.org/public/gitweb.cgi?a=commitdiff_plain;h=3ec11c781b61efd53c001c05e8e52fbd1e6e9034;p=UglifyJS.git Update README --- diff --git a/README.md b/README.md index a84fce88..7116e45b 100644 --- a/README.md +++ b/README.md @@ -52,70 +52,87 @@ a double dash to prevent input files being used as option arguments: The available options are: ``` - --source-map Specify an output file where to generate source map. - [string] - --source-map-root The path to the original source to be included in the - source map. [string] - --source-map-url The path to the source map to be added in //# - sourceMappingURL. Defaults to the value passed with - --source-map. [string] - --source-map-include-sources - Pass this flag if you want to include the content of - source files in the source map as sourcesContent - property. [boolean] - --in-source-map Input source map, useful if you're compressing JS that was - generated from some other original code. - --screw-ie8 Pass this flag if you don't care about full compliance - with Internet Explorer 6-8 quirks (by default UglifyJS - will try to be IE-proof). [boolean] - --expr Parse a single expression, rather than a program (for - parsing JSON) [boolean] - -p, --prefix Skip prefix for original filenames that appear in source - maps. For example -p 3 will drop 3 directories from file - names and ensure they are relative paths. You can also - specify -p relative, which will make UglifyJS figure out - itself the relative paths between original sources, the - source map and the output file. [string] - -o, --output Output file (default STDOUT). - -b, --beautify Beautify output/specify output options. [string] - -m, --mangle Mangle names/pass mangler options. [string] - -r, --reserved Reserved names to exclude from mangling. - -c, --compress Enable compressor/pass compressor options. Pass options - like -c hoist_vars=false,if_return=false. Use -c with no - argument to use the default compression options. [string] - -d, --define Global definitions [string] - -e, --enclose Embed everything in a big function, with a configurable - parameter/argument list. [string] - --comments Preserve copyright comments in the output. By default this - works like Google Closure, keeping JSDoc-style comments - that contain "@license" or "@preserve". You can optionally - pass one of the following arguments to this flag: - - "all" to keep all comments - - a valid JS regexp (needs to start with a slash) to keep - only comments that match. - Note that currently not *all* comments can be kept when - compression is on, because of dead code removal or - cascading statements into sequences. [string] - --preamble Preamble to prepend to the output. You can use this to - insert a comment, for example for licensing information. - This will not be parsed, but the source map will adjust - for its presence. - --stats Display operations run time on STDERR. [boolean] - --acorn Use Acorn for parsing. [boolean] - --spidermonkey Assume input files are SpiderMonkey AST format (as JSON). - [boolean] - --self Build itself (UglifyJS2) as a library (implies - --wrap=UglifyJS --export-all) [boolean] - --wrap Embed everything in a big function, making the “exports” - and “global” variables available. You need to pass an - argument to this option to specify the name that your - module will take when included in, say, a browser. - [string] - --export-all Only used when --wrap, this tells UglifyJS to add code to - automatically export all globals. [boolean] - --lint Display some scope warnings [boolean] - -v, --verbose Verbose [boolean] - -V, --version Print version number and exit. [boolean] + --source-map Specify an output file where to generate source + map. + --source-map-root The path to the original source to be included + in the source map. + --source-map-url The path to the source map to be added in //# + sourceMappingURL. Defaults to the value passed + with --source-map. + --source-map-include-sources Pass this flag if you want to include the + content of source files in the source map as + sourcesContent property. + --in-source-map Input source map, useful if you're compressing + JS that was generated from some other original + code. + --screw-ie8 Pass this flag if you don't care about full + compliance with Internet Explorer 6-8 quirks + (by default UglifyJS will try to be IE-proof). + --expr Parse a single expression, rather than a + program (for parsing JSON) + -p, --prefix Skip prefix for original filenames that appear + in source maps. For example -p 3 will drop 3 + directories from file names and ensure they are + relative paths. You can also specify -p + relative, which will make UglifyJS figure out + itself the relative paths between original + sources, the source map and the output file. + -o, --output Output file (default STDOUT). + -b, --beautify Beautify output/specify output options. + -m, --mangle Mangle names/pass mangler options. + -r, --reserved Reserved names to exclude from mangling. + -c, --compress Enable compressor/pass compressor options. Pass + options like -c + hoist_vars=false,if_return=false. Use -c with + no argument to use the default compression + options. + -d, --define Global definitions + -e, --enclose Embed everything in a big function, with a + configurable parameter/argument list. + --comments Preserve copyright comments in the output. By + default this works like Google Closure, keeping + JSDoc-style comments that contain "@license" or + "@preserve". You can optionally pass one of the + following arguments to this flag: + - "all" to keep all comments + - a valid JS regexp (needs to start with a + slash) to keep only comments that match. + Note that currently not *all* comments can be + kept when compression is on, because of dead + code removal or cascading statements into + sequences. + --preamble Preamble to prepend to the output. You can use + this to insert a comment, for example for + licensing information. This will not be + parsed, but the source map will adjust for its + presence. + --stats Display operations run time on STDERR. + --acorn Use Acorn for parsing. + --spidermonkey Assume input files are SpiderMonkey AST format + (as JSON). + --self Build itself (UglifyJS2) as a library (implies + --wrap=UglifyJS --export-all) + --wrap Embed everything in a big function, making the + “exports” and “global” variables available. You + need to pass an argument to this option to + specify the name that your module will take + when included in, say, a browser. + --export-all Only used when --wrap, this tells UglifyJS to + add code to automatically export all globals. + --lint Display some scope warnings + -v, --verbose Verbose + -V, --version Print version number and exit. + --noerr Don't throw an error for unknown options in -c, + -b or -m. + --bare-returns Allow return outside of functions. Useful when + minifying CommonJS modules. + --keep-fnames Do not mangle/drop function names. Useful for + code relying on Function.prototype.name. + --reserved-file File containing reserved names + --reserve-domprops Make (most?) DOM properties reserved for + --mangle-props + --mangle-props Mangle property names + --name-cache File to hold mangled names mappings ``` Specify `--output` (`-o`) to declare the output file. Otherwise the output @@ -189,6 +206,69 @@ comma-separated list of names. For example: to prevent the `require`, `exports` and `$` names from being changed. +### Mangling property names (`--mangle-props`) + +**Note:** this will probably break your code. Mangling property names is a +separate step, different from variable name mangling. Pass +`--mangle-props`. It will mangle all properties that are seen in some +object literal, or that are assigned to. For example: + +```js +var x = { + foo: 1 +}; + +x.bar = 2; +x["baz"] = 3; +x[condition ? "moo" : "boo"] = 4; +console.log(x.something()); +``` + +In the above code, `foo`, `bar`, `baz`, `moo` and `boo` will be replaced +with single characters, while `something()` will be left as is. + +In order for this to be of any use, we should avoid mangling standard JS +names. For instance, if your code would contain `x.length = 10`, then +`length` becomes a candidate for mangling and it will be mangled throughout +the code, regardless if it's being used as part of your own objects or +accessing an array's length. To avoid that, you can use `--reserved-file` +to pass a filename that should contain the names to be excluded from +mangling. This file can be used both for excluding variable names and +property names. It could look like this, for example: + +```js +{ + "vars": [ "define", "require", ... ], + "props": [ "length", "prototype", ... ] +} +``` + +`--reserved-file` can be an array of file names (either a single +comma-separated argument, or you can pass multiple `--reserved-file` +arguments) — in this case it will exclude names from all those files. + +A default exclusion file is provided in `tools/domprops.json` which should +cover most standard JS and DOM properties defined in various browsers. Pass +`--reserve-domprops` to read that in. + +When you compress multiple files using this option, in order for them to +work together in the end we need to ensure somehow that one property gets +mangled to the same name in all of them. For this, pass `--name-cache +filename.json` and UglifyJS will maintain these mappings in a file which can +then be reused. It should be initially empty. Example: + +``` +rm -f /tmp/cache.json # start fresh +uglifyjs file1.js file2.js --mangle-props --name-cache /tmp/cache.json -o part1.js +uglifyjs file3.js file4.js --mangle-props --name-cache /tmp/cache.json -o part2.js +``` + +Now, `part1.js` and `part2.js` will be consistent with each other in terms +of mangled property names. + +Using the name cache is not necessary if you compress all your files in a +single call to UglifyJS. + ## Compressor options You need to pass `--compress` (`-c`) to enable the compressor. Optionally