Getting Idio

There are no downloadable packages, you need to build Idio from source. The systems Idio is regularly tested on are listed in Supported Platforms.

There’s a few assumptions:

1. you’re using a C99-capable C compiler

2. you also have objdump [1] installed

3. you’re using GNU make (gmake on BSD platforms)

4. lsof [2] is required for the test suite (a hooky internal version is used on SunOS and OpenBSD)

You may want to use rlwrap with idio when using it interactively.

[1]

objdump seems to be installed alongside the C compiler on modern systems. YMMV.

dwarfdump is used on Mac OS X and is part of the XCode distribution.

[2]

On Alpine Linux both lsof and ps are BusyBox implementations. The test suite requires regular versions. The build requires bash.

# apk add bash lsof procps

Source

The source code is available on GitHub at https://github.com/idio-lang/idio.git.

Building from Source

Filthy casual mode:

git clone https://github.com/idio-lang/idio.git
cd idio
make

make test

The Idio executable is .local/bin/idio.

Two Phases

Please note that there are two phases to the build. The first might only be performed once (until you run make dist-clean or start again from scratch).

Idio wants to know the details of the data types used in your operating system interfaces: is your pid_t an int or a long (or something else)? Idio can figure this out so long as it can run a copy of itself. Cue the bootstrap problem!

The first phase, therefore, builds itself using some generic “about right” values for pid_t etc. which don’t matter because the script it is going to run to generate the correct values doesn’t use them.

Both phases are run, if required, when you run make.

1. build idio using “build-bootstrap” values to run a script which generates correct values in a couple of files

   For those interested, the script is bin/idio-c-api-gen, here, using ext/libc/api/libc-api.c as input. The output is src/libc-api.h and lib/libc-api.idio which align the C and Idio sides of the interfaces.

2. (re-)build idio using correct values

If you type make clean it won’t delete the generated files with the correct values.

If you type make dist-clean it will delete the generated files with the correct values and the next make will simply waste a bit of time re-creating them.

Building

make all should be enough.

Other useful targets include:

• test to run the test suite, see below

• debug to:

  • compile with -g in the usual way for use with gdb

  • enable extra informational debug statements

  • generate some post-mortem VM state files if you pass the --vm-reports flag

• clean – you will probably want to run make clean before and after a “debug” session

Build Install

The output of the build goes into a .local hierarchy at the top-level of the source tree which has the usual bin and lib subdirectories.

You can now run .../.local/bin/idio or put .../.local/bin on your PATH – which is what running the test suite does.

Install

The source tree .local hierarchy is designed to be tarred-up and shifted and should work wherever you leave it:

% (cd .../.local; tar cf - bin lib) | (cd /some/where; tar xf -)
% /some/where/bin/idio ...

(Although the test suite won’t work from there!)

However more specific user and system installations can be performed.

User Install

You can make user-install to install Idio in your XDG-friendly $HOME/.local hierarchy.

make clean-user-install removes Idio from that hierarchy.

System Install

A system install is useful if you want to ssh host scriptname and your portable scriptname starts:

#! /usr/bin/env idio

However, this depends on the default PATH, used by ssh including a directory in which idio is installed. Commonly, you might see:

% ssh somehost env
...
PATH=/usr/local/bin:/usr/bin:/usr/local/sbin:/usr/sbin
...

which doesn’t contain any user-specific directories. This is a PATH compiled into ssh so it is “difficult” to influence.

Idio ought to be packaged and installed by your distro of choice however it’s a wee bit short of that level of popularity.

In the meanwhile, you can make system-install to install Idio in an operating system-specific location.

This location, in general, means two separate trees as library files often go in a directory that isn’t mirrored by the executable pathname and may or may not utilise a multiarch-style component.

You can see where Idio would be installed by looking in the generated src/Makefile.system, here for a Debian 10 system:

% make
...
% cat src/Makefile.system
...
IDIO_SYSTEM_BINDIR              := /usr/bin
IDIO_SYSTEM_LIBDIR              := /usr/lib/x86_64-linux-gnu/idio
...

make clean-system-install removes Idio from that hierarchy.

Warning

This does not work on some operating systems.

In particular, on macOS systems using /System/Volumes/* filesystems, ie. macOS Catalina and later, the default ssh PATH is /usr/bin:/bin:/usr/sbin:/sbin all of which are mounted read-only.

Installing idio in /Applications/... or /usr/local/... is, therefore, relatively pointless.

In practice, a system-install can be done into the /usr/local hierarchy as, if nothing else, it allows you to run:

% ssh machost /usr/local/bin/idio /path/to/scriptname

for macOS systems.

Virtualenvs

Further, it is envisaged that users might use a Python-style virtualenv arrangement where an application-specific bin directory has a symlink to the real idio executable and Idio will prefix the corresponding application-specific lib hierarchy into its IDIOLIB search paths.

Here, suppose we want to use idio from our specialised /tmp/dir hierarchy in which bin/idio is just a symlink into our user-install $HOME/.local hierarchy and, in addition, we want to start out with IDIOLIB having the value /some/where/else:

% make user-install

...

% mkdir -p /tmp/dir/bin
% ln -s $HOME/.local/bin/idio /tmp/dir/bin

% IDIOLIB=/some/where/else /tmp/dir/bin/idio
WARNING: extend-IDIOLIB: /tmp/dir/lib/idio/0.0 is not accessible
Idio> IDIOLIB
"/tmp/dir/lib/idio/0.0:$HOME/.local/lib/idio/0.0:/some/where/else"
Idio>

The first element of IDIOLIB, /tmp/dir/lib/idio/0.0, is derived from the symlink in /tmp/dir/bin and the second, $HOME/.local/lib/idio/0.0, is derived from the executable idio. Both of these executable-specific directories are prepended to IDIOLIB.

Test Suite

Idio’s test suite has several thousand tests which attempt to:

1. generate every possible error

2. probe boundary cases

3. give decent code coverage

   Code coverage doesn’t guarantee the code works it just means that at least something caused the code to be exercised (and it didn’t generate an error).

4. do regression testing of issues

Not all tests pass on all platforms. Let’s caveat that: not all “system” tests pass on all platforms.

All internal, Idio-the-programming-language, tests should pass on all platforms.

The test suite concludes with a series of increasingly baroque “system” tests where they try to provoke various inter-process situations (processes exiting normally, abnormally, being killed whilst standalone, in pipelines etc.) and some operating systems have inconsistent behaviour which hasn’t been accommodated.

SunOS and Debian 10 are repeat offenders, here.

Supported Platforms

Idio is regularly built and tested on a range of platforms (largely virtual machine instances with the exception of Mac OS and Raspbian):

Test Systems

kernel	OS	ISA	bits	compiler
BSD	OpenBSD 7.1	amd64	64	clang 13
BSD	OpenBSD 6.9	amd64	64	clang 10
BSD	NetBSD 9.2	amd64	64	gcc 7
BSD	FreeBSD 13.2	amd64	64	clang 14
Darwin	macOS 14.1	x86_64	64	clang 12
Darwin	Mac OS X 10.15.7	x86_64	64	clang 11
Linux	openSUSE Leap 15.3	x86_64	64	gcc 7
Linux	Ubuntu 22.04	x86_64	64	gcc 11
Linux	Ubuntu 18.04	x86_64	64	gcc 8
Linux	Fedora Linux 39	x86_64	64	gcc 13
Linux	Debian GNU/Linux 11	x86_64	64	gcc 10
Linux	Debian GNU/Linux 10	x86_64	64	gcc 8
Linux	CentOS Stream 9	x86_64	64	gcc 11
Linux	CentOS Stream 8	x86_64	64	gcc 8
Linux	CentOS Linux 7	x86_64	64	gcc 4
Linux	CentOS 6	x86_64	64	gcc 4
Linux	Alpine Linux 3.16.2 (musl)	x86_64	64	gcc 11
SunOS	Oracle Solaris 11.4	i86pc	64	gcc 11
SunOS	OpenIndiana Hipster 2022.10	i86pc	64	gcc 10
SunOS	OpenIndiana Development oi_151.1.9	i86pc	64	gcc 4
BSD	FreeBSD 13.2	arm64	64	clang 14
Darwin	macOS 14.1	arm64	64	clang 15
Linux	Ubuntu 20.04	aarch64	64	gcc 9
Linux	Fedora Linux 39	aarch64	64	gcc 13
Linux	Debian GNU/Linux 12 (RPi 4 B)	aarch64	64	gcc 12
BSD	NetBSD 9.2	i386	32	gcc 7
Darwin	Mac OS X 10.5.8	i386	32	gcc 4
Linux	Debian GNU/Linux 10	i686	32	gcc 8
Linux	CentOS 6	i686	32	gcc 4
SunOS	OpenIndiana Development oi_151.1.8	i86pc	32	gcc 4
Linux	Raspbian GNU/Linux 12 (RPi 3 B+)	armv7l	32	gcc 12
		QEMU
Linux	Ubuntu 20.04	riscv64	64	gcc 9
		WSL
Linux	Ubuntu 18.04 (WSL1)	x86_64	64	gcc 7

Note

WSL2 runs Linux as a true VM so should be no different to the virtual machine examples above.