Running Idio

Idio is started like many scripting languages with:

.../idio [Idio-args] [script-name [script-args]]

where arguments to Idio must come before any script name or arguments to the script as, both in essence and in practice, the first argument that isn’t recognised as an Idio argument will be treated as the name of a script. --hlep beware!

The script is searched for on IDIOLIB, a regular Unix :-separated list of directories. The use of IDIOLIB is probably more complicated than it should be, see below.

Idio Arguments

Idio accepts a few arguments with --help giving an up to date list.

For users, the useful arguments are:

--load <NAME>

evaluate load NAME and continue processing arguments

--version

print the version number and quit

--help

print the argument help information and quit

For developers (of Idio), the useful arguments are:

--debugger

enable the debugger (if the session is interactive)

(The debugger is barely useful, even for developers just to get machine state.)

--vm-reports

enable some VM-oriented reporting on a clean shutdown

The reports are created in the current working directory and include:

• vm-constants which is the VM’s constants table referred to by various ci (constants index) entities

• vm-values which is the VM’s values table referred to by various vi (values index) entities

• vm-dasm which is the augmented disassembly of the byte code

• vm-modules which is a long list of top-level names per module including their constants index (vm-constants), value index (vm-values) and whether the name was exported

If you were running a “debug” build you will also get

• vm-perf.log which contains a mix of:

  • Garbage Collections stats by type

  • per function usage stats (when freed or at shutdown)

  • instruction throughput rates

  • memory allocation stats (on shutdown)

Warning

Debug builds on some systems become chronically slowed as calling various time and resource usage interfaces overburdens them.

IDIOLIB

Whatever value of IDIOLIB is supplied in the environment, two possible prefixes may occur:

1. if the actual idio executable looks like .../bin/name then IDIOLIB will be prefixed with .../lib/idio/M.N (where M.N are the major and minor version numbers of Idio)

   This makes the executable “position independent” (assuming you copy the libraries along with it).

2. if the idio command run is a symlink and looks like .../bin/name then IDIOLIB will be prefixed with .../lib/idio/M.N (where M.N are the major and minor version numbers of Idio)

   This allows users to have virtualenv-style working areas separate from the main distribution.

   Note

   There is no other support for virtualenvs at this time.

Attention

Idio allows for both relative directories and empty elements (meaning PWD) in IDIOLIB.

At some point these will be either elided or normalized to absolute directories (based on the initial PWD) to avoid to traditional problem of running unexpected code.

Last built at 2026-01-04T22:40:02Z+0000 from da47fd3 (dev)