blob: 61ff2c9fd2c66c93ea162c4f861a744a76b75f44 [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 git.chromium.org. (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 http://git.chromium.org/chromiumos/platform/assets.git
That's it. Look under the chromeapps/ directory for the 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://git.chromium.org/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.
You're now ready to start hacking. Once you've got something to post for
review, commit it locally with...
$ git commit
And then upload it using...
$ repo upload
If you want 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.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.
3. Building the Native Client plugin
If you want to make changes to the plugin, you'll need to build it from
scratch. However, if you're only interested in front end changes, you
can cheat.
3.1 Cheating the Native Client plugin
If you've already got Secure Shell installed, search your local drive for
"ssh_client_x86_32.nexe". Copy the entire parent directory (not just
that one .nexe file) into chromeapps/hterm/plugin.
If you don't have Secure Shell installed, can't, or won't install it for
some reason you can download the CRX file, expand it with "unzip", and copy
the entire plugin/ directory into chromeapps/hterm.
3.2 Building the Native Client plugin
If you actually want to make changes to the native client plugin then
you'll need to run its build script...
$ cd chromeapps/ssh_client
$ build.sh
This will download and install (locally) some Native Client support
libraries. When the build is done, copy the entire hterm/plugin/
into chromeapps/hterm.
4. Building the front end
The front end code (in chromeapps/hterm) doesn't require a build step.
There is a one-time setup however. You must create a symlink from
hterm/manifest-dev.json to hterm/manifest.json. That goes like this...
$ cd chromeapps/hterm
$ ln -s manifest-dev.json hterm/manifest.json
And that's it for the front end.
5. Adding the unpacked application to Chrome
You can add the front end source as a Chrome App without packaging it
back into a CRX file. This makes development turnaround extremely fast.
Just make a change to the source and reload the Secure Shell page in
the browser.
To get this set up, open Wrench->Tools->Extensions, enable the Developer
Mode checkbox, click "Load unpacked extension...", and select the
chromeapps/hterm directory.
You should now see a "Secure Shell (dev)" icon on your New Tab Page.
6. Running the unit tests
In a normal browser window, load chromeapps/hterm/html/test_harness.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.
7. 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.