Difference between revisions of "CalicoDevelopment"

From IPRE Wiki
Jump to: navigation, search
(Developers)
 
(117 intermediate revisions by 5 users not shown)
Line 1: Line 1:
This page describes the planning of Pyjama Editor and Myro3. The Pyjama Editor is an integrated, cross-platform environment for learning about computing, and Myro3 is an API for communicating with real and simulated robots. This is part of the [[Pyjama]] Project.
+
This page describes how to work on the Calico source code. It is meant for developers who would like to understand how Calico works.
  
For extensive details on the planning of this project, please see [[Myro on .NET (Including Mono)]].
+
This document describes the latest version of Calico, version 2 and greater.
  
Myro3 uses [http://www.microsoft.com/robotics Microsoft Robotics Developer Studio].  This guide describes how to get started developing for Pyjama and get up and running with the in-progress version of Myro3.  We are targeting the following software versions:
+
= What is Calico? =
  
* Microsoft Robotics Developer Studio 2008, CTP April
+
First, let's take a step back and see Calico in the big picture. What is it exactly?
* .NET 3.5
+
* Mono 1.9.1 or greater
+
* IronPython 2.0
+
  
= Overview =
+
Calico is:
  
The Pyjama interface is written in C#. This will allow any of the .NET/Mono Languages (IronPython, IronRuby, [[PyjamaScheme]], JavaScript, F#, J#, etc) to use the API.  Myro3 is the interface in .NET/Mono that allows these languages to connect to robots.
+
# A program written in C# that runs under Mono and .NET
 +
# It has abstractions for dynamically loading two kinds of libraries:
 +
## Languages
 +
## Libraries
  
Initially, connections to robots (real and simulated) will be made through the Microsoft Robotics Developer Studio (MSRDS) API [2]. This is made through a set of ''services'' defined for each robot, sensor, actuator, etc.
+
Calico is mostly GUI code, but it is really designed to be the "glue" between Languages and Libraries. Calico uses Gtk# (pronounced "gee tee kay sharp") for the graphics. Gtk is a general purpose "tool kit"... it is written in C, but has wrappers in most languages, including C++, Python, and C#. There are other graphical tool kits, but we chose Gtk because of its good support and tight connection with Mono.
  
In addition, an alternative interface could be defined that allows direct connections to a robot, or through another API, such as Player/Stage. This may require a layer above the services, or a different set of objects. This interface could allow for models to be created in C# (or another .NET language).
+
.NET and Mono are Virtual Machines (VM), and a whole lot more. To try to be clear for the rest of this document, We'll use the term VM to refer to either the .NET or Mono virtual machines when it doesn't matter which.
  
= Development =
+
You see the sharp sign (#) on a few libraries; this is usually a sign to indicate that the library works on the .NET VM. Not all programs written for the .NET VM will run on the Mono VM, and not all code written for the Mono VM will run on the .NET VM.
  
One can program either in Visual Studio (only available on Windows) or in Mono (available on most platforms). Mono has a development environment (called MonoDevelop), but you can also use any editor. There is a free Visual Studio Express available from Microsoft. Mono 1.9.1 comes with Fedora 9 and is also for free from Mono.
+
= Getting Started with Development =
  
== Install MSRDS ==
+
If you want to just run Calico, see [[Calico Download]].
  
# First, download Microsoft Robotics Developer Studio 2008, CTP July, and all software it prompts you on [ [http://www.microsoft.com/downloads/details.aspx?FamilyId=57CE326B-2125-4163-A33F-ED2F69E03B56&displaylang=en Download here] ].
+
== Translations ==
  
# Install MRDS.
+
If you are interested in getting Calico running in a language other than
# Point all the project references to MSRDS libraries to the right places.
+
English, or if you would like to get students involved in a computer
# Install the update and samples
+
science project through an alternative approach, this information may be
 +
relative to you.
  
== Install IronPython ==
+
Calico was designed to be used with non-English languages, and to be used in many cultures. This effects many aspects of a project, including:
  
Download IronPython 2.0 from [http://www.codeplex.com/IronPython/ here].
+
* language, including plural noun formations
 +
* font
 +
* numeric representations
 +
* currency
 +
* date/time representations
 +
* language direction (left-to-right, vs. right-to-left)
  
== Check out the code ==
+
These issues are sometimes shortened to "internationalization" (i18n) and "localization" (l10n).
  
The directories in the source tree pertaining to Myro3 are:
+
Calico is written a manner to use translations through the
* <b><tt>IPRE</tt></b> (Myro3 API and MRDS services)
+
"gettext" system. All strings in the main Calico program have been marked
* <b><tt>Pyjama</tt></b> (New IDE for Myro3)
+
for version 2.2.8, and exported to the calico.pot, on-line here:
  
=== Users ===
+
http://svn.cs.brynmawr.edu/Calico/trunk/locale/
  
Our read-only source tree is located at: <b><tt>http://svn.cs.brynmawr.edu/Myro/</tt></b>. You can use [http://sourceforge.net/projects/tortoisesvn TortoiseSVN].  
+
That file is copied to language files (such as es.po and fr.po, for
 +
Spanish and French, respectively) in that same folder. Those po files are
 +
then compiled to .mo files.
  
You will need Myro3 and Pyjama.
+
You also need the Gtk language files on your operating system. On Linux,
 +
those can be installed through the language-packs (eg, sudo apt-get
 +
install language-pack-es).
  
From the command line:
+
Once that has been done, running Calico, like this (on Linux and Mac):
  
  $ svn co http://svn.cs.brynmawr.edu/Myro/trunk/IPRE Myro
+
  LANGUAGE=es ./StartCalico
$ svn co http://svn.cs.brynmawr.edu/Myro/trunk/Pyjama Pyjama
+
  
=== Developers ===
+
should result in Calico running in your the identified language. (There
 +
are some strings not translated. Those are bugs.) On Windows, you can edit the StartCalico.bat file.
  
Our developer source tree is located at: <b><tt>https://svn.cs.brynmawr.edu/Myro-dev/trunk</tt></b>.  Note the http<i>s</i>. You can use [http://sourceforge.net/projects/tortoisesvn TortoiseSVN].
+
There are many tools for editing .po files. But, we have also uploaded the
 +
calico.pot file to:
  
You will need Myro3 and Pyjama:
+
https://poeditor.com/projects/view?id=161
  
$ svn co https://svn.cs.brynmawr.edu/Myro-dev/trunk/IPRE Myro
+
That is an on-line editing tool for Calico's strings. Currently, there are
$ svn co https://svn.cs.brynmawr.edu/Myro-dev/trunk/Pyjama Myro
+
versions for Spansh (es), French, (fr) and Chinese (ch). All of those
 +
could use editing by native speakers.
  
== Mono ==
+
If you have questions, please don't hesitate to ask.
  
Download and install Mono version 1.9.1 or greater.
+
== Virtual Machine ==
  
You can see what version of Mono you have with:
+
First you'll need a VM. We'll be using the latest version, called version 4. You might need to update some items on your computer.
  
mono --version
+
* On all systems, you'll need Mono, version 2.10 or later
 +
** On Windows and Mac:
 +
*** http://www.go-mono.com/mono-downloads/download.html (Install latest Mono, 2.10)
 +
** On Linux, you can use your package manager to install Mono
 +
*** On Ubuntu, Debian systems: sudo apt-get install mono
 +
*** On Fedora, Redhat systems: yum install mono
  
To install Mono (currently 1.9) with ipy included:
+
== C# Compiler ==
  
* http://www.go-mono.com/mono-downloads/download.html
+
Mono contains a C# compiler, called mcs. We use MonoDevelop as our IDE. It is available for all platforms.
  
You can then create a program, like this:
+
== Monodevelop ==
 +
 
 +
For more sophisticated devlopment, we'll use MonoDevelop. You can install it from here:
 +
 
 +
http://monodevelop.com/Download
 +
 
 +
== Gtk# ==
 +
 
 +
The only other item we'll need for building programs in general is Gtk#, the graphics tool kit for the VM. It contains the low-level C libraries, and the "wrappers" for any VM language, like C#.
 +
 
 +
* Windows: it comes with Mono
 +
* Mac: it comes with Mono
 +
* Linux: you'll need to install it from your package manager
 +
** Ubuntu: sudo apt-get install gtk-sharp
 +
 
 +
= From the Bottom Up =
 +
 
 +
To understand all of the technology of Calico, let's start at the beginning, Hello World.
 +
 
 +
We'll be running these commands from the command line. In Windows, you can run "cmd"; under Mac and Linux we'll use the Terminal or Console.
 +
 
 +
On any platform, create a file named ''HelloWorld.cs'' with the contents:
  
 
<pre>
 
<pre>
using System;                        // for Console
+
// HelloWorld.cs
 
public class HelloWorld {
 
public class HelloWorld {
  public static void Main(string[] args) {
+
    public static void Main(string [] args) {
      Console.WriteLine("Hello World!");
+
        System.Console.WriteLine("Hello, World!");
  }
+
    }
 
}
 
}
 
</pre>
 
</pre>
  
Call that program hello.cs, and compile with:
+
How to edit? You can use the Text Editor, gedit, Emacs, etc. We'll use MonoDevelop later, but for now, we just need to create a simple text file.
 +
 
 +
Now, we'll compile this C# code for the VM using either:
 +
 
 +
* .NET, use csc
 +
* Mono, use mcs
 +
 
 +
For the rest of this document, we'll just use "mcs" to represent whichever of these you need (eg, "mcs" on Mono, "csc" on .NET).
 +
 
 +
To compile:
 +
 
 +
mcs -out:HelloWorld.exe HelloWorld.cs
 +
 
 +
This will create the file ''HelloWorld.exe'' ready to run on the VM. On Windows, you can just type "HelloWorld" or double-click it and it should display the text in a console. On Linux or Mono where the .exe is not associated with Mono, you will need to run it like:
 +
 
 +
mono HelloWorld.exe
 +
 
 +
When writing programs, you may get tired of typing the fully specified name of a function, like "System.Console.WriteLine". In C# you can use the form "using XXX;" to include everything in that "name space":
  
 
<pre>
 
<pre>
gmcs hello.cs
+
// HelloWorld2.cs
 +
using System;
 +
 
 +
public class HelloWorld {
 +
    public static void Main(string [] args) {
 +
        Console.WriteLine("Hello, World!");
 +
    }
 +
}
 
</pre>
 
</pre>
  
You can run it with:
+
The file "HelloWorld.exe" can be used as a library in the VM. But you can also compile C# code to be used as a library only. In that way, you don't need a "Main" static method. When you compile to a library, the file will have an extension of ".DLL".
  
 
<pre>
 
<pre>
mono hello.exe
+
// MyLibrary.cs
 +
public class MyLibrary {
 +
    public static int Answer() {
 +
        return 42;
 +
    }
 +
}
 
</pre>
 
</pre>
  
= Libraries for Pyjama =
+
mcs -out:MyLibrary.dll -target:library MyLibrary.cs
  
If you create a Dynamically Linked Library (.DLL) then you can load the library in Python (or any language) and use it as if it were written in Python.
+
To use the library:
  
For example under Mono:
+
<pre>
 +
// HelloWorld3.cs
 +
using System;
 +
 
 +
public class HelloWorld {
 +
    public static void Main(string [] args) {
 +
        Console.WriteLine("Hello, World; the answer is {0}", MyLibrary.Answer());
 +
    }
 +
}
 +
</pre>
 +
 
 +
And compile the code and library:
 +
 
 +
mcs -out:HelloWorld3.exe -r:MyLibrary HelloWorld3.cs
 +
 
 +
Running that gives:
 +
 
 +
$ mcs -out:HelloWorld3.exe -r:MyLibrary HelloWorld3.cs
 +
$ mono ./HelloWorld3.exe
 +
Hello, World; the answer is 42
 +
 
 +
= Calico2 =
 +
 
 +
Let's now dive into Calico. First, you'll need the source code if you don't already have it.
 +
 
 +
== Getting Source Code ==
 +
 
 +
The calico source code is currently hosted on [http://bitbucket.org bitbucket] using [http://git-scm.com/ git].
 +
 
 +
  http://git.calicoproject.org
 +
 
 +
You can clone the repository using git (assuming you have a bitbucket account):
 +
 
 +
  git clone https://USERNAME@bitbucket.org/ipre/calico.git
 +
 
 +
or if you don't have a bitbucket account you can use:
 +
 
 +
  git clone https://bitbucket.org/ipre/calico.git
 +
 
 +
There are a variety of turials online for using [http://git-scm.com/docs/gittutorial git] and [https://confluence.atlassian.com/display/BITBUCKET/Bitbucket+101 bitbucket]
 +
 
 +
 
 +
=== Contributing Code ===
 +
 
 +
Feel free to clone the Calico repository and make improvements. Once completed you can send a pull request to have the changes integrated into the main branch.
 +
 
 +
=== Getting Source Code for Calico 1 ===
 +
 
 +
Calico1 still uses SVN.
 +
 
 +
For those with write permissions to the SVN Bryn Mawr College source code repository
 +
 
 +
 
 +
svn co http://svn.cs.brynmawr.edu/Calico/branches/Calico1 Calico
 +
 
 +
 
 +
 
 +
Developers who have an Bryn Mawr College SVN account should use:
 +
 
 +
svn co https://svn.cs.brynmawr.edu/Calico-dev/branches/Calico1 Calico
 +
 
 +
 
 +
== Support Libraries ==
 +
 
 +
Please see [[Calico Download]] for additional libraries needed to run and develop Calico.
 +
 
 +
== Educational Research ==
 +
 
 +
* http://myro.roboteducation.org/~dblank/ipre/surveys/ - pre- and post- surveys for CS1
 +
 
 +
You will also need:
 +
 
 +
* mono
 +
* gtk (and libgtk2.0-cil-dev, for package-config files)
 +
 
 +
== Overview ==
 +
 
 +
There are 5 directories in the Calico folder:
 +
 
 +
# bin - contains the startup exe and dll files
 +
## bin/Lib - contains the standard Python libraries
 +
# languages - contains the language definition files for Python, Ruby, Scheme, etc.
 +
# modules - Cross-language modules that can be used by all Calico languages
 +
# examples - sample code, broken down by language
 +
# Source - the code to build the Calico .exe
 +
 
 +
== Language ==
 +
 
 +
See [[Calico: Language Development]]
 +
 
 +
= TODO =
 +
 
 +
See [http://svn.cs.brynmawr.edu/viewvc/Calico/trunk/NOTES?view=co NOTES] in the Calico download (package or svn).
 +
 
 +
= Screen Shots =
 +
 
 +
[[Image:Pyjama-010.gif]]
 +
 
 +
For more, see [[CalicoScreenShots]]
 +
 
 +
== Python and Ruby ==
 +
 
 +
Calico allows you to easily jump back and forth between languages. Enter this code in the command box:
  
 
<pre>
 
<pre>
gmcs -target:library hello.cs
+
def fib(n):
 +
    if n <= 2: return 1
 +
    return fib(n - 1) + fib(n - 2)
 
</pre>
 
</pre>
  
will create '''hello.dll''' which can be used in Python.
+
Make sure the bottom status line has Python checked, and press the '''Run!''' button (or simply hit <enter> when in the command box).
  
If you need graphics, please use Windows Forms (aka, winforms) rather than GTK, or Windows Presentation Forms.
+
Now, enter this code in the command box (make sure to set bottom status line has Ruby checked).  
  
== Build and run ==
+
<pre>
 +
class Hello_world
 +
  def greet
 +
    puts "Hello World"
 +
  end
 +
end
 +
hw = Hello_world.new
 +
hw.greet
 +
</pre>
  
For Visual Studio:
+
== Cross-language Access ==
 +
 
 +
In this example, you'll see that you can access code and variables defined in other languages.
 +
 
 +
Enter the following in the Interactive Command Box:
 +
 
 +
<pre>
 +
class PythonClass:
 +
    def hello(self, value):
 +
        print "Python says hello to", value
 +
</pre>
 +
 
 +
This defines a PythonClass. To test it out, enter the following in the command box:
 +
 
 +
<pre>
 +
pc = PythonClass()
 +
pc.hello("Python")
 +
</pre>
 +
 
 +
In the Output Box, you'll of course see:
 +
 
 +
<pre>
 +
Python says hello to Python
 +
</pre>
 +
 
 +
Now, switch to Ruby mode (bottom line status bar, select Ruby) and enter this in the command box:
 +
 
 +
<pre>
 +
pc = python_class().new
 +
pc.hello "Ruby"
 +
</pre>
 +
 
 +
This uses the PythonClass (now called python_class). In Ruby, you can create an object by placing the '''.new''' after it. You call the method .hello by placing the arguments after the method name (parens are not needed in Ruby).
 +
 
 +
You will see in the output box:
 +
 
 +
<pre>
 +
Python says hello to Ruby
 +
</pre>
 +
 
 +
which is Python code running inside Ruby!
 +
 
 +
While in Ruby Mode, enter:
 +
 
 +
<pre>
 +
class Ruby_class
 +
  def hello caller
 +
    puts "Ruby says hello to #{caller}"
 +
  end
 +
end
 +
</pre>
 +
 
 +
To see that work, try:
 +
 
 +
<pre>
 +
rc = Ruby_class.new
 +
rc.hello "Ruby"
 +
</pre>
 +
 
 +
and you'll of course see:
 +
 
 +
<pre>
 +
Ruby says hello to Ruby
 +
</pre>
 +
 
 +
Finally, switch back to Python Mode, and enter:
 +
 
 +
<pre>
 +
import Ruby_class
 +
rc = Ruby_class()
 +
rc.hello("Python")
 +
</pre>
 +
 
 +
and you'll see:
 +
 
 +
<pre>
 +
Ruby says hello to Python
 +
</pre>
 +
 
 +
which is Ruby code running in Python!
 +
 
 +
 
 +
 
 +
 
 +
 
 +
== Interacting with .NET ==
 +
 
 +
The languages of Calico can also interact with .NET/Mono. If you are already familiar with .NET/Mono programs (such as those written in C# or Visual Basic) then you will recognize some of these idioms and names.
 +
 
 +
As a simple example, let's use the interactive abilities to directly interact with some Windows Forms. In order to do this in Calico, will turn the threaded ability off, so as to talk to the GUI in the same thread as Calico is running in. Let's create a window (called a Form in .NET parlance):
 +
 
 +
<pre>
 +
# file: winform.py
 +
import clr
 +
clr.AddReference("System.Windows.Forms")
 +
from System.Windows.Forms import *
 +
win = Form()
 +
win.Show()
 +
</pre>
 +
 
 +
Importing the special module named '''clr''' is the gateway to interacting with the underlying .NET/Mono subsystem. From the clr module, you can add a reference to any Dynamic Link Library (DLL) so that you can access library functions and objects. In this example, we add a reference to the '''System.Windows.Forms''' DLL which contains a library of Graphical User Interface (GUI) objects. We then can create a Form, save it in a variable named '''win''', and call the form's '''Show()''' method.
 +
 
 +
If you'd like to give the window a name, enter this in Calico's interactive command box:
 +
 
 +
<pre>
 +
win.Text = "This is the Window Title"
 +
</pre>
 +
 
 +
These windows will go away when you close Calico, or you can close them manually.
 +
 
 +
== Developing a Language for the DLR in the DLR ==
 +
 
 +
''This section needs to be revised for Calico2''
 +
 
 +
Python and Ruby are defined to interact as above by taking advantage of the Dynamic Language Runtime (DLR). To further show this off, here is an example of defining a new language, much like Lisp, called SymPL written in Python using the tools of the DLR:
 +
 
 +
# [http://svn.cs.brynmawr.edu/Myro/trunk/Calico/sympl/lexer.py lexer.py] - the lexer
 +
# [http://svn.cs.brynmawr.edu/Myro/trunk/Calico/sympl/parser.py parser.py] - the parser
 +
# [http://svn.cs.brynmawr.edu/Myro/trunk/Calico/sympl/etgen.py etgen.py] - expression tree generators
 +
# [http://svn.cs.brynmawr.edu/Myro/trunk/Calico/sympl/runtime.py runtime.py] - runtime helpers (e.g., lookup, import)
 +
# [http://svn.cs.brynmawr.edu/Myro/trunk/Calico/sympl/test.py test.py] - the Read Eval Print Loop
 +
 
 +
Some sample SymPL programs:
 +
 
 +
# [http://svn.cs.brynmawr.edu/Myro/trunk/Calico/sympl/test.sympl test.sympl] - function tests
 +
# [http://svn.cs.brynmawr.edu/Myro/trunk/Calico/sympl/ops.sympl ops.sympl] - operator tests
 +
# [http://svn.cs.brynmawr.edu/Myro/trunk/Calico/sympl/lists.sympl lists.sympl] - list tests
 +
 
 +
== Writing Fast Module Code Once ==
 +
 
 +
Perhaps the nicest aspect of the DLR is that you can develop code (in CSharp, for example) that is "compiled" and used directly. Such can be imported and used by any language in the DLR suite as if it were written in that language. For example, consider this simple example:
 +
 
 +
<pre>
 +
// file: Testing.cs
 +
public class Point {
 +
  private int _x;
 +
  private int _y;
 +
  public Point(int x, int y) {
 +
_x = x;
 +
_y = y;
 +
  }
 +
  public int x {
 +
get { return _x; }
 +
set { _x = value; }
 +
  }
 +
  public int y {
 +
get { return _y; }
 +
set { _y = value; }
 +
  }
 +
  public string __repr__() {
 +
return "<Point at (" + _x + "," + _y +")>";
 +
  }
 +
}
 +
</pre>
 +
 
 +
This can be compiled in Mono:
 +
 
 +
<pre>
 +
gmcs Testing.cs -target:library
 +
</pre>
 +
 
 +
or put into a Project in Visual Studio, and compiled into a library.
 +
 
 +
You should then put the resulting '''Testing.dll''' somewhere will Calico can find it (either put in the same directory with the calico.exe, or put it in a directory and add the path of the directory to Python's sys.path):
 +
 
 +
<pre>
 +
import sys
 +
sys.path.append("/path/to/folder")
 +
</pre>
 +
 
 +
Finally, you can use it in Calico:
 +
 
 +
<pre>
 +
>>> import clr
 +
>>> clr.AddReference("Testing")
 +
>>> import Point
 +
>>> Point
 +
<type 'Point'>
 +
>>> p = Point(1,2)
 +
>>> p
 +
<Point at (1,2)>
 +
>>> p.x
 +
1
 +
>>> p.x = 9
 +
>>> p
 +
<Point at (9,2)>
 +
>>>
 +
</pre>
  
# Open the Visual Studio solution <b><tt>IPRE\Myro.sln</tt></b>.
+
== Creating Interactive Programs and Graphics for the Web ==
# Set the working directory for "runnable" projects.  These projects are in <b><tt>IPRE\Demos</tt></b>.  In the "Debug" tab of the project properties, set the working directory to the full path to your <b><tt>IPRE/bin</tt></b> directory.
+
# Fix any missing references to MSRDS and IronPython assemblies.
+
# You should now be able to run the demo projects!
+
  
== Troubleshooting ==
+
Theoretically, once you have a working program in Calico, you can save the program to run on the Web in a manner very much like Flash applications. The resulting program can (possibly) be run in a browser using Silverlight/Moonlight. Need to explore this.
  
* You may have to keep your source tree on a local drive, instead of a network drive, or you may get strange errors about not being able to find modules.  I was getting dssproxy.exe exiting with code 20, and unable to load modules at runtime, and this may have fixed it.  This may be because under Vista, network drives are not always trusted.
+
= Troubleshooting =
  
= Links =
+
If you have any trouble, find bugs, or want to make a feature request, please do that at:
  
# [[Myro_on_.NET_(Including_Mono)#Robotics_Connection|Myro3 - Robotics Connection]]
+
[http://calico.codeplex.com/WorkItem/List.aspx calico.codeplex.com/WorkItem/]
# [[Writing a Myro3 program]]
+
# [http://svn.cs.brynmawr.edu/viewvc/Myro/trunk/IPRE/Services/ Myro3 Robot Services]
+
# [http://pyrorobotics.org/?page=PyroModuleObjectOverview Pyro Robot Interfaces]
+
## [http://svn.cs.brynmawr.edu/viewvc/pyrobot/trunk/robot/ Pyro Source Code]
+
# [http://www.go-mono.com/mono-downloads/download.html Mono Download]
+
# [http://www.microsoft.com/Express/ Visual Studio Express]
+

Latest revision as of 00:33, 13 June 2013

This page describes how to work on the Calico source code. It is meant for developers who would like to understand how Calico works.

This document describes the latest version of Calico, version 2 and greater.

What is Calico?

First, let's take a step back and see Calico in the big picture. What is it exactly?

Calico is:

  1. A program written in C# that runs under Mono and .NET
  2. It has abstractions for dynamically loading two kinds of libraries:
    1. Languages
    2. Libraries

Calico is mostly GUI code, but it is really designed to be the "glue" between Languages and Libraries. Calico uses Gtk# (pronounced "gee tee kay sharp") for the graphics. Gtk is a general purpose "tool kit"... it is written in C, but has wrappers in most languages, including C++, Python, and C#. There are other graphical tool kits, but we chose Gtk because of its good support and tight connection with Mono.

.NET and Mono are Virtual Machines (VM), and a whole lot more. To try to be clear for the rest of this document, We'll use the term VM to refer to either the .NET or Mono virtual machines when it doesn't matter which.

You see the sharp sign (#) on a few libraries; this is usually a sign to indicate that the library works on the .NET VM. Not all programs written for the .NET VM will run on the Mono VM, and not all code written for the Mono VM will run on the .NET VM.

Getting Started with Development

If you want to just run Calico, see Calico Download.

Translations

If you are interested in getting Calico running in a language other than English, or if you would like to get students involved in a computer science project through an alternative approach, this information may be relative to you.

Calico was designed to be used with non-English languages, and to be used in many cultures. This effects many aspects of a project, including:

  • language, including plural noun formations
  • font
  • numeric representations
  • currency
  • date/time representations
  • language direction (left-to-right, vs. right-to-left)

These issues are sometimes shortened to "internationalization" (i18n) and "localization" (l10n).

Calico is written a manner to use translations through the "gettext" system. All strings in the main Calico program have been marked for version 2.2.8, and exported to the calico.pot, on-line here:

http://svn.cs.brynmawr.edu/Calico/trunk/locale/

That file is copied to language files (such as es.po and fr.po, for Spanish and French, respectively) in that same folder. Those po files are then compiled to .mo files.

You also need the Gtk language files on your operating system. On Linux, those can be installed through the language-packs (eg, sudo apt-get install language-pack-es).

Once that has been done, running Calico, like this (on Linux and Mac):

LANGUAGE=es ./StartCalico

should result in Calico running in your the identified language. (There are some strings not translated. Those are bugs.) On Windows, you can edit the StartCalico.bat file.

There are many tools for editing .po files. But, we have also uploaded the calico.pot file to:

https://poeditor.com/projects/view?id=161

That is an on-line editing tool for Calico's strings. Currently, there are versions for Spansh (es), French, (fr) and Chinese (ch). All of those could use editing by native speakers.

If you have questions, please don't hesitate to ask.

Virtual Machine

First you'll need a VM. We'll be using the latest version, called version 4. You might need to update some items on your computer.

  • On all systems, you'll need Mono, version 2.10 or later
    • On Windows and Mac:
    • On Linux, you can use your package manager to install Mono
      • On Ubuntu, Debian systems: sudo apt-get install mono
      • On Fedora, Redhat systems: yum install mono

C# Compiler

Mono contains a C# compiler, called mcs. We use MonoDevelop as our IDE. It is available for all platforms.

Monodevelop

For more sophisticated devlopment, we'll use MonoDevelop. You can install it from here:

http://monodevelop.com/Download

Gtk#

The only other item we'll need for building programs in general is Gtk#, the graphics tool kit for the VM. It contains the low-level C libraries, and the "wrappers" for any VM language, like C#.

  • Windows: it comes with Mono
  • Mac: it comes with Mono
  • Linux: you'll need to install it from your package manager
    • Ubuntu: sudo apt-get install gtk-sharp

From the Bottom Up

To understand all of the technology of Calico, let's start at the beginning, Hello World.

We'll be running these commands from the command line. In Windows, you can run "cmd"; under Mac and Linux we'll use the Terminal or Console.

On any platform, create a file named HelloWorld.cs with the contents:

// HelloWorld.cs
public class HelloWorld {
    public static void Main(string [] args) {
        System.Console.WriteLine("Hello, World!");
    }
}

How to edit? You can use the Text Editor, gedit, Emacs, etc. We'll use MonoDevelop later, but for now, we just need to create a simple text file.

Now, we'll compile this C# code for the VM using either:

  • .NET, use csc
  • Mono, use mcs

For the rest of this document, we'll just use "mcs" to represent whichever of these you need (eg, "mcs" on Mono, "csc" on .NET).

To compile:

mcs -out:HelloWorld.exe HelloWorld.cs

This will create the file HelloWorld.exe ready to run on the VM. On Windows, you can just type "HelloWorld" or double-click it and it should display the text in a console. On Linux or Mono where the .exe is not associated with Mono, you will need to run it like:

mono HelloWorld.exe

When writing programs, you may get tired of typing the fully specified name of a function, like "System.Console.WriteLine". In C# you can use the form "using XXX;" to include everything in that "name space":

// HelloWorld2.cs
using System;

public class HelloWorld {
    public static void Main(string [] args) {
        Console.WriteLine("Hello, World!");
    }
}

The file "HelloWorld.exe" can be used as a library in the VM. But you can also compile C# code to be used as a library only. In that way, you don't need a "Main" static method. When you compile to a library, the file will have an extension of ".DLL".

// MyLibrary.cs
public class MyLibrary {
    public static int Answer() {
        return 42;
    }
}
mcs -out:MyLibrary.dll -target:library MyLibrary.cs

To use the library:

// HelloWorld3.cs
using System;

public class HelloWorld {
    public static void Main(string [] args) {
        Console.WriteLine("Hello, World; the answer is {0}", MyLibrary.Answer());
    }
}

And compile the code and library:

mcs -out:HelloWorld3.exe -r:MyLibrary HelloWorld3.cs

Running that gives:

$ mcs -out:HelloWorld3.exe -r:MyLibrary HelloWorld3.cs 
$ mono ./HelloWorld3.exe 
Hello, World; the answer is 42

Calico2

Let's now dive into Calico. First, you'll need the source code if you don't already have it.

Getting Source Code

The calico source code is currently hosted on bitbucket using git.

 http://git.calicoproject.org

You can clone the repository using git (assuming you have a bitbucket account):

 git clone https://USERNAME@bitbucket.org/ipre/calico.git

or if you don't have a bitbucket account you can use:

 git clone https://bitbucket.org/ipre/calico.git

There are a variety of turials online for using git and bitbucket


Contributing Code

Feel free to clone the Calico repository and make improvements. Once completed you can send a pull request to have the changes integrated into the main branch.

Getting Source Code for Calico 1

Calico1 still uses SVN.

For those with write permissions to the SVN Bryn Mawr College source code repository


svn co http://svn.cs.brynmawr.edu/Calico/branches/Calico1 Calico


Developers who have an Bryn Mawr College SVN account should use:

svn co https://svn.cs.brynmawr.edu/Calico-dev/branches/Calico1 Calico


Support Libraries

Please see Calico Download for additional libraries needed to run and develop Calico.

Educational Research

You will also need:

  • mono
  • gtk (and libgtk2.0-cil-dev, for package-config files)

Overview

There are 5 directories in the Calico folder:

  1. bin - contains the startup exe and dll files
    1. bin/Lib - contains the standard Python libraries
  2. languages - contains the language definition files for Python, Ruby, Scheme, etc.
  3. modules - Cross-language modules that can be used by all Calico languages
  4. examples - sample code, broken down by language
  5. Source - the code to build the Calico .exe

Language

See Calico: Language Development

TODO

See NOTES in the Calico download (package or svn).

Screen Shots

Pyjama-010.gif

For more, see CalicoScreenShots

Python and Ruby

Calico allows you to easily jump back and forth between languages. Enter this code in the command box:

def fib(n):
    if n <= 2: return 1
    return fib(n - 1) + fib(n - 2)

Make sure the bottom status line has Python checked, and press the Run! button (or simply hit <enter> when in the command box).

Now, enter this code in the command box (make sure to set bottom status line has Ruby checked).

class Hello_world
  def greet
    puts "Hello World"
  end
end
hw = Hello_world.new
hw.greet

Cross-language Access

In this example, you'll see that you can access code and variables defined in other languages.

Enter the following in the Interactive Command Box:

class PythonClass:
     def hello(self, value):
         print "Python says hello to", value

This defines a PythonClass. To test it out, enter the following in the command box:

pc = PythonClass()
pc.hello("Python")

In the Output Box, you'll of course see:

Python says hello to Python

Now, switch to Ruby mode (bottom line status bar, select Ruby) and enter this in the command box:

pc = python_class().new
pc.hello "Ruby"

This uses the PythonClass (now called python_class). In Ruby, you can create an object by placing the .new after it. You call the method .hello by placing the arguments after the method name (parens are not needed in Ruby).

You will see in the output box:

Python says hello to Ruby

which is Python code running inside Ruby!

While in Ruby Mode, enter:

class Ruby_class
   def hello caller
     puts "Ruby says hello to #{caller}"
   end
end

To see that work, try:

rc = Ruby_class.new
rc.hello "Ruby"

and you'll of course see:

Ruby says hello to Ruby

Finally, switch back to Python Mode, and enter:

import Ruby_class
rc = Ruby_class()
rc.hello("Python")

and you'll see:

Ruby says hello to Python

which is Ruby code running in Python!



Interacting with .NET

The languages of Calico can also interact with .NET/Mono. If you are already familiar with .NET/Mono programs (such as those written in C# or Visual Basic) then you will recognize some of these idioms and names.

As a simple example, let's use the interactive abilities to directly interact with some Windows Forms. In order to do this in Calico, will turn the threaded ability off, so as to talk to the GUI in the same thread as Calico is running in. Let's create a window (called a Form in .NET parlance):

# file: winform.py
import clr
clr.AddReference("System.Windows.Forms")
from System.Windows.Forms import *
win = Form()
win.Show()

Importing the special module named clr is the gateway to interacting with the underlying .NET/Mono subsystem. From the clr module, you can add a reference to any Dynamic Link Library (DLL) so that you can access library functions and objects. In this example, we add a reference to the System.Windows.Forms DLL which contains a library of Graphical User Interface (GUI) objects. We then can create a Form, save it in a variable named win, and call the form's Show() method.

If you'd like to give the window a name, enter this in Calico's interactive command box:

win.Text = "This is the Window Title"

These windows will go away when you close Calico, or you can close them manually.

Developing a Language for the DLR in the DLR

This section needs to be revised for Calico2

Python and Ruby are defined to interact as above by taking advantage of the Dynamic Language Runtime (DLR). To further show this off, here is an example of defining a new language, much like Lisp, called SymPL written in Python using the tools of the DLR:

  1. lexer.py - the lexer
  2. parser.py - the parser
  3. etgen.py - expression tree generators
  4. runtime.py - runtime helpers (e.g., lookup, import)
  5. test.py - the Read Eval Print Loop

Some sample SymPL programs:

  1. test.sympl - function tests
  2. ops.sympl - operator tests
  3. lists.sympl - list tests

Writing Fast Module Code Once

Perhaps the nicest aspect of the DLR is that you can develop code (in CSharp, for example) that is "compiled" and used directly. Such can be imported and used by any language in the DLR suite as if it were written in that language. For example, consider this simple example:

// file: Testing.cs
public class Point {
  private int _x;
  private int _y;
  public Point(int x, int y) {
	_x = x;
	_y = y;
  }
  public int x {
	get { return _x; }
	set { _x = value; }
  }
  public int y {
	get { return _y; }
	set { _y = value; }
  }
  public string __repr__() {
	return "<Point at (" + _x + "," + _y +")>";
  }
}

This can be compiled in Mono:

gmcs Testing.cs -target:library

or put into a Project in Visual Studio, and compiled into a library.

You should then put the resulting Testing.dll somewhere will Calico can find it (either put in the same directory with the calico.exe, or put it in a directory and add the path of the directory to Python's sys.path):

import sys
sys.path.append("/path/to/folder")

Finally, you can use it in Calico:

>>> import clr
>>> clr.AddReference("Testing")
>>> import Point
>>> Point
<type 'Point'>
>>> p = Point(1,2)
>>> p
<Point at (1,2)>
>>> p.x
1
>>> p.x = 9
>>> p
<Point at (9,2)>
>>> 

Creating Interactive Programs and Graphics for the Web

Theoretically, once you have a working program in Calico, you can save the program to run on the Web in a manner very much like Flash applications. The resulting program can (possibly) be run in a browser using Silverlight/Moonlight. Need to explore this.

Troubleshooting

If you have any trouble, find bugs, or want to make a feature request, please do that at:

calico.codeplex.com/WorkItem/