ConfigOption enum.Options that support a "query data override" can be specified in any of the following places:
/compile servlet./compile URL via a <script> tag, such that the URL of the page that loads the URL will be sent via the referer header. (Note that a user agent that loads a file:// URL will not send the referer for security reasons.)http://example.com/foo?mode=SIMPLE loads http://example.com:9810/compile?id=test&mode=ADVANCED via a <script> tag, then mode=SIMPLE will take precedence and the code returned by http://example.com:9810/compile?id=test&mode=ADVANCED will be compiled in SIMPLE mode rather than in ADVANCED mode. This makes it easier to change compilation options without editing the config file or the URL in the <script> tag.ambiguate-properties, checks, closure-library, custom-externs-only, custom-passes, debug, define, disambiguate-properties, experimental-compiler-options, experimental-exclude-closure-library, export-test-functions, externs, fingerprint, global-scope-name, id, id-generators, inherits, inputs, jsdoc-html-output-path, level, mode, module-info-path, module-output-path, module-production-uri, modules, name-suffixes-to-strip, output-charset, output-file, output-wrapper, paths, pretty-print, print-input-delimiter, property-map-input-file, property-map-output-file, soy-function-plugins, test-excludes, test-template, treat-warnings-as-errors, type-prefixes-to-strip, variable-map-input-file, variable-map-output-file
stringEvery config must have an id. The id must be unique among the configs being served by plovr because the id is a parameter to every function in the plovr REST API.
string, arrayInput files to be compiled. Each input file and its transitive dependencies will be included in the compiled output.
string, arrayFiles or directories where the transitive dependencies of the inputs can be found.
string, arrayFiles that contain externs that should be included in the compilation. By default, these will be used in addition to the default externs bundled with the Closure Compiler.
There are also externs for third party libraries, such as jQuery and Google Maps, that are bundled with the Closure Compiler but are not enabled by default. (This article from the Closure Tools blog explains why adding unneccessary externs can inhibit the Compiler's ability to rename properties.) These additional extern files can be seen in the Closure Compiler's contrib/externs directory. Such externs can be included with a // prefix as follows:
"externs": [ "//jquery-1.5.js", "//google_maps_api_v3.js", "//chrome_extensions.js" ]
booleanWhether only the custom externs specified by externs should be used (rather than in addition to the default externs bundled with the Closure Compiler).
stringPath to the version of the Closure Library that should be used instead of the version of the Closure Library that is bundled with plovr. When specified, it should identify the root directory that contains base.js for that instance of the library, so a sample value might be "../closure-library/closure/goog/".
booleanThis is an experimental option to address Issue 40. When set to true, it will exclude Closure Library's base.js from the compiled output. This is primarily for developers using a library other than Closure, such as jQuery. Because neither goog.require() nor goog.provide() will be defined without base.js, all inputs to compilation will have to be listed explicitly, in order, as part of the inputs option in the config.
It is possible (but not guaranteed) that goog.provide() and goog.require() will be processed correctly by the Compiler in either SIMPLE or ADVANCED mode, even if base.js from the Closure Library is not present. Therefore, it may be possible to use those functions as "directives" that will be processed by the Compiler to express dependencies (which may be useful if you have complex dependencies that transitively depend on jQuery but not the Closure Library, for example). However, using goog.provide() and goog.require() in RAW or WHITESPACE mode will almost definitely not work without base.js.
Because this is an experimental option, it may be removed at some point with a more generic solution for excluding the Closure Library when using another library, such as jQuery or Dojo.
stringCompilation mode, which must be one of "RAW", "WHITESPACE", "SIMPLE", or "ADVANCED". The default value is "SIMPLE".
stringWarning level, which must be one of "QUIET", "DEFAULT", or "VERBOSE". The default value is "DEFAULT".
stringConfig file from which to inherit. When compiling multiple JavaScript files for the same project, you are likely to have common settings across your plovr config files. For this reason, it is possible for one config file to "inherit" from another config file. For example, you might have a "root" config file that has settings that are universal to all of your config files:
// root-config.js
{
"paths": "js",
"mode": "ADVANCED",
"level": "VERBOSE",
"checks": {
"deprecated": "ERROR",
"nonStandardJsDocs": "ERROR"
}
}Then you can use inherits option in the config files for your specific build targets such that they "inherit" the settings from the root config file, eliminating the need to copy and paste the common options:
// app-config.js
{
"id": "app",
"inherits": "root-config.js",
"inputs": "js/app/main.js"
}
// api-config.js
{
"id": "api",
"inherits": "root-config.js",
"inputs": "js/api/exports.js"
}Similarly, you may want to have a production and development configs that differ only in their values for the mode and level options.When an option is overridden by a child config file, the value on the right in the child config file outright replaces any value from a parent config file. Therefore, if you have a child config file that wants to add one value to the checks option, the child config file must list all of the parent checks in addition to the check it wants to add. Again, this is because config file inheritance options replace parent values: they are not additive.
booleanEquivalent to the command-line --debug flag for the Closure Compiler. Defaults to false.
booleanEquivalent to the command-line --formatting=PRETTY_PRINT flag for the Closure Compiler. Defaults to false.
booleanEquivalent to the command-line --formatting=PRINT_INPUT_DELIMITER flag for the Closure Compiler. Defaults to false.
stringIf specified, when the build command is used, plovr will write the compiled output to this file rather than standard out. Note that if modules are used, you must use module-output-path instead.
string, arrayIf specified, a template into which compiled JavaScript will be written. The placeholder for compiled code is %output%, so to wrap the compiled output in an anonymous function preceded by a copyright comment, specify:
"output-wrapper": "// Copyright 2011\n(function(){%output%})();",The value may also be an array of strings that will be concatenated together:
"output-wrapper": [
"var http = require('http');\n",
"var https = require('https');\n",
"var nodeUrl = require('url');\n"
]
This is helpful if there are many lines to include that would normally be hard to read if the template were one long string.stringDefaults to "US-ASCII". Although datetimesymbols.js in the Closure Library contains many non-ASCII characters, all of them are in string literals, so the Closure Compiler is able to represent them using the ASCII charset by escaping them. For example, the string 'sábado' that contains the non-ASCII character 'á' will be output as 's\u00e1bado'.
If you use a lot of international characters in your strings, then you may want to consider setting this to "UTF-8". Though if you do so, in order to make sure that your JavaScript code is interpreted with the correct character encoding, make sure to specify it in the <script> tag as follows:
<script type="text/javascript" src="myscript.js" charset="utf-8"></script>
booleanWhether to fingerprint the JS files for modules when plovr is used in build mode. The fingerprint is an md5 hash of the file content. Defaults to false.
objectAn object literal that contains mappings from module names to module definitions. Each module definition should have two properties: inputs and deps. The inputs property specifies the inputs that must be contained in that module. The deps property specifies the modules that the specified module depends on. The value of each property may be either a single string literal or an array of string literals. Because the graph of modules must form a rooted DAG, exactly one module may specify an empty array as its value for deps, as that module must be the root module.
"modules": {
"app": {
"inputs": "app_init.js",
"deps": [] // This must be the root module.
},
"api": {
"inputs": ["api.js", "api_init.js"],
"deps": "app"
},
"settings": {
"inputs": "settings_init.js",
"deps": "app"
}
}stringstringstringstringA scope name for multiple modules to share. This will cause modules to be wrapped with a
(function(a) { with (a) { ... } })(scope)(and the main module will additionally start with scope = {} so that you don't actually have to do anything special). As a result, none of the modules' global variables will make it to the real global scope. Instead they will be inside of the specified scope variable, which should not be touched by any other code on the page.objectAn object literal that contains a mapping of variables in the JavaScript code that are annotated with @define (indicating that they can be redefined at compile time) to the values that should be substituted. The following should be specified to set goog.DEBUG to false at compile time:
"define": {
"goog.DEBUG": false
}Note that these compile-time defines will only take effect when the code is compiled in either SIMPLE or ADVANCED modes.objectAn object literal that contains a mapping of Closure Compiler checks to the desired check level, which must be one of "OFF", "WARNING", or "ERROR". The following is an example of enabling a fairly strict set of checks:
"checks": {
// Unfortunately, the Closure Library violates these in many places.
// "accessControls": "ERROR",
// "visibility": "ERROR"
"checkRegExp": "ERROR",
"checkTypes": "ERROR",
"checkVars": "ERROR",
"deprecated": "ERROR",
"fileoverviewTags": "ERROR",
"invalidCasts": "ERROR",
"missingProperties": "ERROR",
"nonStandardJsDocs": "ERROR",
"undefinedVars": "ERROR"
}These are analogous to the --jscomp_off, --jscomp_warning, and --jscomp_error command-line flags for the Closure Compiler.booleanWhen set to true, warnings will be reported as errors. Recall that compilation will still succeed if there are warnings, but will fail if there are any errors, so enabling this option will draw more attention to any potential problems detected by the Closure Compiler.
booleanWhen compiled, all global functions that start with test will be exported via goog.exportSymbol() so that when run as part of the Closure testing framework, the test methods will still be able to be discovered. In short, this makes it possible to unit test JavaScript code compiled in Advanced mode.
string, arraystring, arraystring, arrayIt is common to set this option as follows so that all event ids are unique:
"id-generators": ["goog.events.getUniqueId"],See p.444 of Closure: The Definitive Guide for details.
booleanbooleanobjectThe Closure Compiler contains many options that are only available programmatically in Java. Many of these options are experimental or not finalized, so they may not be a permanent part of the API. Nevertheless, many of them will be useful to you today, so plovr attempts to expose these the experimental-compiler-options option. Under the hood, it uses reflection in Java, so it is fairly hacky, but in practice, it is a convenient way to experiment with Closure Compiler options without writing Java code.
If you look at the source code for CompilerOptions.java (which is part of the Closure Compiler), you will see that there are many fields, some of which are public, and some of which are package-private, but are configurable via setter methods. plovr supports setting both types of options through experimental-compiler-options. Consider the following example:
"experimental-compiler-options": {
"instrumentForCoverage": true,
"checkShadowVars": "ERROR",
"languageIn": "ECMASCRIPT5"
}This example exhibits several of the supported cases:instrumentForCoverage is a public boolean field, so plovr can directly set its value to true.checkShadowVars is also a public field, but it has an enum type, CheckLevel. Upon determining that the type of the field is an enum, it uses its valueOf() method in Java to create the enum value that corresponds to the string in the plovr config file. Therefore, when specifying an enum value in experimental-compiler-options, use the name of the enum value as a string (just like you would for the checks option).languageIn is a package private field, but there is a setter method named setLanguageIn() in CompilerOptions. Again, using reflection, plovr discovers the method and that it takes an enum value, so it uses the valueOf() method of LanguageMode to get the enum value and then invokes the setLanguageIn() method to set the field in CompilerOptions.applyExperimentalCompilerOptions() method in org.plovr.Config. Fear not, as it has a corresponding unit test!) Fortunately, you should not have to worry about the implementation details, in practice. If plovr cannot set a property that you have specified in experimental-compiler-options, then it will print a message to standard error.arrayYou can add custom behavior to the Closure Compiler by adding your own compiler pass. The standard way to do this is to create a Java class that implements the CompilerPass interface and scheduling it to run by adding it to the customPasses field of the Closure Compiler (along with a CustomPassExecutionTime). With plovr, you still need to implement CompilerPass, but you schedule it by listing it in your plovr config. As an example, take a look at the CheckDoubleEquals class, which is derived from the "Creating a Compiler Check" example from Chapter 14 of Closure: The Definitive Guide. As shown in config.json, it can be included during compilation by using the custom-passes option as follows:
"custom-passes": [
{
"class-name": "org.plovr.CheckDoubleEquals",
"when": "BEFORE_CHECKS" // this value is from the CustomPassExecutionTime enum
}
// Because "custom-passes" is a list, you can add
// as many passes as you like.
]Also note that CheckDoubleEquals implements DiagnosticGroupRegistrar, which is a plovr interface that makes it easy to register a DiagnosticGroup, which is a collection of Closure Compiler checks. In the case of CheckDoubleEquals, it registers a group under the name checkDoubleEquals that contains two checks: one for == and one for !=. Note that it is possible to assign a warning level in the checks section of the config file for the DiagnosticGroup that you registered. You can also see an example of this in config.json:"checks": {
"checkDoubleEquals": "WARNING",
}Note that when developing a CompilerPass in Java, plovr has all of the Closure Compiler classes that you need to compile against to create your pass, so include plovr.jar on your classpath when developing your CompilerPass. Further, when running plovr with your CustomPass, make sure to include the .class file for your CustomPass (and any of its dependencies) on the classpath, as well.
string, arraySpecifies the full class names of Guice modules for Soy (Closure Templates) function plugins and print directive plugins. For example, "org.plovr.soy.function.PlovrModule" defines the Soy function substring(), so to use that function in your Closure Templates, include this option in your plovr config:
"soy-function-plugins": "org.plovr.soy.function.PlovrModule",
stringstringIf specified, plovr will pre-populate the compiler's variable map with the variable map contained in this file.
stringIf specified, when the build command is used, plovr will write the used variable map to this file.
stringIf specified, plovr will pre-populate the compiler's property map with the property map contained in this file.
stringIf specified, when the build command is used, plovr will write the used property map to this file.
stringThe Soy file to use as a template for JsUnit-style tests. The template will receive the following parameters:
titlebaseJsUrltestJsUrl{namespace org.plovr}
/**
* @param title
* @param baseJsUrl
* @param testJsUrl
*/
{template .test}
<!doctype html>
<html>
<head>
<title>{$title} test</title>
</head>
<body>
<script src="{$baseJsUrl}"></script>
<script src="{$testJsUrl}"></script>
</body>
</html>
{/template}The value of the test-template option is not the content of your template, but the path to the .soy file that defines your template. Your template must be named org.plovr.test, just like the default template.See the section on testing for more details.
string, arrayBy default, all files that end in _test.js under the paths directories are included in the test runner that runs all of the JS unit tests. This option can be used to specify subpaths of paths that should be excluded from testing.
For example, if the closure-library option is used to specify a custom Closure Library, then it is likely that "third_party/closure" will be specified as a path to include utilities such as goog.async.Deferred. Including such a directory will also include closure/goog/dojo/dom/query_test.js, which fails when run by plovr because its corresponding query_test.html file includes a hardcoded path to base.js that cannot be loaded by plovr. If this is a problem, then "third_party/closure" should be included as an argument to test-excludes.
See the section on testing for more details.