1. BirdTerm_building_doc.html  Copyright 2009 Kevin Stokes  

  2. - The content of this document may be freely copied as long as the original copyright notice and links to the Bold Inventions website remain.
  3. - This information is to be used at your own risk.  There is no warranty or guarantee that this information is accurate or useful for any purpose.

  4. BirdTerm - The Bold Inventions Really Dumb Terminal Program
    1. Intro
    2. This Documentation
    3. Requirements for Compiling BirdTerm from Source Code
      1. The BirdTerm source tree is a Eclipse-based Project
      2. BirdTerm uses SWT and JFace
    4. Getting the Source Code from the SVN repo
      1. What is SVN?
      2. Method one:    Download the command line svn program and learn the commands
      3. Method two:  TortoiseSVN
      4. Method three:  Eclipse Subversive
    5. The BirdTerm Projects
      1. If your org.eclipse.swt Project is not happy, don't despair...
      2. The RxTx Serial Communication Library
    6. The Bird Term Application Design
      1. You have been warned!
      2. boldinventions.ansi_console
        1. TextConsole
        2. TextConsoleDocument
        3. AnsiTextConsole
        4. AnsiCharColors
      3. boldinventions.ansi_console.serial
        1. AnsiSerialConsole
        2. SerialPortOpenDialog
      4. boldinventions.birdterm
        1. BirdTerm
        2. AppSettings
    7. How To Generate the Application Files Require To Run in Stand-Alone mode
      1. Checking the Manifest File
      2. Creating the Output Folder for the Application
      3. Getting Eclipse to Make BirdTerm.jar for you
      4. Copy the SWT/JFace/RxTx Jar Files from your Hard Drive to Output Folder
      5. If the Application Doesn't Run

BirdTerm - The Bold Inventions Really Dumb Terminal Program

http://boldinventions.com/

Intro

This free, open source Java program emulates an RS232 (Serial Port) terminal, similar to Microsoft's HyperTerm,or T. Teranishi's TeraTerm program.

BirdTerm is a free open-source program. It is released under the Eclipse Public License 1.0. For more info, see the files
in the License folder in the distrubution. You may use BirdTerm for free for both non-commercial and commercial use. For exact
legal terms, please see the License folder for more info.

This version 1.0 release of BirdTerm, has minimal features. It supports a subset of the Ansi command sequences to chance text color, and cursor position.

For information on how to run the BirdTerm program, please see the ReadMe.txt file which should come with your executable.


This Documentation

This document is to help with people trying to compile the source to recreate the BirdTerm program, because perhaps you want to add a feature or make a change.   If you find a problem and want to fix it, please go to BoldInventions.com and attempt to let us know about it.


Requirements for Compiling BirdTerm from Source Code

The BirdTerm source tree is a Eclipse-based Project

BirdTerm is a Java program developed using the Eclipse IDE.   More specifically, we used  Eclipse Version: 3.5.0.   Our starting point was the 'Galileo' release, which you can get info and a free download from:

http://www.eclipse.org/galileo/


If this link is broken because it is old, there is a good chance you'll be fine getting whatever the latest Eclipse release is.    Just go to

http://www.eclipse.org 

and go to the downloads page and download eclipse for Java developers.

BirdTerm uses SWT and JFace

SWT and JFace are basically libraries created by the Eclipse foundation.  They are used by the Eclipse IDE.   BirdTerm uses SWT and JFace for the graphic user interface, and does not use Sun's AWT or Swing packages directly.   Therefore, along with the BirdTerm code, the SWT and JFace libraries need to be distributed as part of the application.

For people who like to get all riled up about Swing vs. SWT, be advised that we at Bold Inventions like both of them and aren't at all interested in GUI politics.

The fact that we used SWT and JFace also makes it more complicated to set up Eclipse.   When the user downloads the BirdTerm source code, she may notice there are two projects there, one named BirdTerm and another named org.eclipse.swt.    The project org.eclipse.swt is included because that project gathers all the necessary SWT and JFace jars that the BirdTerm project needs.    The org.eclipse.swt project was added to the BirdTerm build path.

This org.eclipse.swt project references very specific versions of the jar files found in the Eclipse\plugins folder, so if you are using a different version of Eclipse, you will possibly need to recreate this org.eclipse.swt project.    It is a bit tedious to do so, but not very difficult.   The good thing is that once you get your org.eclipse.swt project set up, you can use it to make all your SWT/JFace programs and you won't have to do this again.


Getting the Source Code from the SVN repo

The source code to BirdTerm should be available from

http://sourceforge.net

Search for 'BirdTerm'

What is SVN?


To actually download the source, you'll want to use SVN which is a way of storing files that keeps track of changes over time, and lets multiple work on a project at once. 

To learn more about SVN see http://en.wikipedia.org/wiki/Subversion_(software)

If you don't have SVN, here are three popular methods of using this widely used system:

Method one:    Download the command line svn program and learn the commands

http://subversion.tigris.org/

  This is a command-line based SVN client.  You can type commands in a console to access the SVN repository.   We at Bold Inventions have never used this, but it might not be that hard.   We prefer the other choices.

Method two:  TortoiseSVN

To get the source, you'll want to get from the SVN repo located on Sourceforge's BirdTerm page.     SVN is a really cool program for saving your source code.  It keeps track of all your changes over time and keeps a backup of everything.  And it is free open source.      Here at Bold Inventions, we use  TortoiseSVN because it is integrated right into Windows File Explorer, and we haven't had to learn any SVN commands yet.   Get TortoiseSVN from here:

http://tortoisesvn.tigris.org/

It might be that you need to install the command line version of SVN first.   Also, follow any instructions carefully, and remember to reboot after installing TortoiseSVN in order for the context features to show up in your File Explorer.

TortoiseSVN has no relation to Bold Inventions.   We just like it alot.   If you have trouble with TortoiseSVN, please refer to the FAQ and Support pages of their website.

Method three:  Eclipse Subversive

  This is the best.  Use Subversive, SVN is integrated right into your IDE.   You can check your sources into the repository right from the IDE.     At the time we installed it, it was quite complicated to get working, as it was necessary to go to another site and download some 'Connectors' and there were some confusing choices.    We documented it all, but the current Subversive web site claims that installation is easier now, so perhaps it is no longer a hassle.

http://www.eclipse.org/subversive/

  Here at Bold Inventions we use both TortioseSVN and Subversive quite often.

TODO:
   Figure out the exact commands for getting the source - I'm not sure how if you don't have full access to the SVN repo.......


The BirdTerm Projects

  The source code to BirdTerm is save in the repo as two Eclipse Projects.   One is BirdTerm.  That has all the source code and project settings for building the application.    However, it references the other project, org.eclipse.swt.   This project has the build path with all the SWT and JFace jars in it.      The BirdTerm project should not require any configuration or set up.   If you see compile errors marked on everything, it is probably because of problems with the org.eclipse.swt project.

If your org.eclipse.swt Project is not happy, don't despair...


  If it appears that there is a problem with the org.eclipse.swt project, a likely possibility is that your version of eclipse is not the same as the one used when this project was created.    The org.eclipse.swt project contains references to very version-specific jar files in the ECLIPSE_HOME\plugins folder.   Newer versions of Eclipse are likely to have jar files with different versions in their names.

  The eclipse Wiki has a really good tutorial on how to recreate this project with lots of screen shots and everything:

http://wiki.eclipse.org/JFace#Setting_Up_an_Eclipse_Project_to_use_SWT_and_JFace

  Keep in mind, that wiki page might not be exactly up to date with all the jar files.  Sometimes the SWT folk split a module into two or combine some or change a name.  You can look at the Build Path in our org.eclipse.swt project to see what we put in ours.

  As long as they haven't change SWT or JFace too much, once you get your org.eclipse.swt project set up nicely, you should be able to compile BirdTerm.

The RxTx Serial Communication Library

Included in the BirdTerm project are the DLL's for the RxTx communications library for Java.   The DLL's used in BirdTerm are already in the project in the BirdTerm SVN repo, so if you have gotten the full source to BirdTerm, then you already have the native DLL's and the jar file that you'll need.   But if you want to replace the files in the BirdTerm/Lib folder with new versions, they are available here:

Binary downloads are available there, and there is a link the source code, but the source is not necessary in order to rebuild BirdTerm.

http://rxtx.qbang.org


Hopefully, this is enough information to get the project to compile.

The Bird Term Application Design

You have been warned!

   BirdTerm is probably not an example of good design or programming style.    If there are some really awesome parts, it must have happened by accident.    There are some comments in the code, but it needs more.   For an open source project like this it would be nice if the whole thing was done in a javadoc style so we could have automatically generated doc on all the objects and so on.

   There are three package here.

boldinventions.ansi_console

   This contains three important classes, 

TextConsole

    This class is the custom control for drawing color Ascii text in a box on the screen.    Instead of trying to use an existing control like a multi-line text box, this control actually implements a listener to the swt paintEvent to redraw the screen using SWT primitives.    This was done in an effort to make it run fast by only using non-proportional fonts, and trying not to bother trying to draw parts of the control which didn't need it.   It also uses gc.drawText() to draw a whole string at a time rather than individual characters if possible.    That being said, no time was actually spent trying to measure and optimize drawing speed, so it is unclear if any of this was worth it or paid off.  Also there are probably lots of things which could be done to speed it up.
    Note, that no attempt was made to make TextConsole work properly with proportional fonts.   If an proportional font is selected into the control, you will likely see a very messy mess on the screen.

TextConsole implements the ITextConsole interface.   The ITextConsole interface is the set of methods thought most likely to be useful for communicating with a text console, making it possible to make very different implementations.

TextConsoleDocument

   As an experiment, it was decided to make the text itself be stored in a different object, since some people believe that having the document be seperated from the view is good.   So the document object stores the text, and notifies listeners of any changes.

AnsiTextConsole

   This class is a subclass of TextConsole which is able to pull some Ansi sequences out of the incoming Ascii stream and interpret these as commands to move the cursor, change text color and so on.

AnsiCharColors

   Is worth a mention.   Because SWT colors must be allocated and free'd, it was desired to have the equivalent of global variables for the 16 Ansi colors so they are always there for the life of the application.   The static method create() is called at startup, and hopefully, dispose() gets called at close time, but I'm not sure that ever gets done.   This probably isn't the best way to do this, but it seems to work ok. 



boldinventions.ansi_console.serial

AnsiSerialConsole

 Is a subclass of AnsiTextConsole which implements connecting, sending and receiving ascii characters to a serial port.   It actually creates the dialog box which allows the user to select a serial port and set the settings.   It also contains the event handlers for getting the data from the RxTx library, and a method for sending the characters back out.   It implements ICharAccepter as a way of pushing characters out the serial port.

SerialPortOpenDialog

  Is a subclass of the JFace Dialog class.  It creates a dialog which allows the user to specify a comm port and set up the settings like baud rate and so on.   AnsiSerialConsole creates an instance of this dialog and shows it when needed.  After the user closes the dialog, the application calls a method in the dialog to get the SerialPortSettingsContainer to retrieve the settings.


boldinventions.birdterm

  This package is the main application code.

BirdTerm

   This class is the main application window.   It doesn't do much but create an AnsiSerialConsole and provide some code to set the status bar text, and create the menus and manage the persistent settings.  It tries to provide some helpful error message if an exception happens while trying to open the serial port.  It also handles the logic for the auto-connect feature.

AppSettings

    This is a boilerplate kind of class with all the app settings in it.   It uses Sun's java.util.prefs.Preferences class to save and retrieve the application settings from the registry key.  It also is a place where the default values are specified.  The registry key used is:
HKEY_CURRENT_USER\Software\JavaSoft\Prefs\boldinventions\birdterm



How To Generate the Application Files Require To Run in Stand-Alone mode

  Because we have used SWT/JFace, it is necessary to put the SWT and JFace jar files in the same folder as BirdTerm.jar file in order for it to run.    It is critical that these jar files are the same as the ones specified in the org.eclipse.swt project, or the application will not run.   The manifest file must also contain the names of these jar files.   As checked out from SVN, these may not match the exact jar files present in your Eclipse installation, so care must be taken to make sure they are all consistent.

Checking the Manifest File

 Before you begin, it is important to check the BirdTermManifest.txt file.   In there is a list of jar files the application will need in order to run.   This includes the RxTx jar file, the SWT jar file, and the other JFace jar files which were included in the org.eclipse.swt project.

  If you your org.eclipse.swt project uses different versions of these jar files than the manifest indicates, the manifest file will need to be updated.   

  If needed, go through the build path of the org.eclipse.swt project, in the 'Libraries' tab, and select each of the jar files.   Hit the 'edit' button so you can copy the exact name of the jar into the clipboard, then paste that into the manifest file, replacing the original if it has a different version in the filename than the current manifest file.  Be careful about accidently removing or adding spaces!

  WARNING:  The manifest file is **very** picky about spaces and blank lines.   One space in front of the jar name in the the file did not seem to do the trick.   Two seemed to make it happy.  If the manifest file is missing any spaces or has extra spaces or lines, it is likely the application will not be able to load the jar files correctly.

  

Creating the Output Folder for the Application

  First create a folder using Windows File Explorer to put the files in, such as:

c:/java_export/BirdTerm

Getting Eclipse to Make BirdTerm.jar for you


 Then in Eclipse, right-click on the BirdTerm project in the package explorer pane.  Chose 'Export'.

  In the dialog which pops up, choose    Java/Jar File   for your export type.

  Click on Next

  In the 'Select the Resources to Export' pane, make sure the BirdTerm project is checked green, and all the other project are not selected.

  Make sure the files .classpath and .project are NOT checked, but the others are.

  Below the white panes are a bunch of check boxes.

  Make sure 'Export Generated class files and resources' is checked.

  The other 'Export' type checkboxes should be unchecked.

  Hit the 'Browse' to the destination folder you already created in the first step described above.

  Make sure the 'Compress the contents of the JAR file' is checked.

  Leave the 'Add directory entries' unchecked.

  The other checkbox about overwriting files without warning is up to you.

  Click on Next

   Make sure Export class file with compile warnings is checked.

   Check the box which saves the jar description file in the workspace.   The path in the box should be:
/BirdTerm/jar_description.jardesc

  Click on Next

   Check the 'Use Existing Manifest from workspace' radio button.
      The manifest file in the textbox control should be:
/BirdTerm/BirdTermManifest.xt

  Click on Finish

  If you get a warning about overwriting the jardesc file, say yes.

  You may get a box that says it completed with warnings.   Open the warnings and make sure they all are just Java compiler warning messages about silly code things, and not anything really bad sounding.

After this, you have created the BirdTerm.jar file and it should be in the \java_export\BirdTerm folder.

However, you are not yet finished.   All the jar files mentioned in the BirdTermManifest.txt file must exist in this folder for the application to run.  

Copy the SWT/JFace/RxTx Jar Files from your Hard Drive to Output Folder


Copy each jar file mentioned in the manifest file from your ECLIPSE_HOME\plugin folder on your hard drive into your \java_export\BirdTerm folder.   If in doubt about where the jar file is, you can always go back to the Build Path/Libraries  page of your org.eclipse.swt project.   They should all be in

ECLIPSE_HOME/plugin     folder, where ECLIPSE_HOME might be c:\eclipse

Don't forget the swt.jar file!

Warning!  Each of the jar files in the plugin folder has a source file jar with a very similar name.   Be careful not to accidently copy in a source file jar when you meant to copy the jar with the binary in it.

If the Application Doesn't Run

When all the jar files are in there, you can try double-clicking on the BirdTerm.jar file in the c:\java_export\BirdTerm folder.    Hopefully, BirdTerm will run.   If you get a class loader exception, then it couldn't find something.   Look at the error message carefully for a clue about what class it couldn't find.    The exception message is notorious for not being very precise about what the problem was, but sometimes the message can help.

Good Luck!