Command-line tools
riSim Studio user manual
risim lists, compiles, and simulates the testbenches of a project from a terminal, and manages riSim’s license and versions.
Installing the command-line tools describes how to install it.
risim [--color <when>] [--progress <when>] <command> [<options>]
risim --help lists the commands, risim <command> --help describes one, and risim --version prints the version.
Testbench commands
| Command | What it does |
|---|---|
risim list |
Shows the detected testcases. |
risim compile |
Compiles the source files and prints errors and warnings. |
risim simulate <pattern>… |
Compiles, then simulates the testcases that match the patterns. |
risim results |
Shows the last result of every testcase, with the file of its output. |
They work on the project in the current directory, with the same testcases, compiled libraries, and results as VS Code.
Their options follow the command, as in risim list --workspace my_project:
--workspace <dir>: the project’s directory, instead of the current directory.--config <file>: the configuration file, instead ofrisim-config.tomlin the project’s directory.--isolated: runs riSim in this command’s own process (the shared and the isolated riSim).-j <n>,--jobs <n>(compile,simulate): runs at most<n>compiles and simulations at once.--threads cores|smt|<n>(simulate): limits the number of simulation threads to the number of physical cores (cores, the default), logical cores (smt), or<n>threads; the plan limits them too.--require-license(simulate): fails before compiling if riSim runs on the free plan (requiring a license).
Patterns match testcase names, <library>.<testbench>.<testcase>, with *, ?, and […], ignoring case (testcase names).
Quote them to prevent expansion by the shell:
risim simulate 'my_tests.tb_uart.*'
Shared and the isolated modes
By default, the VS Code extension and the command line tools share a riSim hub that coordinates compiles and simulations in the background.
This hub is started automatically, and exits after a period of inactivity.
With --isolated, a command instead runs a riSim hub of its own, which ends with it and which isn’t shared with other command invocations.
This mode is the default when the environment variable CI is set and not empty, as in most CI systems; --isolated=false uses the shared one there.
riSim versions and pinning
Several versions of riSim can be installed side by side. A project can pin the version it is tested with, so that everyone who works on it, and its CI, uses the same toolchain.
Installed versions
The VS Code extension installs its required version of riSim, if it isn’t already available.
Additional version can be installed on the same system; risim toolchain list lists the installed versions, and the default:
$ risim toolchain list
store: /home/me/.local/share/risim
default: latest
1.0.0 (default) self used today
| Command | What it does |
|---|---|
risim toolchain install <version> |
Downloads and installs the newest release that matches the version. |
risim toolchain install --from <archive> |
Installs the version of a release archive, without a network. |
risim toolchain remove <version> |
Removes an installed version, given exactly, such as 1.0.0, unless it is in active use. |
risim toolchain default [<version>] |
Prints the default version, or sets it. |
risim self update |
Installs the newest release, and the risim command that comes with it. |
A version is latest, an exact version such as 1.0.0, or a prefix such as 1.0, which selects the newest installed version that it matches.
latest and prefixes skip pre-releases, which only an exact version selects.
riSim doesn’t check for updates by itself; the extension’s version changes when VS Code updates the extension.
Which version runs
risim runs the version that the first of these selects:
risim +<version> …, as the first argument, such asrisim +1.0 simulate '*';- the environment variable
RISIM_TOOLCHAIN; - a directory override of the current directory, or of the nearest directory above it that has one;
[toolchain] versionin the project’srisim-config.toml(pinning a project);- the default,
risim toolchain default, which islatestunless you set it.
risim toolchain resolve prints which version runs in the current directory, and what selects it, without running or installing it:
$ risim toolchain resolve
riSim 1.0.0 (1.0, selected by the directory override of /home/me/my_project)
The VS Code extension selects the version of a workspace folder in a similar way (riSim versions in VS Code).
Pinning a project
A project pins its riSim version in risim-config.toml:
[toolchain]
version = "1.0"
If no installed version matches, risim downloads and installs the newest release that does, except in offline mode when it was installed with --prefix (CI).
Directory overrides
A directory override pins a directory and everything below it for you alone, without changing the project; this has a higher priority than the project’s pin.
risim toolchain override set 1.0 # the current directory, or: override set 1.0 <dir>
risim toolchain override list
risim toolchain override unset # removes the override of exactly this directory
Offline
When the environment variable RISIM_OFFLINE is set and not empty, riSim downloads nothing: a pinned version that isn’t installed is an error that says how to install it, and risim toolchain install <version> takes the newest installed version that matches.
risim toolchain install --offline does the same for one command.
Cleaning up
riSim removes the versions that aren’t used anymore when
- it installs a version, or
- the extension starts, or
- with
risim toolchain gc
A toolchain version counts as used if it’s the default, the extension’s toolchain, or if it was used in the last 30 days.
CI and unattended machines
This section describes how to install riSim in CI runners, containers, and compute farms, and license management on such machines.
Installing riSim
The installer installs riSim for the user who runs it.
In a container image, install it into a directory of its own instead, and point RISIM_HOME at it:
curl -fsSL https://dl.risim-studio.com/install.sh | sh -s -- --prefix /opt/risim --no-modify-path
export RISIM_HOME=/opt/risim PATH="/opt/risim/bin:$PATH"
With --prefix, riSim doesn’t write to that directory when it runs, and doesn’t download other versions: a project that pins a version that isn’t installed there fails.
riSim then keeps its logs and the machine’s license activation in the user’s own directories (where riSim keeps its files); where the user has no writable home directory, set XDG_STATE_HOME, XDG_CACHE_HOME, and XDG_RUNTIME_DIR to writable directories, such as directories in /tmp.
Offline installs from an archive are available for machines without internet access.
Running testcases
risim simulate --progress never '*'
- Isolated: when the environment variable
CIis set, as in most CI systems, eachrisimcommand runs riSim in its own process, so that jobs that run at the same time as the same user don’t share it (the shared and the isolated riSim). - Output: the results go to the standard output, one line per testcase, and the output of failed testcases follows;
--progress neverturns off the live view, which a CI log doesn’t need.risim resultsprints the last result of every testcase with the file of its output, inrisim-out/. - Exit codes:
risim simulatefails the job when a testcase fails (exit codes). - Caching: riSim keeps the compiled libraries in the project’s
risim-out/. Keeping that directory between jobs, for example in the CI system’s cache, saves compiling the files that didn’t change, as long as the jobs run the same riSim version from the same directory.
License selection
A node-locked seat stays with its machine until the machine is deactivated, so each new CI machine would take another seat.
risim license activate warns about this when the environment variable CI is set and the license is node-locked.
Each new container usually counts as a new machine.
The free plan isn’t permitted for use on virtual machines and containers (physical machines only).
Until Pro is available, a trial is the license for them: it activates one machine at a time, so use it on one runner that stays, or deactivate the machine at the end of each job with risim license deactivate.
Activating with RISIM_LICENSE
Set the environment variables:
RISIM_LICENSE: to the license keyRISIM_ACCEPT_TERMS: to the version of the license terms that you accept;risim --helpshows it for your version of riSimRISIM_MACHINE_NAME(optional): the name under which the license holder sees the machine (1 to 100 character), or the host name if this variable isn’t set
When riSim starts, it activates the machine with this key, unless the machine is activated with it already.
Without RISIM_ACCEPT_TERMS, or with a different version, riSim activates the key only if the terms are accepted on the machine already.
With RISIM_ACCEPT_TERMS set to riSim’s version, the testbench commands record your acceptance on the machine, and don’t point to the terms.
If CI is set, as in most CI systems, each risim command starts riSim afresh, so it uses the key of its environment.
Alternatively, a script can activate the machine itself, with the key hidden from other users on the machine:
printf '%s\n' "$RISIM_LICENSE" | risim license activate - --accept-terms
risim license activate reads neither RISIM_MACHINE_NAME nor RISIM_ACCEPT_TERMS; give it the name with --name <name>, and accept the terms with --accept-terms.
Floating licenses are returned when a simulation ends; the license server removes the machine a few minutes after its last contact.
Deactivate persistent machines, such as a permanent CI runner, with risim license deactivate when you no longer use them.
If the machine reaches the internet through a proxy, set HTTPS_PROXY or ALL_PROXY, and NO_PROXY for exceptions.
Nobody sees riSim’s output when a CI machine activates itself. Make the software privacy notice available to the people who use these machines, as the license terms ask; refer to what activating sends for details.
Requiring a license
On the free plan, or when a license can’t be used, riSim runs with the free plan’s limits instead of failing, which makes a CI run much slower.
To make it fail instead, pass --require-license to risim simulate, or set the environment variable RISIM_REQUIRE_LICENSE to any value except empty, 0, or false.
Before it compiles, risim simulate then checks that riSim runs with a license, and exits with code 3 if it runs on the free plan.
That includes a license that is activated but can’t be used, for example after the end of a subscription.
On a floating license, the check covers only the machine’s activation, not the threads, which riSim gets from the license server for each simulation.
If the license server can’t be reached, the check therefore still passes, but simulations that need a new thread run on the free plan (floating licenses offline).
# RISIM_LICENSE holds the license key, from a secret variable of the CI system, and
# RISIM_ACCEPT_TERMS the version of the license terms you accept.
export RISIM_REQUIRE_LICENSE=1
risim simulate '*'
License, versions, and installation
| Command | What it does |
|---|---|
risim license activate <key> [--name <name>] |
Activates this machine on a license, under a name; - reads the key from the input (licenses). |
risim license accept-terms |
Accepts the license terms of this version of riSim (license terms). |
risim license status |
Prints the plan of this machine, and whether the license terms are accepted, without contacting the license server. |
risim license list-machines |
Lists the machines of this machine’s license (listing the machines). |
risim license deactivate [--machine <id>] |
Deactivates this machine, which frees its seat, or another one of its license. |
risim toolchain … |
Installs, lists, removes, and pins versions of riSim (riSim versions and pinning). |
risim self update |
Installs the newest release of riSim. |
risim self uninstall [--all] |
Uninstalls the command-line tools (uninstalling). |
The risim license commands print one JSON object with --json.
Exit codes
list, compile, simulate, and results:
| Code | Meaning |
|---|---|
| 0 | Everything passed. |
| 1 | Testcases failed, or were cancelled by another client; or the riSim version to run can’t be installed or started. |
| 2 | Configuration or compile errors, a missing configuration file, a connection failure, no matching testcase, or a usage error. |
| 3 | simulate --require-license found riSim on the free plan. |
| 130 | Cancelled with Ctrl-C. |
risim license exits with 0 on success and 2 on an error, or 1 if the riSim version to run can’t be installed or started; risim toolchain and risim self with 0 on success, 1 on an error, and 2 on a usage error.
Environment variables
| Variable | Meaning |
|---|---|
CI |
Set and not empty: the testbench commands run isolated. |
RISIM_REQUIRE_LICENSE |
Set and neither empty, 0 nor false: simulate requires a license, as with --require-license. |
RISIM_LICENSE |
A license key that riSim activates when it starts (CI). |
RISIM_MACHINE_NAME |
The name of the machine that riSim activates with RISIM_LICENSE (CI). |
RISIM_ACCEPT_TERMS |
The version of the license terms accepted for RISIM_LICENSE (CI). |
RISIM_HOME |
One directory for all of riSim’s files (where riSim keeps its files). |
RISIM_TOOLCHAIN |
The riSim version to run (which version runs). |
RISIM_OFFLINE |
Set and not empty: riSim downloads nothing (offline). |
NO_COLOR, CLICOLOR_FORCE |
No colors, or colors also when the output isn’t a terminal. |
HTTPS_PROXY, ALL_PROXY, NO_PROXY |
The proxy for downloads and the license server, and the hosts that don’t use it. |
Troubleshooting
For license problems, see when the license isn’t used; when testcases wait, when all threads are in use. Contact support if that doesn’t solve your problem.
Logs
- riSim itself: the log files of the riSim hub, in a directory per riSim version under
~/.local/state/risim/logs/on Linux and%LOCALAPPDATA%\riSim\logs\on Windows. - A testcase: what its simulation printed, in the file that
risim resultsnames.
risim isn’t found
After riSim: Install Command-Line Tools or the installer, open a new terminal.
On Linux, ~/.local/bin must be on your PATH; the installer’s output says how to add it (installing the command-line tools).
A command fails because another riSim holds the project
A project is used by one riSim hub at a time.
A command with --isolated, the default when CI is set, fails while VS Code or another command runs something in the same project; wait until it is done, or pass --isolated=false to use the shared hub (the shared and the isolated riSim).