We’ll take you through the one-time steps necessary to install and build your working copy of the Onyx toolkit.
Start the PuTTY application. It puts up some UI for entering a host name or IP address.
Look back at the console; there should be a line above the login prompt that gives you the IP address to use:
OnyxUbuntu32 -- Ubuntu 32-bit Server -- IP address: 172.16.166.130
OnyxUbuntu32 login: _
The IP address of the Ubuntu server is the four dotted-numbers part. It’s unlikely to be exactly the same as the above, but it’s likely that it starts with 172.16..
In PuTTY you should type a name for your SSH connections to the OnyxUbuntu32 server, e.g. OnyxUbuntu32, and then enter the IP address into the address field, then click Save. PuTTY will associate the IP address with the name you gave so you won’t have to type it each time.
Double click on the OnyxUbuntu32 name to open an SSH connection to the server. A terminal window should open with a comand-line login prompt; enter your user name and your password at the following prompts:
OnyxUbuntu32 login:
Password:
You should be logged into your own account on the server.
One configuration detail in PuTTY. In the Keyboard settings, put a check in the box for Meta key. Then be sure to Save the configuration.
We recommend (well, Hugh anyway) using Emacs as your one and only work environment on the server. Emacs keeps each of the things you work with in a text buffer, e.g. each text file, each file of Python code, each command shell, each directory listings, etc, etc. is in its own buffer of text. Buffers of text is the currency used throughout Emacs. This is a very simple and flat user interface: everything is text!
Furthermore, Emacs is highly configurable. You can configure almost anything about how it operates. Emacs has a good tutorial that provides an introduction to many of its basic features and to its configurability.
Here’s the Emacs Manual, and the GNU Emacs homepage. The tutorial is builtin to Emacs, we’ll show you how to run it below.
When explaing about how to drive Emacs there are a couple of conventions you must know about:
Echo Area
Emacs works well in any terminal window. That is, it has a character-based model of display and workflow. Mostly you just type text into a buffer. But, when Emacs is expecting input from you, or when you are constructing a command, or when it needs to tell you something, it prompts you and gives you feedback in the Echo Area, the bottom-most line of the window.
Mode Line
The line right above the Echo Area is the Mode Line. It’s where Emacs puts information about the buffer that’s right above the Mode Line. It’s also where other information, e.g. the time of day, is displayed.
Keystrokes
Keystrokes are shown in a fixed-width font with a space between each separate key press. So, C a t Return means to hold the Shift key and press the c key, release both of those, then press the a key, then press the t key, the hit the Return key. That would leave the text cat on a line by itself with the cursor on the next line.
Holding the Control key and then pressing another key
This is denoted by the prefix C-, e.g. C-x means to hold the Control key and then press the x key. So, C-x b means to hold the Control key and press the x key, release both of those keys, and then press b.
Holding the Alt key and then pressing another key
This is denoted by the prefix M-, (M for meta), e.g. M-v means to hold the Alt key and then press the v key. Note that Alt key is sometimes marked Option.
Also, you may have to configure your terminal application to allow the Alt (or meta) modifier key to work that way. Until you’ve done that, you can use the long-cut of hitting they Esc key first. So, to enter M-v you do Esc v, that is, you do it with two keystrokes, the Esc key followed by the v key.
Start Emacs:
hugh@OnyxUbuntu32:~$ emacs
You should get a buffer that describes a few helpful starting points. Then do C-x b Return to get the the *shell* buffer that Emacs has running. The shell buffer is like a shell in a terminal window, but with some useful quirks.
Shell buffer
For one thing, the buffer grows as the you work with the shell, so there’s a text record of everything that happened during your work. You will find that you often copy output text from the shell buffer to other text files you’re working on. New commands are always typed in at the bottom of the shell buffer.
Editing:
The standard text-navigation and editing commands work in the shell buffer.
Control characters:
Because it’s inside Emacs, any control characters that you need to send to the shell must be prefixed with C-c. E.g. to send C-d (the standard Unix way to end input) to end the input to a command you must type C-c C-d, or to cancel a running program, C-c C-c, or to suspend a program, C-c C-z.
Previous commands:
Emacs keeps a history of all commands you’ve typed. When you’re at the prompt at the bottom of the buffer you can use M-p to insert the previous command, and multiple M-p to cycle back through prior commands.
Cancel
You can cancel out of almost anything in Emacs with Control-g, C-g.
Man pages
Command-line tools on Unix are documented in what are called man pages. Each command-line tool has its own man page. Emacs knows how to format a man page and put the text in a buffer. Let’s look at the man page for Python.
M-x m a n Return p y t h o n ReturnThe man page is displayed in a different buffer, the other buffer. To go to that buffer do
C-x oTo page down or up in that buffer, use C-v or M-v. The man page just talks about the command-line options for starting the Python interpreter. It doesn’t talk about the Python language.
To go back to the shell buffer do:
C-x o
Tutorial
Emacs has a built-in tutorial. You can start the tutorial at any time via C-h t. Emacs is a very rich and powerful environment; we strongly recommend working through the tutorial once you’ve got Onyx installed and built.
Onyx is a Python toolkit that provides many low-level tools for doing research on machine learning with streaming data. Onyx is hosted on SourceForge, and a copy of Onyx HTML documentation is kept fairly up to date there as well.
Installing a copy of Onyx is easy. Go to the shell buffer. Make sure you’re in your home directory, then create a directory for your work:
hugh@OnyxUbuntu32:~$ cd
hugh@OnyxUbuntu32:~$ mkdir work
hugh@OnyxUbuntu32:~$ cd work
hugh@OnyxUbuntu32:~/work$
Now we’ll install Onyx under your work directory there using bzr, the version conrol system. For practice, bring up the bzr man page in Emacs, starting with M-x m a n Return, and filling in the rest yourself.
Here’s the installation command that runs bzr:
hugh@OnyxUbuntu32:~/work$ bzr branch bzr://onyxtools.bzr.sourceforge.net/bzrroot/onyxtools/onyx/
Branched 96 revision(s).
You don’t want to type the entire command. Instead:
The bzr command goes out to the SourceForge server and downloads (branches) the latest version of the Onyx project into the onyx subdirectory. It works silently, so be patient while it completes. When it finally prints its one-line report the revision number will be higher than the 96 shown above because people have revised the project since that example was captured.
Switch into the onyx directory and run the pypa command alias that sets up the PYTHONPATH environment variable:
hugh@OnyxUbuntu32:~/work$ cd onyx
hugh@OnyxUbuntu32:~/work/onyx$ pypa
hugh@OnyxUbuntu32:~/work/onyx$
Now build the project using the op/scons command:
hugh@OnyxUbuntu32:~/work/onyx$ op/scons
scons: Reading SConscript files ...
Mkdir("build/linux2-posix-i386-32bit-le")
scons: done reading SConscript files.
scons: Building targets ...
scons: building associated VariantDir targets: build/linux2-posix-i386-32bit-le
gcc -o build/linux2-posix-i386-32bit-le/cpp/sph2pipe/file_headers.o -c -Wall -Werror build/linux2-posix-i386-32bit-le/cpp/sph2pipe/file_headers.c
[ ... hundreds of lines of building and testing commands taking several minutes to finish ... ]
Install file: "build/linux2-posix-i386-32bit-le/cpp/liveaudio/sndfilewrap.so" as "cpp/liveaudio/sndfilewrap.so"
Install file: "build/linux2-posix-i386-32bit-le/cpp/syck/_syck.so" as "cpp/syck/_syck.so"
scons: done building targets.
hugh@OnyxUbuntu32:~/work/onyx$
If all has gone well, the output from op/scons will end with scons: done building targets.. If so, Congratulations!, you’ve not only got your Ubuntu server running, you’ve installed and built Onyx.
Adding files to the build
Don’t hesitate to try changing files or even creating new Python files. You can’t damage anything on the SourceForge repository, and you can always install a fresh copy of Onyx to your machine. For new Python files, copy the template in templates/module.py to your new filename in one of the directories under py/onyx. Add a env.PyFile('<new filename>.py') statement to the SConscript in that same directory. Save your new file and the SConscript file. Now when op/scons is run, your new file will also be built and tested.
Python mode
When you open a Python file in Emacs, the text buffer will be in Python mode. This means several things, notably that the text will be colored according to its syntax in the language (chromo-coding). Another very useful thing about Python-mode is that it’s very easy to execute the code in the buffer. Two keystrokes, C-c C-c will cause the text of the buffer to get sent to a freshly running Python. The output of running the text will be put in the *Python Output* buffer.
Try it. Create a new file buffer: C-x C-f m y c o d e . p y Return
Type the following into the buffer:
print 'Hello world!'
Make sure there’s a newline (Return) following that line.
Then do C-c C-c. The text Hello world! that Python prints when it runs the code should appear in the *Python Output* buffer.
Emacs tutorial
Be sure to spend time with the Emacs tutorial, C-h t.
Working with Onyx
You can use Emacs dired mode, C-x d Return, to browse the project’s directories. In a dired buffer, n and p move down and up by one entry. Use v to visit files and subdirectories. Use ^ to go up to the parent directory.
At this point, you may also want to look more closely at the online docs:
Note
Some of the other installation and usage instrutions that you’ll find in the Onyx documentation are somewhat out-of-date. But the code itself and the build system are not out of date!
Python documentation
There is extensive and well-maintained Python documentation online. The Tutorial and Library Reference are good starting points about how to use the libraries of the language to do stuff. The Language Reference is more advanced; it’s about the syntax and fundamental semantics of the interpreter itself.