File: palcom/doc/setup/Cygwin-Install.txt

-------------------------------------------------------------------------------
Introduction 
-------------------------------------------------------------------------------

The PalCom developer tools can be invoked from the command line on
Windows, using the Cygwin UNIX emulation suite.

To install this, download an execute the installer:

http://www.cygwin.com/setup.exe

When run, you will be asked a number of questions.
Typical answers are:

  Download Source: Install from Internet
  Root Directory: C:\cygwin
  Install for: All Users
  Default text file type: DOS 
   (IMPORTANT if you check out palcom using a windows tool,
    e.g. if you use Eclipse as described in Eclipse-SVN.txt)
  Local Package Directory: <anywhere on your computer>
  Internet Connection: Direct Connection
  Download site: <a site near you>
 
When you reach the Select Packages list, there are a number of
packages you need to install, as well as some we recommend you also
install. You may wish to click the "View" button one or more times
until an alphabetical list of packages is shown.
To include a package in the installation, click the two "circular
arrows" once to get the latest stable release instead of "Skip".

The packages besides the default ones selected by the installer
itself we recommend are:

  + subversion     (if you want to use cygwin for svn checkout/update/commit)
  + gcc-g++	   (needed to compile pal-vm)
  + less	   (file paging tool)
  + make           (needed to compile pal-vm and some tutorials)
  + perl           (needed for a few scripts)
  + vim/emacs/nano (text editors)

Once you press Next, the relevant packages will be downloaded and
installed.

Installing ANT
--------------

You will need ant to build the java based projects in palcom.
Ant seems not to be included in the current cygwin packages, but can
be downloaded from 

http://ant.apache.org/bindownload.cgi

Setting up for ant is rather simple, see 

http://ant.apache.org/manual/index.html

For cygwin it basically amounts to (assuming ant installed in C:\)

export ANT_HOME=/cygdrive/c/ant
export PATH=${PATH}:${ANT_HOME}/bin

Installation check
------------------

Please do this in a cygwin bash window:

which make

This should report 

/usr/bin/make

Using the cygwin built-in 'make' is essential to a correct build of
the pal-vm and some of the tutorials.
If you get another path from "which make", please fix your PATH (see
below for examples).

Cygwin tips
-----------

Quickedit:

If you click the cygwin icon in the upper left corner of a cygwin
window, you get a menu ending in "Properties".
Select Properties, and under "Edit Modes" select Quickedit.
When you press OK select "Modify icon that started this window".
Then the current and future cygwin windows will support copy and paste
using the mouse: Drag to select, right-click to copy and right-click
to paste.

Home directory
--------------

If you add a Windows Environment Variable called "HOME" via
Start->Control Panel-System->Advanced->Environment Variables
you can specify where cygwin windows start up, and where cygwin
"dotfiles" reside.
We recommend HOME=C:\

Dotfiles: .bash_login
---------------------

The most important dotfile you can place in HOME is called
.bash_login.
In here you can e.g. specify variables to set during bash shell
execution. Some useful examples:

# Include SUN Java installation in setup
# Notice the alternative cygwin notation for C:\
export JAVAHOME="C:/Program Files/Java/jdk1.5.0_11"; 
export PATH="/cygdrive/c/Program Files/Java/jdk1.5.0_11/bin:$PATH"; 

# Include palcom in setup
export PATH="/cygdrive/c/PalCom/palcom/bin:/cygdrive/c/PalCom/palcom/developer/dev-bin:$PATH"; 


Dotfiles: .inputrc
------------------

In HOME you may also place a file called .inputrc, which modifies the
way the command interpreter in cygwin bash works.
Here is an example content:

set completion-ignore-case On
set show-all-if-ambiguous on
"\e[A": history-search-backward
"\e[B": history-search-forward

The first line augments the completion functionality to be case
insensitive.
That is, if you have a file like "Cygwin-Setup.txt" in your current
directory, and on the command line type

ls cyg<TAB>

this will complete to 

ls Cygwin-Setup.txt

The second line specifies that you want all possibilities listed, if
there are more than one matching completion.

The two next lines specify that arrow-up and arow-down can be used to
complete via the command history. That is, if you previously did a
command like

ls Cygwin-Setup.txt

and then later type

ls<arrow-up>

this will complete to 

ls Cygwin-Setup.txt

(assuming that was the latest commend starting with "ls").

For more tricks like this, refer to "man bash".