| |
| |
| .--~~~~~~~~~~~~~------. |
| /--===============------\ |
| | |```````````````| | |
| | | | | |
| | | >_< | | |
| | | | | |
| | |_______________| | |
| | ::::| |
| '=======================' |
| //-"-"-"-"-"-"-"-"-"-"-\\ |
| //_"_"_"_"_"_"_"_"_"_"_"_\\ |
| [-------------------------] |
| \_________________________/ |
| |
| |
| |
| hterm and Secure Shell |
| Developer Guide |
| |
| April 23, 2012 |
| |
| |
| This developer guide explains how to edit, test and debug the hterm, Secure |
| Shell and Native Client ssh wrapper source code. |
| |
| 1. The Source Repository |
| |
| The source is publicly available under a BSD-style license documented here: |
| <http://src.chromium.org/viewvc/chrome/trunk/src/LICENSE?view=markup>. |
| |
| The source code itself is in the Chromium OS "assets" repository, located |
| on chromium.googlesource.com. (The Secure Shell application works on recent |
| Chromium based browsers on Windows, Mac and Linux platforms too. The source |
| just happens to live in a Chromium OS repository.) |
| |
| There are two important directories. The first is assets/chromeapps/hterm/ |
| (gitweb: <http://goo.gl/EqrV0>). This directory contains the hterm |
| terminal emulator and the Secure Shell front end code. This code is |
| entirely JavaScript, HTML and CSS. |
| |
| Any JavaScript code that lives off the "hterm.NaSSH" object can be |
| considered part of the Secure Shell front end. Everything else is hterm. |
| |
| The second important directory is /assets/chromeapps/ssh_client/ |
| (gitweb: <http://goo.gl/760JC>). This contains Native Client wrapper |
| around ssh. It is written in C and C++. |
| |
| |
| 2. Syncing the Source Repository |
| |
| If you have Secure Shell installed, you already have most of the source. |
| You can probably just search your local disk for "terminal.js" to find out |
| where Chrome has stored it. |
| |
| That's OK for making small changes, or for playing around a bit. If you |
| want to be able to track your changes (which you'll need to do if you want |
| to propose patches) you'll need to fetch the source with `git`. |
| |
| If you don't know what git is or how to use it, you'll want to find out |
| before continuing. Explaining git is well beyond the scope of this |
| document. |
| |
| There are three ways to get the source with git, described below. |
| |
| 2.1 Using git only |
| |
| The first option is to use the "git clone" command as shown at the bottom |
| of the gitweb page. It goes like this... |
| |
| $ mkdir chromiumos |
| $ cd chromiumos |
| $ git clone https://chromium.googlesource.com/chromiumos/platform/assets.git |
| |
| That's it. Look under the chromeapps/ directory for the nassh/, hterm/ |
| and ssh_client/ directories. Make your changes, use `git diff` to produce |
| a patch, and send it off to the chromium-hterm mailing list. |
| |
| 2.2 Using repo and git |
| |
| Alternately, you can use the `repo` front end. This has the advantage |
| of being able to upload patches to the Gerrit review server. This makes |
| it easy for someone to review and comment on your change. Once it's |
| reviewed, it's also easy to use Gerrit to commit the change. If you |
| have the time to set up repo, this is the preferred way to submit patches. |
| |
| The repo command comes with the Chromium "depot_tools" package. See |
| this document for details on how to install it: |
| <http://www.chromium.org/developers/how-tos/install-depot-tools>. |
| |
| Once you have repo installed, you can use it to check out a local |
| copy of the hterm source... |
| |
| $ mkdir chromiumos |
| $ cd chromiumos |
| $ repo init -u https://chromium.googlesource.com/chromiumos/manifest.git |
| $ repo sync chromiumos/repohooks |
| $ repo sync chromiumos/platform/assets |
| |
| You'll end up with the relevant directories in |
| src/platform/assets/chromeapps. |
| |
| Before you start working, you should use repo to create a branch. That |
| goes like this... |
| |
| $ cd src/platform/assets/chromeapps/ |
| $ repo start mybranch . |
| |
| Feel free to replace "mybranch" with something more descriptive. Repo |
| makes it easy to re-use the branch for the next set of changes. It's |
| OK to just call the branch "hterm", and keep it around for a long time. |
| |
| 2.3 From a full Chromium OS checkout |
| |
| This is really just a special case of 2.2. If you're already set up to |
| work on Chromium OS, just `cros_workon start assets` to add the |
| source to your checkout. Then continue to use `repo` as you would |
| elsewhere. |
| |
| 2.4 Keeping up to date |
| |
| To sync with the latest version of the source, use... |
| |
| $ repo sync |
| $ git rebase cros/master |
| |
| And that's pretty much the life cycle. It's important to know that repo |
| will consider each local git commit as separate change-list to be reviewed. |
| Before uploading your change, make sure to squash multiple commits into one |
| (if you have multiple commits for a single review) or commit each part of |
| the change using the --amend option. |
| |
| 2.5 Submitting patches |
| |
| Once you've got something to post for review commit it locally with... |
| |
| $ git commit |
| |
| And then upload it using... |
| |
| $ repo upload |
| |
| |
| 3 Hacking on Secure Shell or hterm. |
| |
| The easiest way to hack on Secure Shell is to load it as an unpacked |
| extension in Chrome. |
| |
| Visit chrome:extensions, check the "Developer mode" checkbox, click |
| "Load unpacked extension...", and select the chromeapps/nassh directory. |
| Before running Secure Shell, make sure to build the dependencies as |
| described below. |
| |
| You can test most changes by pressing Ctrl-R (the typical page-reload |
| gesture) while at the connect dialog, or the "(R)econnect..." message. |
| |
| 3.1 Building the Secure Shell dependencies. |
| |
| The Secure Shell app depends on some library code from chromeapps/libdot/ |
| and the hterm terminal emulator from in chromeapps/hterm. To build these |
| external dependencies, run... |
| |
| nassh$ ./bin/mkdeps.sh |
| |
| This will create the nassh/js/nassh_deps.concat.js file containing all of |
| the necessary libdot and hterm source. If you find yourself changing |
| a lot of libdot or hterm code and testing those changes in Secure Shell you |
| can run this script with the "--forever" (aka -f) option. When run in this |
| manner it will automatically re-create nassh_deps.concat.js file whenever |
| one of the source files is changed. |
| |
| 3.2 Building the Native Client plugin |
| |
| The Secure Shell app also depends on a Native Client plugin. The code |
| currently lives in chromeapps/ssh_client. Build it with... |
| |
| $ cd chromeapps/ssh_client |
| $ build.sh |
| |
| This will download and install some Native Client support libraries and |
| then build the NaCl wrapped ssh binary. When the build is done, copy the |
| entire ssh_client/output/hterm/plugin directory into chromeapps/nassh. |
| |
| |
| 4. Running the unit tests |
| |
| In a normal browser window, load chromeapps/hterm/html/hterm_test.html. |
| Make sure to open the JavaScript console to see the test output. |
| |
| The test harness will stop at the first test failure, and will not clean |
| up after the failed test. This makes it easier to poke around and see |
| what went wrong. |
| |
| Typically, a test that creates a terminal object will export it to the |
| JavaScript console as "terminal", rather then the "term_" variable that |
| the Secure Shell app exports. |
| |
| |
| 5. Debugging escape sequences |
| |
| Debugging issues with an escape sequence can be difficult to do without |
| the right tool. The hardest part is usually finding out exactly which |
| sequence is going wrong. The second hardest part is knowing what the |
| right behavior is supposed to be. |
| |
| That's where "vtscope.py" comes in. This small Python script can be used |
| to step through a pre-recorded VT session on multiple terminals. |
| |
| When the two terminals start to diverge (say, the cursor moved to 0,0 in |
| xterm, but somewhere else in hterm) you know where the trouble is. You |
| can also say what *should* have happened based on what xterm did. |
| |
| You can try it out with some of the pre-recorded test data. |
| |
| First start vtscope.py... |
| |
| $ cd chromeapps/hterm/bin |
| $ ./vtscope.py |
| |
| Tell vtscope to wait for two clients... |
| |
| vtscope> accept 2 |
| |
| Then open Secure Shell, and log in to the machine with the hterm source. |
| Start the netcat utility with `nc 127.0.0.1 8383`. (If you don't have |
| netcat, get it.) |
| |
| Next, launch some other terminal (say, xterm) on the same machine. Start |
| netcat again with the same command line. |
| |
| Now you can load a recorded terminal session in vtscope... |
| |
| vtscope> open ../test_data/vttest-01.log |
| |
| And start stepping through the escape sequences... |
| |
| vtscope> step |
| vtscope> step |
| vtscope> step |
| |
| You should see the two connected terminals changing in lock-step as they |
| receive the escape sequences. |
| |
| Vtscope has a few more tricks up its sleeve. Check out the comments in |
| the source for more details. |
| |
| You can record terminal sessions in xterm by enabling "Log to File" from |
| the Ctrl-Mouse-1 menu. Any terminal that has a logging option will |
| probably also work. |
| |
| If you're going to hand-edit the logs in emacs, don't forget to add... |
| |
| # -*- coding: no-conversion -*- |
| |
| ...as the first line of the file (using vi, of course). Otherwise emacs |
| will likely munge your escape sequences the first time you save. |
