HOW TO INSTALL RUBY/TK FOR THE WINDOWS RUBYINSTALLER
("NEW" ONE-CLICK-INSTALLER)

============
Introduction
============

If you want to use Ruby/Tk with the "new" One-Click-Installer for
Windows (i.e. the "RubyInstaller") from
http://rubyforge.org/frs/?group_id=167 ,
as of today (2010-02-24), you have two possibilities:

1) Compile the Ruby interpreter together with the Ruby/TK-extension
  yourself:
  * comp.lang.ruby, 2009-12-18, "Ruby 1.8.7 + Tk8.5 with
    Windows-RubyInstaller"
  * or compile a gem from Roger Pack:
    http://github.com/rdp/tk_as_gem,
  Discussion: comp.lang.ruby, 2009-12-17, "Where is Ruby 1.9 'TK'
  library?"

2) Get a ruby distro that already has the Tk bindings precompiled to
the same
  version of Tk that you want to install.  Getting the precompiled
  binaries and finding out, for which version of TK they work, (e.g.
TK8.4 or
  TK8.5), SEEMS VERY HARD.


Both ways ("compile yourself" and "precompiled binaries") require you
to install ActiveTcl from
http://www.activestate.com/activetcl/downloads/ (Download sizes:
TK8.4: ~31 MB, TK8.5: ~23 MB, disk space TK8.5: ~ 40 MB). At first, I
did not like to have my disk cluttered with TCL, just for using TK
from Ruby. But today, I dont regret it: Installation was easy,
license seems to be very permissive, even for commercial use and I
got the possibility to add additional TCL/TK libraries that I can
use from Ruby/TK, for example "plotchart" for plotting simple graphs,
nicely integrated into Ruby.

I try to give you a step-by-step instruction on how to get Ruby/Tk
working on Windows XP (hopefully it is almost the same for other
Windows versions) for the RubyInstaller for Windows ("new
One-Click-installer", http://wiki.github.com/oneclick/rubyinstaller,
http://rubyforge.org/frs/?group_id=167), which is based on mingw,
_without_ compilation.

This instruction is _not_ valid for the "old" OneClickInstaller,
which used a Microsoft compiler.

For the old compiler, you just need to download TK8.4 and make sure
its bin directory is in your PATH.

To get TK working, the following things are important:

* You need to install TCL/TK
* You need Ruby/TK-binaries, which fit your Ruby Version (e.g.
 1.8.x), the type of compiler with which it is compiled (e.g.
 mingw), and the TCL/TK-Version (e.g. 8.4)
* The environment variable "PATH" must be set appropriate.


====================
Just for Information
====================

Paths for Ruby/TK, which contain scripts only (i.e. just to be
copied, nothing what has to be compiled):

* \ruby18_mingw\lib\ruby\site_ruby\tk
* \ruby18_mingw\lib\ruby\site_ruby\1.8\tk
* \ruby18_mingw\lib\ruby\site_ruby\1.8\tkextlib\

Path for Ruby/TK, which contains the compiled files ("binaries"):
 \lib\ruby\1.8\i386-mingw32\
and/or:
 \ruby18_mingw\lib\ruby\site_ruby\1.8\i386-msvcrt
Filenames are:
 tcltklib.so and tkutil.so


========================
Step-by-Step Instruction
========================

Find Binaries
=============

Most difficult thing first: Find binaries for Ruby/TK, which fit your
Ruby Version and your TK-Version. As of now (2010-02-24), there are
only these I know of (I don't know where you can download binaries
for TK8.5):

* rdp-ruby_windows_tk from Roger Pack:
 - for Ruby 1.8.6-mingw and 1.8.7-mingw + TK8.4
 - http://github.com/rdp/ruby_windows_tk
 - (download-instruction below)
 - download size: 0.4 MB.
* ruby191p376.tgz from Roger Pack:
 - comp.lang.ruby, 2010-02-18, "Where is Ruby 1.9 'TK' library?"
 - contains binaries for Ruby-1.9.1-mingw + TK8.4 (not TK8.5).
 - Download size: 15 MB
* ruby-1.9.1-p243-tweaked.tgz from Roger Pack
 - comp.lang.ruby, 2010-02-19, "Where is Ruby 1.9 'TK' library?"
 - contains binaries for Ruby-1.9.1-mingw + TK8.4 (TK8.5).
 - download size: 40 MB
* Please put a note in comp.lang.ruby, if you know of other
 downloadable Windows-mingw-TK-binaries (hyperlink and, if
 available, Ruby-Version and TK-Version.)

Do _not_ install yet!

Speaking of "binaries" here, I mean:
* a lot of tkxxx.rb-scripts (not really binaries), which are easy to
 get,
* tcltklib.so and tkutil.so, which you normally get by compilation;
 they need to fit your Ruby-Version, the compiler with which
 Ruby-Interpreter has been compiled and the TK-Version (8.4, 8.5,
 8.6) you are going to use. To my experience, these are _not_ easy
 to get.

(Note: rdp-tk_as_gem for Ruby 1.9.1-mingw +
TK8.5? does _not_ contain binaries, but helps compiling with mingw
http://github.com/rdp/tk_as_gem).


Install ActiveTcl
=================

Download and install ActiveTcl to path WITHOUT SPACES/BLANKS  from:
http://www.activestate.com/activetcl/downloads/
(I didn't need to register):

* If you have Ruby/TK binaries for TK8.4, choose ActiveTcl 8.4.x.y,
 "Windows Installer (EXE)"
* If you have Ruby/TK binaries for TK8.5, choose ActiveTcl 8.5.x.y,
 "Windows Installer (EXE)"
* If you have Ruby/TK binaries for TK8.6, choose ActiveTcl 8.6.x.y,
  "Windows Installer (EXE)" (still beta-release at 2010-03-09)


Download and "install" Ruby/TK
==============================

For rdp-ruby_windows_tk from http://github.com/rdp/ruby_windows_tk
------------------------------------------------------------------
(Ruby 1.8.6-mingw and 1.8.7-mingw, TK8.4(!) )

Download:
* goto http://github.com/rdp/ruby_windows_tk
* click "Download Source"
* click "ZIP"
* Save the file for example to c:\rdp-ruby.zip
* Extract the downloaded zip-file

Install, first way (I didn't try this, but probably this is the
better way):
* In the extracted files locate the directory of the
 "install.rb"-File (probably
 ...\rdp-ruby_windows\rdp-ruby_windows)
* Open a command shell
* Change the working directory to the directory of "install.rb", for
 example using: cd c:\rdp-ruby_windows\rdp-ruby_windows
* Follow the instructions at http://github.com/rdp/ruby_windows_tk ,
 starting with "ruby install.rb"

Install, second way (I used this):
* Copy all files and dirs - but _not_ dir "i386-mswin32" -
   from:              \lib\ruby\1.8\
   to:   <YourRubyDir>\lib\ruby\1.8\
* Copy tcltklib.so and tkutil.so
   from:                     \lib\ruby\1.8\i386-mingw32\
   to:          <YourRubyDir>\lib\ruby\1.8\i386-mingw32\
   and also to: <YourRubyDir>\lib\ruby\site_ruby\1.8\i386-msvcrt\


For ruby191p376.tgz from roger pack
-----------------------------------
(Ruby 1.9.1-mingw, TK8.4(!) )

* Download ruby191p376.tgz from:
   comp.lang.ruby, 2010-02-18, "Where is Ruby 1.9 'TK' library?"
* Extract it.
* Copy all files and dirs
 from: \lib\ruby\gems\1.9.1\gems\tk_as_gem-0.0.1\ext\lib\
 to:   <YourRubyDir>\lib\ruby\1.9.1\
* Additionally, copy:
 from:
   \lib\ruby\gems\1.9.1\gems\tk_as_gem-0.0.1\ext\tcltklib.so
   and
   \lib\ruby\gems\1.9.1\gems\tk_as_gem-0.0.1\ext\tkutil\tkutil.so
 to:
   <YourRubyDir>\lib\ruby\1.9.1\i386-mingw32\
 and also to:
   <YourRubyDir>\lib\ruby\site_ruby\1.9.1\i386-msvcrt\


For ruby-1.9.1-p243-tweaked.tgz from roger pack
-----------------------------------------------
(Ruby 1.9.1-mingw, TK8.4(!) )

* Download ruby-1.9.1-p243-tweaked.tgz from:
   comp.lang.ruby, 2010-02-19, "Where is Ruby 1.9 'TK' library?"
* Extract it.
* Copy all files and dirs, _containing_ "tk" (= *tk*),
 from:              \lib\ruby\1.9.1\
 to:   <YourRubyDir>\lib\ruby\1.9.1\
* Additionally, copy
 from:
   \lib\ruby\1.9.1\i386-mingw32\tcltklib.so
   and
   \lib\ruby\1.9.1\i386-mingw32\tkutil.so
 to:
   <YourRubyDir>\lib\ruby\1.9.1\i386-mingw32\
 and also to:
   <YourRubyDir>\lib\ruby\site_ruby\1.9.1\i386-msvcrt\


Check, if your PATH environment variable is set correct
=======================================================
* open a command shell
* type: path
* You should get something like:
     PATH=...;C:\Programme\TCL\bin;...
  where "C:\Programme" stands for the directory, where _you_
   installed TCL.
   IMPORTANT: If there is more than one TCL-path-entry,
  the TCL-path for the TCL/TK-version which fits your Ruby and
  TK-Version must be the first one.
* If your PATH environment variable is _not_ set correct, set it
 manually: Click Start (normally on the bottom left of your screen);
 then Control Panel > System > Advanced > Environment Variables
 (German: Systemsteuerung > System > Erweitert > Umgebungsvariablen)
 Look for variable "Path", double-click, and add to the very
 beginning of the Variable-value-line:
    c:\Programme\TCLxxx\bin;
  where "C:\Programme\TCLxxx\" stands for the directory, where _you_
 installed TCL. Don't forget the ";" behind "bin" and check for any
 typo! Click OK, OK, OK, ... and restart your computer :/


Check that installation works
=============================
Create and run a Ruby-script with the following content:
 require 'tk'
 p Tk::TK_PATCHLEVEL
 root = TkRoot.new(:title=>"Hellooo  Ruby")
 Tk.mainloop

On my side, this returns:

c:/ruby18_mingw/lib/ruby/site_ruby/1.8/tk.rb:832: warning: instance
variable @cmdtbl not initialized
"8.4.19"

First line is a warning, about which you need not care. I get it
because I call my scripts with warnings enabled ("ruby -w
myscript.rb").
Second line shows the TK-Version ("8.4.19")

Additional, you should get a small window created by Ruby/Tk.


Ruby/TK-Examples
================
Many can be found here:
At: http://www.ruby-lang.org/en/
download and extract: ruby-1.8.7-p248.zip

Run:
ruby <your_path>\ruby-1.8.7-p248\ext\tk\sample\demos-en\widget

There are even more examples in
<your_path>\ruby-1.8.7-p248\ext\tk\sample\



Adding Packages to TCL/TK
=========================
For some Ruby-Tk-examples (e.g. ...\tkextlib\tcllib\plotchart.rb) you
might need to install additional TCL-packages; this can be done as
follows:

Use "teacup". ActiveTcl must be installed

LIST packages available from ActiveState
In command shell:   teacup list

SEARCH for a package containing a certain string
(not case sensitive)
In command shell:   teacup search plot

INSTALL a package (case sensitive!):
In command shell:     teacup install Plotchart

Help on certain commands:
In command shell:   teacup help <command>

See:
http://wiki.tcl.tk/17305


Bindings between Ruby and TK for some additional TCL-packages
can be found here:

"tcltk-ext (http://raa.ruby-lang.org/search.rhtml?search=tcltk-ext)
may be useful to treat such Tcl/Tk extensions on Ruby/Tk.
However, the library is very old and not developed for many years.
So, it may not work with recent Ruby/Tks."


Notes
=====
I did my tests using:
* ruby-1.9.1-p378-i386-mingw32
* ruby-1.8.7-p249-i386-mingw32

When using ruby-1.8.7-p249-i386-mingw32 and the above mentioned
rdp-ruby_windows_tk, the examples from \ext\tk\sample\demos-en\widget
"stutter" or "judder" (German: "ruckeln"). Same is also true with my
self-compiled 1.8.7-mingw + TK8.5.

This does not occure with ruby-1.9.1-p378-i386-mingw32 and the above
mentioned binaries.

Anybody knows, why?


Please
======
* Please post any comments, corrections,...
* Please put a note in comp.lang.ruby, if you know of other
 downloadable Windows-mingw-TK-binaries (hyperlink and, if
 available, Ruby-Version and TK-Version.)

Many thanks to Hidetoshi NAGAI and Roger Pack!
Both gave me a lot of help on creating this instruction.

Axel