Io Programming/Beginner's Guide/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. is almost always available,  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

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  and   in to the install path (  for binaries usually,   for libraries; both may be changed with the CMake configuration tool by changing the install path) as well as ,  ,   and.

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. is assumed to be the root of the install tree (for example, in your home directory &mdash; but with addition of appropriate  commands this will work for  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):

Tidy up:

Tidy up:

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, you will enter the interactive interpreter. To quit the interactive interpreter, press Ctrl-D or type exit.·


 * NOTE

If you type something after, it will be interpreted as a filename, even if it is something like   or   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.