From c3e44d6a8d69d8870b5bdc0d71ffe71891c97148 Mon Sep 17 00:00:00 2001 From: jmedley Date: Mon, 22 Sep 2014 13:22:23 -0700 Subject: Copy edit SDK section. BUG=none R= TEST=none NOTRY=true (documentation only change) Review URL: https://codereview.chromium.org/588723002 Cr-Commit-Position: refs/heads/master@{#296033} --- .../doc_generated/devguide/devcycle/running.html | 2 +- .../devguide/tutorial/tutorial-part2.html | 2 +- native_client_sdk/doc_generated/sdk/download.html | 127 +++++------ native_client_sdk/doc_generated/sdk/examples.html | 244 ++++++++++----------- native_client_sdk/doc_generated/sitemap.html | 6 +- 5 files changed, 178 insertions(+), 203 deletions(-) (limited to 'native_client_sdk/doc_generated') diff --git a/native_client_sdk/doc_generated/devguide/devcycle/running.html b/native_client_sdk/doc_generated/devguide/devcycle/running.html index ee8279a..0cae390 100644 --- a/native_client_sdk/doc_generated/devguide/devcycle/running.html +++ b/native_client_sdk/doc_generated/devguide/devcycle/running.html @@ -209,7 +209,7 @@ to run most applications under the examples directory where you sta server. For example, to run the flock example in the SDK, start the server and point your browser to http://localhost:5103/demo/flock/.

Some of the applications need special flags to Chrome, and must be run with the -make run command. See Run the SDK examples for more details.

+make run command. See Run the SDK examples for more details.

Chrome Web Store metadata

Applications published in the Chrome Web Store must be accompanied by CWS metadata; specifically, a Chrome Web Store manifest file named diff --git a/native_client_sdk/doc_generated/devguide/tutorial/tutorial-part2.html b/native_client_sdk/doc_generated/devguide/tutorial/tutorial-part2.html index 47dddbd..08a753b 100644 --- a/native_client_sdk/doc_generated/devguide/tutorial/tutorial-part2.html +++ b/native_client_sdk/doc_generated/devguide/tutorial/tutorial-part2.html @@ -37,7 +37,7 @@ application Con

Using the Native Client SDK build system makes it easy to build with all of the SDK toolchains, and switch between the Debug and Release configurations. It also simplifies the makefiles for your project, as we’ll see in the next -section. Finally, it adds some useful commands for running and debugging +section. Finally, it adds some useful commands for running and debugging your application.

The finished code for this example can be found in the pepper_$(VERSION)/getting_started/part2 directory in the Native Client SDK diff --git a/native_client_sdk/doc_generated/sdk/download.html b/native_client_sdk/doc_generated/sdk/download.html index 8a57dbc..d5b35ea 100644 --- a/native_client_sdk/doc_generated/sdk/download.html +++ b/native_client_sdk/doc_generated/sdk/download.html @@ -2,18 +2,16 @@

Download the Native Client SDK

-

To build Native Client modules, you must download and install the Native Client -Software Development Kit (SDK). This page provides an overview of the Native -Client SDK, and instructions for how to download and install the SDK.

+

This page provides an overview of the Native Client SDK, and instructions for +downloading and installing the SDK.

Overview

-

The Native Client SDK includes the following:

+

Overview

+

The Native Client SDK includes:

Follow the steps below to download and install the Native Client SDK.

-

Prerequisites

+

Prerequisites

+

Python 2.7

+

Make sure that the Python executable is in your PATH variable. Python 3.x is +not yet supported.

-

Installing bundles

+

Installing the stable bundle

  1. To see the SDK bundles that are available for download, go to the -nacl_sdk directory and run naclsdk with the “list” command. The -SDK includes a separate bundle for each version of Chrome/Pepper.

    +nacl_sdk directory and run naclsdk with the list command. The SDK +includes a separate bundle for each version of Chrome/Pepper.

    On Mac/Linux:

     $ cd nacl_sdk
@@ -114,16 +110,18 @@ Bundles:

    The sample output above shows that several bundles are available for download, and that you have already installed the latest revision of the -sdk_tools bundle. (It was included in the zip file you downloaded.) Each -bundle is labeled post-stable, stable, beta, dev, or canary. These labels -usually correspond to the current versions of Chrome.

    -

    We recommend that you download and use a “stable” bundle, because -applications developed with “stable” bundles can be used by all current -Chrome users. This is because Native Client is designed to be -backward-compatible (for example, applications developed with the -pepper_31 bundle can run in Chrome 31, Chrome 32, etc.).

    +sdk_tools bundle, which was included in the zip file. You never need to +update the sdk_tools bundle. It is updated automatically (if necessary) +whenever you run naclsdk.

    +

    Bundles are labeled post-stable, stable, beta, dev, or canary. These labels +usually correspond to the current versions of Chrome. We recommend that you +develop against a “stable” bundle, because such bundles can be used by all +current Chrome users. Native Client is designed to be backward-compatible.For +example, applications developed with the pepper_31 bundle can run in +Chrome 31, Chrome 32, etc..

    2. -

  2. Run naclsdk with the “update” command to download recommended bundles.

    +

  3. Run naclsdk with the update command to download recommended bundles, +including the current “stable” bundle.

    On Mac/Linux:

     $ ./naclsdk update
@@ -132,25 +130,18 @@ $ ./naclsdk update
 
     > naclsdk update
 
    
-
    By default, naclsdk only downloads bundles that are recommended—
-generally those that are “stable.” Continuing with the earlier example, the
-“update” command would only download the pepper_35 bundle, since the
-bundles pepper_36 and greater are not yet stable. If you want the
-pepper_36 bundle, you must ask for it explicitly:
    
+
    By default, naclsdk only downloads bundles that are recommended,
+generally those that are “stable.” For example, if the current “stable”
+bundle is pepper_35, then the update downloads that bundle. To
+download the pepper_36 bundle you must ask for it explicitly:
    
 
     $ ./naclsdk update pepper_36
- -

Updating bundles

+

Updating bundles

    -

  1. Run naclsdk with the “list” command. This shows you the list of available +

  2. Run naclsdk with the list command. This shows you the list of available bundles and verifies which bundles you have installed.

    On Mac/Linux:

    @@ -160,7 +151,8 @@ $ ./naclsdk list
 
     > naclsdk list
 
    
-
    If an update is available, you’ll see something like this.:
    
+
    An asterisk (*) next to a bundle indicates that there is an update available
+it. For example:
    
 
     Bundles:
  I: installed
@@ -178,8 +170,7 @@ Bundles:
      pepper_canary (canary)
      bionic_canary (canary)
 
    
-
    An asterisk next to a bundle indicates that there is an update available it.
-If you run “naclsdk update” now, it warns you with a message similar to
+
    If you run naclsdk update now, it warns you with a message similar to
 this:
    
 
     WARNING: pepper_35 already exists, but has an update available. Run update
@@ -198,7 +189,7 @@ $ ./naclsdk update --force
-

Help with the naclsdk utility

+

Help with the naclsdk utility

  1. For more information about the naclsdk utility, run:

    On Mac/Linux:

    @@ -211,14 +202,14 @@ $ ./naclsdk help
-

Next steps:

+

Next steps

diff --git a/native_client_sdk/doc_generated/sdk/examples.html b/native_client_sdk/doc_generated/sdk/examples.html index aa93928..306031f 100644 --- a/native_client_sdk/doc_generated/sdk/examples.html +++ b/native_client_sdk/doc_generated/sdk/examples.html @@ -1,22 +1,19 @@ {{+bindTo:partials.standard_nacl_article}} -
-

Running the SDK Examples

+
+

Examples

Every Native Client SDK bundle comes with a folder of example applications. Each example demonstrates one or two key Native Client programming concepts. After you’ve downloaded the SDK, follow the instructions on this page to build and run the examples.

Your version of Chrome must be equal to or greater than the version of your SDK -bundle. For example, if you’re developing with the pepper_31 bundle, you -must use Google Chrome version 31 or greater. To find out what version of Chrome +bundle. For example, if you’re developing with the pepper_35 bundle, you +must use Google Chrome version 35 or greater. To find out what version of Chrome you’re using, type about:chrome or about:version in the Chrome address bar.

-

Enable Native Client

- -

To run Portable Native Client applications you must specifically enable Native -Client in Chrome:

+

Enable Native Client

+

If you are using Chrome 31 or later, you can skip this section. To run Portable +Native Client applications you must specifically enable Native Client in Chrome:

  1. Type about:flags in the Chrome address bar and scroll down to “Native Client”.

    @@ -35,107 +32,85 @@ link.

    windows will restart when you relaunch Chrome.

-

Disable the Chrome cache

-

Chrome caches resources aggressively. When you are building a Native Client -application you should disable the cache to make sure that Chrome loads the -latest version.

-
    -
  1. Open Chrome’s developer tools by clicking the menu icon menu-icon and -choosing Tools > Developer tools.
    2. -
  2. Click the gear icon gear-icon in the bottom right corner of the Chrome -window.
    3. -
  3. Under the “General” settings, check the box next to “Disable cache”.
    4. -
-

Build the SDK examples

-

The Makefile scripts for the SDK examples build multiple versions of the -examples using all three SDK toolchains (newlib, glibc, and PNaCl) and in both -release and debug configurations. (Note that some examples build only with -particular toolchains).

-

Build all examples

-

To build all the examples, go to the examples directory in a specific SDK -bundle and run make:

+

Build the SDK examples

+

The Makefile scripts for the SDK examples can build multiple versions of the +examples using any of the three SDK toolchains (newlib, glibc, and PNaCl) and in +both release and debug configurations. Note that some examples, dlopen for +example, build only with particular toolchains.

+

Find the toolchains for each example by looking at the VALID_TOOLCHAINS +variable in the Makefile for a particular example. The first item listed is the +default. It’s built when you run an example make file without parameters. for +example running make in the core directory of pepper_35 builds the example +using the newlib toolchain.

-$ cd pepper_31/examples
+$ cd pepper_35/examples/api/core
 $ make
-make -C api  all
-make[1]: Entering directory `pepper_31/examples/api'
-make -C audio  all
-make[2]: Entering directory `pepper_31/examples/api/audio'
-  CXX  newlib/Debug/audio_x86_32.o
-  LINK newlib/Debug/audio_x86_32.nexe
-  CXX  newlib/Debug/audio_x86_64.o
-  LINK newlib/Debug/audio_x86_64.nexe
-  CXX  newlib/Debug/audio_arm.o
-  LINK newlib/Debug/audio_arm.nexe
-  CREATE_NMF newlib/Debug/audio.nmf
-make[2]: Leaving directory `pepper_31/examples/api/audio'
-make -C url_loader  all
-make[2]: Entering directory `pepper_31/examples/api/url_loader'
-  CXX  newlib/Debug/url_loader_x86_32.o
-...
+  CXX  newlib/Release/core_x86_32.o
+  LINK newlib/Release/core_unstripped_x86_32.nexe
+  VALIDATE newlib/Release/core_unstripped_x86_32.nexe
+  CXX  newlib/Release/core_x86_64.o
+  LINK newlib/Release/core_unstripped_x86_64.nexe
+  VALIDATE newlib/Release/core_unstripped_x86_64.nexe
+  CXX  newlib/Release/core_arm.o
+  LINK newlib/Release/core_unstripped_arm.nexe
+  VALIDATE newlib/Release/core_unstripped_arm.nexe
+  STRIP newlib/Release/core_x86_32.nexe
+  STRIP newlib/Release/core_x86_64.nexe
+  STRIP newlib/Release/core_arm.nexe
+  CREATE_NMF newlib/Release/core.nmf
-

Build a single example

-

Calling make from inside a particular example’s directory will build only -that example:

+

As you can see, this produces a number of architecture specific nexe files in +the pepper_35/examples/api/core/Release directory. Create debug versions by +using the CONFIG parameter of the make command.

-$ cd pepper_31/examples/api/core
-$ make
-  CXX  newlib/Debug/core_x86_32.o
-  LINK newlib/Debug/core_x86_32.nexe
-  CXX  newlib/Debug/core_x86_64.o
-  LINK newlib/Debug/core_x86_64.nexe
-  CXX  newlib/Debug/core_arm.o
-  LINK newlib/Debug/core_arm.nexe
-  CREATE_NMF newlib/Debug/core.nmf
+$make CONFIG=Debug
-

Override defaults

-

You can call make with the TOOLCHAIN and CONFIG parameters to -override the defaults:

+

This creates similar output, but in pepper_35/examples/api/core/Debug.

+

Select a different toolchain with the TOOLCHAIN parameter. For example:

+$ cd pepper_35/examples/api/core
 $ make TOOLCHAIN=pnacl CONFIG=Release
-  CXX  pnacl/Release/core_pnacl.o
-  LINK pnacl/Release/core.bc
-  FINALIZE pnacl/Release/core.pexe
+  CXX  pnacl/Release/core.o
+  LINK pnacl/Release/core_unstripped.bc
+  FINALIZE pnacl/Release/core_unstripped.pexe
   CREATE_NMF pnacl/Release/core.nmf
-

You can also set TOOLCHAIN to “all” to build one or more examples with -all available toolchains:

+

You can also set TOOLCHAIN to all to build all Release versions with +default toolchains.

+$ cd pepper_35/examples/api/core
 $ make TOOLCHAIN=all
 make TOOLCHAIN=newlib
-make[1]: Entering directory `pepper_31/examples/api/core'
-  CXX  newlib/Debug/core_x86_32.o
-  LINK newlib/Debug/core_x86_32.nexe
-  CXX  newlib/Debug/core_x86_64.o
-  LINK newlib/Debug/core_x86_64.nexe
-  CXX  newlib/Debug/core_arm.o
-  LINK newlib/Debug/core_arm.nexe
-  CREATE_NMF newlib/Debug/core.nmf
-make[1]: Leaving directory `pepper_31/examples/api/core'
+make[1]: Entering directory 'pepper_35/examples/api/core'
+  CXX  newlib/Release/core_x86_32.o
+  LINK newlib/Release/core_unstripped_x86_32.nexe
+  VALIDATE newlib/Release/core_unstripped_x86_32.nexe
+  CXX  newlib/Release/core_x86_64.o
+  LINK newlib/Release/core_unstripped_x86_64.nexe
+  VALIDATE newlib/Release/core_unstripped_x86_64.nexe
+  CXX  newlib/Release/core_arm.o
+  LINK newlib/Release/core_unstripped_arm.nexe
+  VALIDATE newlib/Release/core_unstripped_arm.nexe
+  STRIP newlib/Release/core_x86_32.nexe
+  STRIP newlib/Release/core_x86_64.nexe
+  STRIP newlib/Release/core_arm.nexe
+  CREATE_NMF newlib/Release/core.nmf
+make[1]: Leaving directory 'pepper_35/examples/api/core'
 make TOOLCHAIN=glibc
-make[1]: Entering directory `pepper_31/examples/api/core'
-  CXX  glibc/Debug/core_x86_32.o
-  LINK glibc/Debug/core_x86_32.nexe
-  CXX  glibc/Debug/core_x86_64.o
-  LINK glibc/Debug/core_x86_64.nexe
-  CREATE_NMF glibc/Debug/core.nmf
-make[1]: Leaving directory `pepper_31/examples/api/core'
-make TOOLCHAIN=pnacl
-make[1]: Entering directory `pepper_31/examples/api/core'
-  CXX  pnacl/Debug/core.o
-  LINK pnacl/Debug/core_unstripped.bc
-  FINALIZE pnacl/Debug/core_unstripped.pexe
-  CREATE_NMF pnacl/Debug/core.nmf
-make[1]: Leaving directory `pepper_31/examples/api/core'
-make TOOLCHAIN=linux
-make[1]: Entering directory `pepper_31/examples/api/core'
-  CXX  linux/Debug/core.o
-  LINK linux/Debug/core.so
-make[1]: Leaving directory `pepper_31/examples/api/core'
+make[1]: Entering directory 'pepper_35/examples/api/core'
+  CXX  glibc/Release/core_x86_32.o
+  LINK glibc/Release/core_unstripped_x86_32.nexe
+  VALIDATE glibc/Release/core_unstripped_x86_32.nexe
+  CXX  glibc/Release/core_x86_64.o
+  LINK glibc/Release/core_unstripped_x86_64.nexe
+  VALIDATE glibc/Release/core_unstripped_x86_64.nexe
+  ...
+  (content excerpted)
+  ...
-

Build results

-

After running make, each example directory will contain one or more of -the following subdirectories:

+

Build results

+

After running make, example directories will contain one or more of the +following subdirectories, depending on which Makefile you run:

  • newlib with subdirectories Debug and Release;
  • glibc with subdirectories Debug and Release;
    • @@ -150,23 +125,36 @@ For information about Native Client manifest files, see the GNU ‘make’ Manual. For details on how to use the SDK toolchain itself, see Building Native Client Modules.

    -

    Run the SDK examples

    -

    To run the SDK examples, you can use the make run command:

    +

    Run the SDK examples

    +

    Disable the Chrome cache

    +

    Chrome’s intelligent caching caches resources aggressively. When building a +Native Client application you should disable the cache to make sure that Chrome +loads the latest version. Intelligent caching only remains inactive while +Developer Tools are open. Otherwise, agressive caching continues.

    +
      +
    1. Open Chrome’s developer tools by clicking the menu icon menu-icon and +choosing Tools > Developer tools.
      2. +
    2. Click the gear icon gear-icon in the bottom right corner of the Chrome +window.
      3. +
    3. Under the “General” settings, check the box next to “Disable cache”.
      4. +
    +

    Run the examples

    +

    To run the SDK examples, use the make run command:

    -$ cd pepper_31/examples/api/core
+$ cd pepper_35/examples/api/core
 $ make run
    -

    This will launch a local HTTP server which will serve the data for the -example. It then launches Chrome with the address of this server, usually -http://localhost:5103. After you close Chrome, the local HTTP server is -automatically shutdown.

    -

    This command will try to find an executable named google-chrome in your +

    This launches a local HTTP server that serves the example. It then launches +Chrome with the address of this server, usually http://localhost:5103. +After you close Chrome, the local HTTP server automatically shuts down.

    +

    This command tries to find an executable named google-chrome in your PATH environment variable. If it can’t, you’ll get an error message like this:

    -pepper_31/tools/common.mk:415: No valid Chrome found at CHROME_PATH=
-pepper_31/tools/common.mk:415: *** Set CHROME_PATH via an environment variable, or command-line..  Stop.
+pepper_35/tools/common.mk:415: No valid Chrome found at CHROME_PATH=
+pepper_35/tools/common.mk:415: *** Set CHROME_PATH via an environment variable, or command-line..  Stop.
    +

    Add an environment variable for Chrome

    Set the CHROME_PATH environment variable to the location of your Chrome executable.

      @@ -175,7 +163,7 @@ executable.

      C:\Program Files (x86)\Google\Chrome\Application\chrome.exe for Chrome stable and C:\Users\<username>\AppData\Local\Google\Chrome SxS\Application\chrome.exe -for Chrome Canary; try looking in those directories first:

      +for Chrome Canary. Try looking in those directories first:

       > set CHROME_PATH=<Path to chrome.exe>
      @@ -197,39 +185,36 @@ $ export CHROME_PATH=<Path to Google Chrome>
    -

    You can run via a different toolchain or configuration by using the -TOOLCHAIN and CONFIG parameters to make:

    -
    -$ make run TOOLCHAIN=pnacl CONFIG=Debug
-

    Run the SDK examples as packaged apps

    -

    Each example can also be launched as a packaged app. For more information about -using Native Client for packaged apps, see Packaged application. For general information about packaged apps, see the -Chrome apps documentation.

    +

    Each example can also be launched as a packaged application. A packaged +application is a special zip file (with a .crx extension) hosted in the Chrome +Web Store. This file contains all of the application parts: A Chrome Web Store +manifest file (manifest.json), an icon, and all of the regular Native Client +application files. Refer to What are Chrome Apps for more +information about creating a packaged application.

    Some Pepper features, such as TCP/UDP socket access, are only allowed in -packaged apps. The examples that use these features must be run as packaged -apps, by using the make run_package command:

    +packaged applications. The examples that use these features must be run as +packaged applications, by using the following command:

     $ make run_package
    -

    You can use TOOLCHAIN and CONFIG parameters as above to run with a -different toolchain or configuration.

    -

    Debugging the SDK examples

    +

    You can use TOOLCHAIN and CONFIG parameters as described above to run +with a different toolchain or configuration.

    +

    Debugging the SDK examples

    The NaCl SDK uses GDB to debug Native Client code. The SDK includes a prebuilt version of GDB that is compatible with NaCl code. To use it, run the make debug command from an example directory:

     $ make debug
    -

    This will launch Chrome with the --enable-nacl-debug flag set. This flag -will cause Chrome to pause when a NaCl module is first loaded, waiting for a -connection from gdb. The make debug command also simultaneously launches -GDB and loads the symbols for that NEXE. To connect GDB to Chrome, in the GDB -console, type:

    +

    This launches Chrome with the --enable-nacl-debug flag set. This flag causes +Chrome to pause when a NaCl module is first loaded, waiting for a connection +from gdb. The make debug command also simultaneously launches GDB and loads +the symbols for that NEXE. To connect GDB to Chrome, in the GDB console, type:

     (gdb) target remote :4014
    -

    This tells GDB to connect to a TCP port on localhost:4014–the port that +

    This tells GDB to connect to a TCP port on localhost:4014, the port that Chrome is listening on. GDB will respond:

     Remote debugging using :4014
@@ -237,8 +222,9 @@ Remote debugging using :4014

    At this point, you can use the standard GDB commands to debug your NaCl module. The most common commands you will use to debug are continue, step, -next, break and backtrace. See Debugging for more information about debugging a Native Client -application.

    +next, break and backtrace. See +Debugging for more information about +debugging a Native Client application.

{{/partials.standard_nacl_article}} diff --git a/native_client_sdk/doc_generated/sitemap.html b/native_client_sdk/doc_generated/sitemap.html index b47fd60..9628579 100644 --- a/native_client_sdk/doc_generated/sitemap.html +++ b/native_client_sdk/doc_generated/sitemap.html @@ -28,16 +28,14 @@
  • Overview
  • Prerequisites
  • Installing the SDK
    • -
  • Installing bundles
  • Updating bundles
  • Help with the naclsdk utility
    • +
  • Next steps
    • -
  • Running the SDK Examples