Io Programming/Beginner's Guide/Getting Started

Getting Started

Posix Systems

Io is primarily developed on Unix-based systems, most notably MacOS X. As such it is easiest to build and use Io on these systems. Io has been successfully compiled on MacOS X, Linux, and various BSDs and should have no problem compiling on any system that complies to the Posix standard and has a C99 compliant compiler.

Download the source

First you need to download the source. It is recommended to get the code from the git repository:

$ git clone https://github.com/stevedekorte/io.git

Or, you can find the downloads at the following website: http://iobin.suspended-chord.info/

Compile

Now that you have Io downloaded, let's build it! To do that, change to the newly created directory and create a directory to perform the building in:

You will need cmake

$ cd io
$ mkdir build && cd build

From this directory we want to run CMake which will feel out the environment the same way autotools does for other projects and generate the makefiles:

$ cmake ..

This will check which libraries you do and don't have and determines which addons can be built based on what dependencies you do have. If you have libraries installed in non-standard places (such as zlib in /opt/zlib or ~/zlib/) then you will need to run one of CMake's graphical configuration tools and tell it where those are, then configure it again. ccmake is almost always available, cmake-gui is available for major platforms like OS X, Windows and some Linux distributions:

$ cmake-gui ..

To build the IoVM and any addons that can be built from the source and library files that you have on your computer, just run make!

$ make

If you have problems with compilation you may not have all the dependencies you need. Ensure you have your operating system's compiler tools (this is often GCC) are installed, as some versions of Linux do not come this way unless you explicitly tell them to when you are setting up the system.

Install

Wait a while (on a MacBook it takes about one minute) and it should compile everything successfully; you may then install it to your system like so:

$ make install

or

$ sudo make install

And this will put the binaries io and io_static in to the install path (/usr/local/bin for binaries usually, /usr/local/lib for libraries; both may be changed with the CMake configuration tool by changing the install path) as well as libbaselib.dylib, libgarbagecollector.dylib, libcoroutine.dylib and libiovmall.dylib.

NOTE: The CMake scripts Io uses do not currently install the header files for use with embedding, that has to be done manually.

Linux

After installing you may need to configure ld on Linux. Add this line to /etc/ld.so.conf

include /usr/local/lib

Then reconfigure ld(, or add current directory with the newly built Io environment to path):

sudo ldconfig

Confirmed to have worked with Ubuntu 10.10. Please note that your user might not have rights to edit /etc/ld.so.conf - in that case sudo gedit /etc/ld.so.conf might work. More alternatives and discussion here.

Debian, non-default install directories, missing cmake

This recipe (written 20101018) covers installation on Debian 5.0.6, and guidelines for dealing with non-default install directories and what to do if your OS doesn't have an up-to-date version of cmake. $MYIROOT is assumed to be the root of the install tree (for example, in your home directory — but with addition of appropriate su(do) commands this will work for /usr/local and similar non-default system-wide install trees).

Debian 5.0.6 doesn't have a sufficiently recent version of cmake for the current version of Io (wants 2.8, Debian has 2.6). The following commands retrieve and install cmake-2.8.2 (the apt-get commands make sure that any build prerequisites are installed):

  $ sudo apt-get build-dep cmake
  $ sudo apt-get install libssl-dev
  $ cd /tmp
  $ wget http://www.cmake.org/files/v2.8/cmake-2.8.2.tar.gz
  $ tar xzf cmake-2.8.2.tar.gz
  $ cd cmake-2.8.2
  $ ./configure --prefix=$MYIROOT
  $ make
  $ make install

Tidy up:

  $ cd /tmp
  $ rm -fr cmake-*</shell>

Next, for Io you can more-or-less iterate through the generic Linux instructions:

<syntaxhighlight lang="shell">
  $ git clone git://github.com/stevedekorte/io.git
  $ cd io/build
  $ ccmake ..
  [hit 'c' to configure, change CMAKE_INSTALL_PREFIX to
   the value of $MYIROOT, then hit 'g' to generate and quit]
  $ make
  $ make install

Tidy up:

  $ cd /tmp
  $ rm -fr io

If you can't engage with the ldconfig incantations described above, non-standard install locations will need LD_LIBRARY_PATH to include the lib directory in which Io's libbasekit.so etc. are installed.

Start Up!

Io will now be installed and can be started using the command:

io

If you type just io, you will enter the interactive interpreter. To quit the interactive interpreter, press Ctrl-D or type exit.·

NOTE

If you type something after io, it will be interpreted as a filename, even if it is something like --help or --version that should be interpreted as an option.

Finishing Touches

Now we can test the installation to see if everything works as expected.

$ make test

Optionally, you're free to clean up the build directory as well:

$ make clean

Windows Systems

Pre-compiled binaries for Io exist at the Io downloads page, and are presently the recommended way of using Io on this platform. Compiling it yourself is not particularly trivial at the time of writing and requires the use of unix emulation tools such as MSYS or Cygwin.