shaka-player/build/README.md

This directory contains the scripts used to build and test Shaka Player. These scripts can run on any platform that supports python v2.7 and JRE 8+.

• all.py simply runs gendeps.py, check.py, docs.py, and build.py. It will forward --force to build.py.
• build.py builds the compiled library. This will fail if there are syntax or type errors.
• check.py will check all the files for style violations and will check the tests for type errors (but will not produce any compiled output).
• checkversion.py is used internally as part of our release process.
• docs.py will build the documentation. The output will be in docs/api.
• gendeps.py will create deps.js which is required to use the uncompiled library.
• shakaBuildHelpers.py is a utility library used by these scripts.
• stats.py will read the compiled library and source map to get information about the size of the compiled library.
• test.py will run the unit/integration tests.

All the scripts here use two environment variables:

• PRINT_ARGUMENTS if set, will print the command-line to subprocesses.
• RAISE_INTERRUPT if set, will raise interrupts rather than swallowing them.

$ PRINT_ARGUMENTS=1 build.py
git -C /path/to/shaka describe --tags --dirty
Compiling the library...
java -jar /path/to/shaka/node_modules/.../compiler.jar --language_in ...

Configurable Build

build.py is used to compile the library and can also be used to produce customized builds that contain only the features that your app requires. build.py accepts an optional argument --name which will set the name of the build, defaulting to ui. All other arguments are treated as commands describing what to include in the build. If nothing is given, it will use +@complete.

A command is either an addition or a subtraction. An addition is prefixed with a +; a subtraction with a -. An addition will add the JavaScript file (or build file) to the resulting library while a subtraction will remove it. After the first character, there is either the path to a JavaScript file, or a @ followed by the name of a build file.

Build files are the files found in build/types/. These files are simply a newline separated list of commands to execute. So if the +@complete command is given, it will open the complete file and run it (which may in turn open other build files). Subtracting a build file will reverse all actions applied by the given file. So -@networking will remove all the networking plugins.

# Examples:
build.py +@complete
build.py +@complete -@networking
build.py --name custom +@manifests +@networking +../my_plugin.js

Test

test.py accepts some arguments, but mostly will forward them to karma. You can run karma start --help to get more info about the karma test runner. If you don't have karma installed, it will be installed by npm install and will be found in node_modules/.bin.

test.py has two arguments that it handles directly. --force will cause the build to run even if there are no changes detected to the source code. --no-build will not build the library even if it does not exist. Note that some integration tests will not run without the compiled library present.

There are also several custom arguments that are handled in JavaScript by karma.conf.js or the tests themselves (via getClientArg). These arguments can be passed in using test.py or using karma start directly:

• --quick will only run unit tests, skipping integration tests.
• --enable-logging will enable console logging. Logs will be printed to the console. It also accepts a value for the log level --enable-logging=1, defaulting to 3. See lib/debug/log.js for the log levels (you must pass the number).
• --external will run integration tests against external assets. This will take an extremely long time to run, and requires a fast and reliable internet connection.
• --drm will run integration tests against DRM license servers. This will require a connection to the open internet.
• --uncompiled will run integration tests using the uncompiled library instead of the compiled version.
• --random will run the tests in a random order to isolate test dependencies.
• --seed will seed the random test order so that the same order can be reproduced across runs. Specify any value --seed=xyz.
• --runs allows running the tests multiple times in succession. This parameter must be specified with a positive integer value, for example --runs 5.
• --use-xvfb will launch the browsers in a virtual display (only on Linux).
• --specFilter is used to filter a specific test or set of tests. This parameter is specified as a RegExp string --specFilter="DataUriPlugin .*\d".

The karma argument --browsers will set the browsers used to run the tests (e.g. --browsers Chrome,Firefox). If you don't pass any arguments, test.py will choose a defaults based on your platform. However, if you pass any arguments to test.py, it will not choose browsers and you must pass --browsers.

Stats

stats.py is used to print various stats about the compiled library. This is used internally to determine dependencies and to determine the size of the compiled library.

Before running the script, you have to compile it first. Then you need to pass either the name of the build (e.g. ui) or the path to the .map file. You will also need to pass some arguments to determine the output you want. You must pass exactly one of the following:

• -c or --class-deps will print dependencies between classes.
• -f or --function-deps will print dependencies between functions.
• -s or --function-sizes will print the compiled size of the functions.
• -t or --all-tokens will print all the tokens in the source map.

For --class-deps and --function-deps you can also output in DOT format. This format can be used to produce visual graphs of the dependencies. Passing in -d or --dot-format will output in DOT format. Then the output can be piped into another program to produce the output. For example using graphviz:

stats.py -c -d | fdb -Goverlap=prism | neato -n2 -Tsvg > out.svg