docs/chromoting_build_instructions.md

   1 # Chromoting Build Instructions
   2
   3 Chromoting, also known as
   4 [Chrome Remote Desktop](https://support.google.com/chrome/answer/1649523),
   5 allows one to remotely control a distant machine, all from within the Chromium
   6 browser. Its source code is located in the `remoting/` folder in the Chromium
   7 codebase. For the sake of brevity, we'll assume that you already have a
   8 pre-built copy of Chromium (or Chrome) installed on your development computer.
   9
  10 [TOC]
  11
  12 ## Obtain API keys
  13
  14 Before you can compile the code, you must obtain an API key to allow it to
  15 access the federated Chromoting API.
  16
  17 1.  Join the chromium-dev list, which can be found at
  18     https://groups.google.com/a/chromium.org/forum/#!forum/chromium-dev. (This
  19     step is required in order to gain access to the Chromoting API.)
  20 1.  Visit the Google APIs console at https://code.google.com/apis/console.
  21     1.  Use the `API Project` dropdown to create a new project with a name of
  22         your choice.
  23     1.  On the `Services` page, click the button to activate the
  24         `Chrome Remote Desktop API`, and accept the license agreements that
  25         appear.
  26     1.  On the `API Access` page, select the option to create an
  27         `OAuth2 client ID`, and supply a product name of your choice.
  28     1.  Choose the `Web application` type, then click more options.
  29     1.  Replace the contents of `Authorized Redirect URLs` with:
  30         `https://chromoting-oauth.talkgadget.google.com/talkgadget/oauth/chrome-remote-desktop/dev`
  31     1.  Clear the `Authorized JavaScript Origins` field and click the button to
  32         finish creating the client ID.
  33 1.  Create a file `~/.gyp/include.gypi` according to the following format:
  34
  35 ```
  36 {
  37   'variables': {
  38     'google_api_key': '<API key, listed under Simple API Access in the console>',
  39     'google_default_client_id': '<Client ID, listed under Client ID for web applications>',
  40     'google_default_client_secret': '<Client secret, listed under Client ID for web applications>',
  41   },
  42 }
  43 ```
  44
  45 (NB: Replace the text in angled braces according the the instructions between
  46 them.)
  47
  48 ## Obtain Chromium code
  49
  50 If you've already checked out a copy of the browser's codebase, you can skip
  51 this section, although you'll still need to run `gclient runhooks` to ensure you
  52 build using the API keys you just generated.
  53
  54 1.  Install the build dependencies, which are listed at
  55     http://code.google.com/p/chromium/wiki/LinuxBuildInstructionsPrerequisites.
  56 1.  Install the depot\_tools utilities, a process that is documented at
  57     http://dev.chromium.org/developers/how-tos/install-depot-tools.
  58 1.  Download the Chromium source code by running:
  59     `$ fetch chromium --nosvn=True`
  60
  61 ## Build and install the Linux host service
  62
  63 If you want to remote into a (Debian-based) GNU/Linux host, follow these steps
  64 to compile and install the host service on that system. As of the time of
  65 writing, you must compile from source because no official binary package is
  66 being distributed.
  67
  68 1.  Start in the `src/` directory that contains your checkout of the Chromium
  69     code.
  70 1.  Build the Chromoting host binaries:
  71
  72     ```shell
  73     $ ninja -C out/Release remoting_me2me_host remoting_start_host \
  74     remoting_native_messaging_host remoting_native_messaging_manifests
  75     ```
  76
  77 1.  When the build finishes, move into the installer directory:
  78     `$ cd remoting/host/installer/`
  79 1.  Generate a DEB package for your system's package manager:
  80     `$ linux/build-deb.sh`
  81 1.  Install the package on your system: `$ sudo dpkg -i *.deb`
  82 1.  The next time you use the Chromoting extension from your browser, it should
  83     detect the presence of the host service and offer you the option to
  84     `Enable remote connections`.
  85     1.  If the Web app doesn't properly detect the host process, you may need to
  86         create a symlink to help the plugin find the native messaging host:
  87         `$ sudo ln -s /etc/opt/chrome /etc/chromium`
  88
  89 (NB: If you compile the host service from source and expect to configure it
  90 using the browser extension, you must also compile the latter from source.
  91 Otherwise, the package signing keys will not match and the Web app's OAuth2
  92 token will not be valid within the host process.)
  93
  94 ## Build and install the browser extension
  95
  96 The Web app is the Chromoting system's main user interface, and allows you to
  97 connect to existing hosts as well as set up the host process on the machine
  98 you're currently sitting at.  Once built, it must be installed into your browser
  99 as an extension.
 100
 101 1.  Start in the `src/` directory that contains your checkout of the Chromium
 102     code.
 103 1.  Build the browser extension (Be sure to replace the substitutions denoted by
 104     angled braces.):
 105
 106     ```shell
 107     $ GOOGLE_API_KEY=<API key> GOOGLE_CLIENT_ID_REMOTING=<client ID> \
 108     GOOGLE_CLIENT_SECRET_REMOTING=<client secret> \
 109     ninja -C out/Release remoting_webapp
 110     ````
 111
 112 1.  Install the extension into your Chromium (or Chrome) browser:
 113     1.  Visit the settings page [chrome://extensions].
 114     1.  If it is unchecked, tick the `Developer mode` box.
 115     1.  Click `Load unpacked extension...`, then navigate to
 116         `out/Release/remoting/remoting.webapp/` within your code checkout.
 117     1.  Confirm the installation, open a new tab, and click the new app's
 118         Chromoting icon.
 119     1.  Complete the account authorization step, signing into your Google
 120         account if you weren't already.
 121
 122 ## Build and install the Android client
 123
 124 If you want to use your Android device to connect to your Chromoting hosts,
 125 follow these steps to install the client app on it. Note that this is in the
 126 very early stages of development. At the time of writing, you must compile from
 127 source because no official version is being distributed.
 128
 129 1.  Follow all the instructions under the `Getting the code` and
 130     `Install prerequisites` sections of: TODO: 404
 131     http://code.google.com/p/chromium/wiki/AndroidBuildInstructions
 132 1.  Move into the `src/` directory that contains your checkout of the Chromium
 133     code.
 134 1.  Build the Android app: `$ ninja -C out/Release remoting_apk`
 135 1.  Connect your device and set up USB debugging:
 136     1.  Plug your device in via USB.
 137     1.  Open the Settings app and look for the `Developer options` choice.
 138         1.  If there is no such entry, open `About phone`, tap `Build number`
 139             7 times, and look again.
 140     1.  Under `Developer options`, toggle the main switch to `ON` and enable
 141         `USB debugging`.
 142 1.  On your machine and still in the `src/` directory, run:
 143     `$ build/android/adb_install_apk.py --apk=out/Release/apks/Chromoting.apk`
 144 1.  If your Android device prompts you to accept the host's key, do so.
 145 1.  The app should now be listed as Chromoting in your app drawer.
 146
 147 See the [chromoting_android_hacking.md] guide for instructions on viewing the
 148 Android app's log and attaching a debugger.