Recommend the use of the debug library

Instead of using the uncompiled library, which some app developers have been confused about, recommend the use of the much simpler debug library, which offers many of the same advantages. Thanks to @jpmedley for pointing out the complexities of using the uncompiled build. Change-Id: I771a2b5a98152a67807629538d8537721177399f
shaka-project · Feb 28, 2018 · 2d0b300 · 2d0b300
1 parent def3d57
commit 2d0b300
Showing 1 changed file with 55 additions and 27 deletions.
diff --git a/docs/tutorials/debugging.md b/docs/tutorials/debugging.md
@@ -29,40 +29,29 @@ that `1001` means `BAD_HTTP_STATUS`:
 So some HTTP request failed, and we can see the failed URI in `data[0]`.
 
 
-#### Loading the uncompiled library
+#### Loading the debug library
 
 The compiled library has no usable stack traces and no logging.  So to get more
-information, we need to switch to the uncompiled library.
+information, we need to switch to the debug library.  The debug library is still
+compiled into a single bundle, but logging and other debug features are enabled.
 
-Instead of the single-file compiled library, we need to load three scripts in
-our HTML file:
-
-1. Closure's base library.  (This is a small JavaScript library related to the
-   Closure compiler used when we build Shaka.)  This is what loads Shaka without
-   requiring you to list all 50+ source files.
-2. A dependency file which maps Shaka's class names to source files.  This is
-   how Closure's base library can locate all of Shaka's individual source files.
-3. The uncompiled Shaka library's bootstrap file, "shaka-player.uncompiled.js".
-   This uses Closure to load the top-level parts of the library.  Each of those
-   files in turn load their internal dependencies.
-
-Once we're using the uncompiled library, we will be able to see detailed logs
-and line numbers for errors.
+To load the debug version of the library instead of the compiled version, just
+change "compiled.js" to "compiled.debug.js" in our HTML file:
 
 ```html
   <head>
-    <!-- Closure base: -->
-    <script src="third_party/closure/goog/base.js"></script>
-    <!-- Deps file: -->
-    <script src="dist/deps.js"></script>
-    <!-- Shaka Player uncompiled library: -->
-    <script src="shaka-player.uncompiled.js"></script>
+    <!-- Shaka Player debug library: -->
+    <script src="shaka-player.compiled.debug.js"></script>
 
     <!-- Your application source: -->
     <script src="myapp.js"></script>
   </head>
 ```
 
+Once we're using the debug library, we will be able to see detailed logs and
+line numbers for errors.
+
+
 Reload the page and look in the JavaScript console.  Now we see something
 similar to this (formatted a bit differently in the console):
 
@@ -95,8 +84,8 @@ shaka.util.Error
     at XMLHttpRequest.xhr.onload (http://localhost/shaka/lib/net/http_plugin.js:70:16)"
 ```
 
-With the information from the uncompiled library, we have the error name as well
-as the code.  So we could avoid looking up the number in the documentation.  The
+With the information from the debug library, we have the error name as well as
+the code.  So we could avoid looking up the number in the documentation.  The
 stack trace gives us clues about where the error was generated, so we can look
 more closely at the source code if we need to.
 
@@ -108,8 +97,8 @@ long sequence of events leading up to an error.  You may also be asked to attach
 logs as part of a bug report to help the Shaka Player team understand your bug.
 
 For this, you want to set the log level.  The log level lets you control what
-logs are shown by the uncompiled library.  To set the log level, add one of
-these to the top of `initApp()` in myapp.js:
+logs are shown by the debug library.  To set the log level, add one of these to
+the top of `initApp()` in myapp.js:
 
 ```js
 // Debug logs, when the default of INFO isn't enough:
@@ -151,11 +140,50 @@ So much more information!  We can now see that the failed HEAD request caused
 load() to fail.
 
 
+#### Advanced: Loading the uncompiled library
+
+To do rapid testing and development, you can also load the uncompiled library.
+This allows you to edit files and just hit the "reload" button in the browser
+to see changes immediately.  This approach is trickier than using the debug
+library, because the entire source tree needs to be available to your web
+server, and because the individual sources can't be moved relative to the files
+in `dist/`.
+
+Instead of the single-file compiled library, we need to load three scripts in
+our HTML file:
+
+1. Closure's base library.  (This is a small JavaScript library related to the
+   Closure compiler used when we build Shaka.)  This is what loads Shaka without
+   requiring you to list all 50+ source files.
+2. A dependency file which maps Shaka's class names to source files.  This is
+   how Closure's base library can locate all of Shaka's individual source files.
+3. The uncompiled Shaka library's bootstrap file, "shaka-player.uncompiled.js".
+   This uses Closure to load the top-level parts of the library.  Each of those
+   files in turn load their internal dependencies.
+
+Once we're using the uncompiled library, we will be able to reload quickly
+without rebuilding.
+
+```html
+  <head>
+    <!-- Closure base: -->
+    <script src="third_party/closure/goog/base.js"></script>
+    <!-- Deps file: -->
+    <script src="dist/deps.js"></script>
+    <!-- Shaka Player uncompiled library: -->
+    <script src="shaka-player.uncompiled.js"></script>
+
+    <!-- Your application source: -->
+    <script src="myapp.js"></script>
+  </head>
+```
+
+
 #### Wrap up
 
 To sum up, remember these points when debugging your application:
 
- - Use the uncompiled version of Shaka Player for debugging and integration work
+ - Use the debug version of Shaka Player for debugging and integration work
  - Refer to the docs for error codes
  - Increase the log level when you need more detail