shaka-player/tutorials/dev.html

<!--
 Copyright 2014 Google Inc.

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<h3 class="tutorial-heading">
Quick Setup (TL;DR)
</h3>

<p>
To get started quickly, just run ./build/all.sh and skip this document.
</p>


<h3 class="tutorial-heading">
Checking Out a Specific Release
</h3>

<p>
You can check out a specific release version after cloning the repository. Just
use "git checkout" followed by a release, such as "git checkout v1.2.0".
</p>


<h3 class="tutorial-heading">
Closure, Annotations, and the Build Process
</h3>

<p>
The Shaka Player library was designed to be compiled with Google's open-sourced
JavaScript compiler, {@link http://goo.gl/HZfHi Closure}.  The Closure compiler
produces JavaScript code which is minified, optimized, obfuscated, and stripped
of dead code.  Deploying a Closure-compiled JavaScript library saves bandwidth,
and the browser can also load and parse the code faster.
</p>

<p>
Closure also enforces structure and type-safety on the JavaScript language.  It
allows developers to annotate code with type information.  The compiler can use
this information to optimize the code, but it also helps catch bugs early, such
as missing arguments, arguments of the wrong type, typos in names, etc.
</p>

<p>
The annotation syntax is derived from {@link http://usejsdoc.org/ JSDoc}.  This
means that the annotated code is also self-documenting.  We generate docs based
on these annotations using JSDoc.  For information on annotation syntax, please
refer to {@link http://goo.gl/xxHG2W Annotating JavaScript} on Closure's site.
</p>

<p>
The Closure compiler and JSDoc are both included in the source.  To compile the
Shaka Player library, simply run ./build/all.sh from the source root.  Compiled
JavaScript will be output to shaka-player.compiled.js in the source root.
</p>

<p>
To generate documentation, run ./build/docs.sh from the source root.  Docs will
be output to ./docs/api/ in HTML format.
</p>


<h3 class="tutorial-heading">
The Test App
</h3>

<p>
The project includes a test application which we used for manual testing during
development.  The test app is made up of index.html, index.css, and app.js, and
can be accessed by pointing a web server at your source code checkout.
</p>

<p>
Many of the settings in the test app can be controlled with URL parameters such
that the page can be reloaded without the need to manually change settings.  To
see a canonical list of URL parameters, see app.js.
</p>

<p>
Some parameters require a value, but most are boolean.  The behavior of boolean
parameters is activated by presence.  Parameters are separated by semicolons.

<ul>
  <li>lang=LANG - Changes the language preference fed to the library.  Language
      settings use language tags from {@link http://goo.gl/J6yQvS BCP 47}, such
      as "en", "en-US', "fr-CA", "el", "deu-AT", etc.</li>
  <li>nocenc - Select the non-encrypted version of the default sample.</li>
  <li>vp9 - Select a VP9 DASH sample.</li>
  <li>dash - Auto-play the selected DASH stream.</li>
  <li>compiled - Load the library in compiled mode.  See "Loader" below.</li>
  <li>debug - Set the log level to show debug messages.</li>
  <li>v - Set the log level to show debug and verbose messages.</li>
</ul>
</p>

<p>
Example URLs for the test app:
<ul>
  <li>https://localhost/shaka/?nocenc
    <ul><li>Defaults the UI to a non-encrypted sample.</li></ul>
  </li>
  <li>https://localhost/shaka/?dash;vp9
    <ul><li>Selects the VP9 sample and auto-plays it.</li></ul>
  </li>
  <li>https://localhost/shaka/?dash;lang=fr
    <ul><li>Sets the language to French and auto-plays.</li></ul>
  </li>
  <li>https://localhost/shaka/?compiled;dash
    <ul><li>Auto-plays the default sample in compiled mode.</li></ul>
  </li>
</ul>
</p>


<h3 class="tutorial-heading">
The Loader
</h3>

<p>
The Shaka Player library can be used without compiling it.  This is useful when
making changes, since it shortens the testing cycle for the developer.  But the
library will be deployed in a compiled form, so it is critical to test a change
using the compiled library once it has been vetted uncompiled.
</p>

<p>
To make it easier to switch between compiled and uncompiled mode during testing
and development, load.js acts as a shim between index.html and the library.  It
will select which version of the library to load based on the boolean parameter
"compiled".  (See "Test App" above for info on parameters.)
</p>

<p>
At any time during development or testing, you can switch modes by changing the
URL. Once the application has loaded, you cannot change modes without reloading
the page.  A production application would directly include the compiled library
instead of using this loader.
</p>

<p>
Remember, when running in compiled mode, you must recompile the library after a
change by running ./build/all.sh.
</p>


<h3 class="tutorial-heading">
Tests
</h3>

<p>
Tests live in the "spec" folder and are run by unit_tests.html and
integration_tests.html.  To run tests, just point your browser at one of these
HTML files.  Do not do this using a file:// URL, but through a local web server.
</p>

<p>
You can also use karma to run the tests.  These node packages are recommended
to use karma:

<ul>
  <li>karma
  <li>karma-jasmine
  <li>karma-jasmine-ajax
  <li>karma-chrome-launcher
  <li>jasmine
  <li>jasmine-ajax
  <li>jasmine-core
</ul>

Then run: karma start --single-run --browsers Chrome
</p>


<h3 class="tutorial-heading">
Source Code Layout
</h3>

<p>
<ul>
  <li>assets/ - assets for smoke-testing basic functionality</li>
  <li>build/ - build scripts
    <ul>
      <li>build.sh - compiles the library and generates
          shaka-player.compiled.js</li>
      <li>gendeps.sh - computes dependencies for running non-compiled code</li>
      <li>lint.sh - checks the code for style issues</li>
      <li>all.sh - combination of gendeps.sh, build.sh, and lint.sh</li>
      <li>docs.sh - generate documentation</li>
    </ul>
  </li>
  <li>docs/ - documentation
    <ul>
      <li>api/ - generated documentation</li>
      <li>reference/ - reference documents</li>
    </ul>
  </li>
  <li>externs/ - definitions of external APIs, used by the compiler</li>
  <li>lib/ - the Shaka Player Library source, organized by namespace
    <ul>
      <li>dash/ - DASH-related classes (internal)</li>
      <li>debug/ - debug-related classes (internal)</li>
      <li>media/ - generic media-related and MSE-related classes (internal)</li>
      <li>player/ - all classes that an integrator must interact with</li>
      <li>polyfill/ - all {@tutorial polyfills}</li>
      <li>util/ - utility classes (internal)</li>
    </ul>
  </li>
  <li>spec/ - unit and integration tests</li>
  <li>spec_runner.html - front-end to run unit and integration tests</li>
  <li>support.html - browser API support test</li>
  <li>third_party/ - third_party dependencies
    <ul>
      <li>SUMMARY.txt - summary of all libraries and their licenses</li>
      <li>blanket_jasmine/ - Blanket JS coverage library</li>
      <li>closure/ - Closure JS compiler and JS library</li>
      <li>jasmine/ - Jasmine JS testing framework</li>
      <li>jsdoc/ - JS documentation generator</li>
    </ul>
  </li>
  <li>tutorials/ - source code for these tutorials</li>

  <br>

  <li>app.js - manual testing/sample application (JS)</li>
  <li>index.html - manual testing/sample application (HTML)</li>
  <li>index.css - manual testing/sample application (CSS)</li>
  <li>load.js - library loader (for testing/bootstrapping)</li>

  <br>

  <li>jsdoc.conf.json - configuration for generating documentation</li>
  <li>shaka-player.compiled.js - compiler output (suitable for deployment)</li>
  <li>shaka-player.compiled.debug.js - compiler output (with debugging enabled
      via source map)</li>
  <li>shaka-player.compiled.debug.map - compiler output
      ({@link http://goo.gl/5xQEy source map})</li>
  <li>shaka-player.uncompiled.js - requires all exported classes in uncompiled
      mode</li>
</ul>
</p>