Installing Io Addons

Io is an interesting programming language. I had not planned to learn a new language in 2024. Then, in a quiet moment, I reached for Seven Languages in Seven Weeks by Bruce Tate. It is an older book, published in 2010 and I know some of the languages described there. I like studying programming languages. Playing with basic concepts without the need to finish larger tasks is relaxing. It should be an easy read.

The Io Language
Io "is a dynamic prototype-based programming language." It seems more or less dead since 2010, basically since the book mentions it. Its site states "actively developed until 2008". While there are a few updates from last year, the latest available build for Windows dates to 4th of December 2013, more than ten years ago. Much of Io is written in C and one should be able to build it from source using cmake. While I like the retro character of plain C, similar to old Pascal, I am un-experienced in the C ecosystem. I am using Windows and building C has been proven to be a hassle due to dependencies and compiler inconsistencies. So I went with the provided Windows build.

Io is prototype based, like JavaScript and looks different than your usual C-styled languages. The core library iovm comes with a unit testing framework. The UnitTest is an old-school xUnit, e.g.

FizzBuzzTest := UnitTest clone do (

  setUp := method(
    super(setUp)
    self fizzbuzz := FizzBuzz clone
  )

  // ...

  testFizz := method(
    result := fizzbuzz single(3)
    assertEquals("Fizz", result)
  )

  // ...

  testTo5 := method(
    result := fizzbuzz upto(5)
    assertEquals(list("1", "2", "Fizz", "4", "Buzz"), result)
  )

)

The corresponding Fizz Buzz is

FizzBuzz := Object clone do (

  single := method(n,
    if (n % (3 * 5) == 0, "FizzBuzz",
      if (n % 5 == 0, "Buzz",
        if (n % 3 == 0, "Fizz",
          n asString)))
  )

  upto := method(limit,
    Range 1 to(limit) map(n, single(n))
  )
)

This could be written more concise, but such was my first Io code. I should probably do a Prime Factors, too. It seems that I am obsessed with unit tests, as it is usually the first thing I look for in a new language, e.g. Scheme or Assembly. If you want to know more about Io, read the guide or the second chapter of Seven Languages in Seven Weeks. While the language is dormant, it will change the way you see programs - exactly as Bruce promises.

Io Addons
The Io distribution contain a bunch of extensions collected under the IoLanguage GitHub organisation. Many extensions are wrappers around well tested C libraries, but these "may not be installed on your system already." And this is probably the reason why the Windows distribution only contains 28 out of the 80+ available addons. While I ignore MySQL or graphics library wrappers, basic functions like socket communication or regular expressions would be nice. There is Eerie, the Io package manager, which should be able to deal with compiling addons, but its installation fails on my system - because of a dependency that needs a missing C library (recursion ;-). Then I try to add addons manually. It is the main purpose of this post to explain how it can be done.

Let me start with some general structure of Io addons: Installed or bundled addons are located in %IO_HOME%\​lib\​io\​addons and share the same folder structure as expected by Io's AddonLoader. Assume an addon named Foo, then the following folders and files (could) exist:

• _build: Several folders with the build results of C code, mostly empty.
• _build\dll\libIoFoo.dll and libIoFoo.dll.a: Compiled C code, its dynamic library and GCC import library file.
• _build\headers: Empty for bundled addons, but should contain the C headers of exported functions, i.e. the Io*.h files from source.
• bin: Starter scripts for addons which are command line tools. e.g. Kano.
• io\*.io: Main Io source code, i.e. new prototypes. There is at least a Foo.io.
• samples\*.io: Optional sample code.
• source\*.c|h: C source code, at least IoFooInit.c. The empty folder must exist.
• tests\correctness\run.io and one or more *Test.io: Unit tests, the run.io runs all tests in the current folder.
• tests\performance\*.io: Optional performance tests, sometimes with run.io.
• depends file: a list of other prototypes (or addons) this addon depends on.
• protos file: a list of all prototypes this addon provides.

Addons are activated in Io by using the prototype with the name of the addon. In an Io REPL or script, Foo will find the addon and import it making all its prototypes available. This works for all provided prototypes given the manifest (i.e. the protos file) is correct.

Io Package Management: Eerie
While working with the different types of addons, see this and the next article, I seem to have reverse engineered much of Io's build and package infrastructure ;-). Knowing about it upfront would have helped. Eerie is the package manager for Io. Unfortunately its installation failed on my system - and it seemed way too complicated for me because it created multiple environments, much like Python's virtualenv. Its documentation is "coming soon", and not helping. Some addons on GitHub are Eerie packages and miss necessary files like protos. While sometimes these files are still there - an oversight as it seems, Eerie packages contain other files:

• package.json is the Eerie manifest. It contains the description of the package and its dependencies. This file is useful.
• eerie.json is some kind of manifest, used in the Eerie Package Storage Database. Only two addons have it and the database is empty.
• build.io will "rewrite AddonBuilder to represent a receipt for your package." Most addons have this and it contains information about needed native libraries and transitive dependencies.

It seems that Eerie's PackageInstaller extractDataFromPackageJson() method creates the protos, depends and build.io files from package.json. I will have to do this by hand. Unfortunately some package.json are incomplete and some miss important information.

Now I explain the installation of several addons with different needs and increasing difficulty using concrete examples:

Addons without Any Native Code: Kano
There are some addons without any C source, e.g. CGI, Continued​Fraction, Rational and integrations like Bitly, Facebook, etc. All of these are included in the distribution. When looking for addons, I checked all addon repositories for ones without native code and found Docio, Eerie and Kano. I guess these were left out because they are part of Eerie. Let's look at Kano. Kano is a simple Make/​Rake inspired tool for Io. It uses a Kanofile to declare tasks. Let's get it running:

> cd "%IO_HOME%\lib\io\addons"
> git clone https://github.com/IoLanguage/kano
Cloning into 'kano'...
> io -e "Kano println"
Exception: Object does not respond to 'kano'

This is broken. io -e "<expression>" runs Io and passes the command, much like Ruby does. Passing the prototype name asks Io to load it and it is not found. By Io convention prototypes start with an uppercase letter while instances (and fields and variables) start with a lowercase one. Somewhere (in the source of Importer maybe) I read that the names must match for importing. Also this is one of only three repositories which lowercase name, i.e. docio, eerie and kano. Tip: Watch out for addon repository names matching the primary prototype.

> ren kano Kano
> io -e "Kano println"
Exception: unable to read file '...\lib\io\addons\Kano\depends'

Ah progress. It is missing the depends and protos files I mentioned earlier. It has a package.json instead:

{
  "version": 0.1,
  "author": "Josip Lisec",
  "description": "Rake-like utility for Io.",
  "readme": "README.textile",
  "category": "Utility",
  "dependencies": { },
  "protos": ["Kano", "Namespace", "Namespaces", "ObjectDescriber"]
}

No dependencies and four prototypes.

> touch Kano\depends
> echo Kano Namespace Namespaces ObjectDescriber > Kano\protos
> io -e "Kano println"
Exception: Unable to open directory ...\lib\io\addons\Kano\source

Progress again but why does Io look for C sources? In some addons, I see an empty source folder with a .gitisdumb file in it, to keep the folder in version control. Maybe it is needed.

> mkdir Kano\source
> io -e "Kano supportedFiles println"
list(make.io, Kanofile, kanofile, Kanofile.io, kanofile.io)

Nice, no error. Kano works. To be fully useable, there are a few more things to fix:

1. Kano is a tool, it comes with bin/kano starter script. Each starter script needs a Windows version, i.e. a bin/kano.bat which calls the original starter script,

   io "%IO_HOME%\lib\io\addons\Kano\bin\kano" %*

   And both scripts need to be in the PATH. The easiest way is to copy kano.bat to %IO_HOME%\bin, which contains io.exe.
   
   
2. Kano offers kano [-T|V|help|ns] [namespace:]taskName arg1 arg2... as help. -T lists all tasks defined in the local Kanofile and -V shows its version. At least it tries to do that. It calls Eerie to get its version. Now Eerie depends on Kano and Kano depends on Eerie, and I do not have Eerie, this is all bad. If you want everything to work, you can replace line 44 in Kano's Namespaces.io:

    V := option(
      """Prints Kano version."""
   -  version := Eerie Env named("_base") packageNamed("Kano") \
                       config at("meta") at("version")
   +  version := File thisSourceFile parentDirectory parentDirectory \
                      at("package.json") contents parseJson at("version")
      ("Kano v" .. version) println)

3. Much later I noticed that Kano's package.json does not have a name field. This is needed for Docio to generate the documentation. Sigh. (Here is my patched Kano.)

Follow along in part two.

Slimming VMware Player Installation

Recently I had to play around with some VMware images. After installing the VMware Player (current version = 2.5.1) I had problems with connecting my image to the network. Finally I managed, but I learned it the hard way. IMHO the best way to run a virtual network is bridged using a static IP address for each image. (Just make sure the addresses are all in the same sub-net.) This description applies to Windows operation systems.

Network Connections
VMware Player installs two additional network adapters on the host computer.

• Virtual switch VNNet1 is the default for Host Only networking. Using this network adapter virtual machines can't access the outside network. - Disable it, we don't need it!
• Virtual switch VNNet8 is the NAT switch. Here virtual machines can access the outside network using the host’s IP address. - Disable it, we don't need it!
• Just make sure the VMware Bridge Protocol is enabled for your main network adapter. So virtual machines can access the outside network using their own IP addresses.

Services
I noticed that VMware Player also installs several services which I don't like. Especially when the purpose of some VMware services is unclear.

• vmnat.exe is the NAT service. It is needed for VNNet8. Deactivate it, we don't need it!
• vmnetdhcp.exe is a virtual DHCP service. It's only needed if you use DHCP in your images and do not have a real DHCP server set up and running. Deactivate it, we don't need it for static IP addresses.
• vmware-authd.exe is the authorisation service and controls authentication and authorisation for access to virtual machines for non admin users. Probably you don't need it, so deactivate it.
• vmware-ufad.exe is the host process for Ufa Services. It's not active by default, so leave it deactivated.
• vmware-tray.exe is probably the same as hqtray.exe, but it was not installed on my computer.
• hqtray.exe is the host network access status tray. Unless you want to see network traffic in the taskbar, deactivate it. (This is not a regular service, it is started at system start-up. You have to delete it from the registry, it's key is below HKEY_LOCAL_MACHINE\ SOFTWARE\ Microsoft\ Windows\ CurrentVersion\ Run.

If you have to use Host Only or NAT, leave the corresponding network and service settings alone.

WTF
And watch your back, you can't connect from the virtual image anywhere when your local firewall is dropping all unknown traffic ;-)

Eclipse Europa GlassFish Problems

OK, it's my fault. I do not RTFM, but usually try out the stuff immediately without much reading.

Recently I wanted to check out the GlassFish application server (version 2) together with Eclipse (version 3.3 or Europa) and encountered some problems. Here is my minimalist conclusion:

• Download the latest version of GlassFish, in my case it was 2ur2-b04.
• Read the documentation, there is more to do than just unpack the archive and start it.
• Do it! Go there! Read it!
• java -Xmx256m -jar glassfish-installer-v2ur2-b04-windows.jar is obvious...
• Now comes an important part: Probably you do not want GlassFish to live in the /glassfish-folder, I would rather have it in something like /glassfish-2ur2-b04 for this version. So
• Copy and/or rename the newly created and filled directory glassfish to your liking. This has to be done before you continue! You can't do that later.
• Go into this folder and execute lib\ant\bin\ant -f setup.xml as shown in the GlassFish documentation. This should finish the installation.

For the integration of GlassFish with Eclipse, there is an excellent description on the GlassFish site. Unfortunately, there are still some holes in it (and of course I did not read it in the first place, remember, I do not RTFM :-)

• To create a new server in Eclipse JEE perspective, use the "New Server" wizard in the "Server" tab. But where is GlassFish?

• So click on the "Download additional server..." link
• When working behind a proxy, this may take long and not list GlassFish in the end. The reason is that an https-Proxy has to be configured in Eclipse.

• Now you are able to create the new server. If the wizard tells you that it can't find some appserv-rt.jar, then you forgot to call ant -f setup.xml during installation of GlassFish (as listed above).

• This is because GlassFish comes with it's jars in the pack200 format, which do not end with .jar but with .jar.pack.gz and are unpacked during installation. (Manually unpacking unpack200 lib\appserv-rt.jar.pack.gz lib\appserv-rt.jar does not help here. You need to call the set-up...)
• Start the server. If you get error messages that the system can't find some path and the start-up fails with a timeout after a minute then you did not move/rename the /glassfish-folder to the desired destination before calling the setup.
• This is because GlassFish has his scripts like asadmin.bat contain absolute paths written during setup, e.g.

  setlocal
  call "C:\download\glassfish\config\asenv.bat"
  set Path=%AS_INSTALL%\bin;%AS_ICU_LIB%;%PATH%

• Enjoy the finally starting GlassFish, serving it's index page at port 8080:

Now is it GlassFish 2.2 or Sun's Application Server 9.1? ;-)