blob: 34703749d08205577a6118d4693941e5c758376e [file] [log] [blame]
.--~~~~~~~~~~~~~------.
/--===============------\
| |```````````````| |
| | | |
| | >_< | |
| | | |
| |_______________| |
| ::::|
'======================='
//-"-"-"-"-"-"-"-"-"-"-\\
//_"_"_"_"_"_"_"_"_"_"_"_\\
[-------------------------]
\_________________________/
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.