Workflow guides6Shell and Host Integration

Container shell behaviour

Wrapper commands can run a single tool and return immediately, but interactive work is usually easier in riscos-shell. The shell is a bash session inside the container, with the current directory mapped from the host and the build environment's tool directories already on the PATH.

Because the shell runs inside a container, startup is slower than a native host shell but faster than starting a new container for every individual command.

Git-root mapping

If the wrapper is started inside a Git repository, it maps the repository root to /riscos-source and restores the current working directory relative to that root. This makes Git commands behave as if they were running from the host checkout while still allowing the environment to use a stable internal project path.

There are some limits. Worktrees and submodules are only reliable when the environment is started from the repository root, because the underlying .git indirections are not always reproduced in the same way inside the container.

Host bridge commands

Host bridge commands make selected host-side behaviour available from inside the container. The most commonly used commands are:

• host-open opens a file or web page on the host;
• host-edit opens a file in the host editor;
• host-run runs a simple non-interactive command on the host;
• host-copy copies standard input to the host clipboard.

These bridges are most useful when editing host files from inside the container, opening generated HTML, or delegating an operation such as a browser launch back to the desktop system.

Opening a build output directory on the host typically looks like this, using the FirstTool project built in First session:

host-open aif32

Opening host file: <host-project-path>/aif32

The same command works for any host-side directory or file, including generated HTML documentation once riscos-prminxml has built it; see Documentation authoring and manual building for that workflow.

host-open reports the resolved host path it opened, so seeing that line (rather than an error) confirms the host bridge is working.

If the preferred editor runs on the host rather than in the container, use:

host-edit prminxml/guide.xml

host-edit is silent on success; the host editor opens with no further output in the container shell. Only mapped files inside the host project tree can be opened this way; a path outside that tree, or one the bridge cannot translate to a host path, fails with Unmappable filename '<name>' not supported.

If a host-side helper needs to run outside the container, use:

host-run uname -a

Darwin myhost 23.0.0 Darwin Kernel Version 23.0.0: ...; root:xnu-... arm64

The exact text depends entirely on the host operating system and version; on a Linux host, for example, it would show a Linux kernel version instead.

For Git-hosted projects, git-open is also useful here. It examines the current repository's configured remote, recognises the hosting site, and opens the repository home page, the current branch, the issue tracker, or the pull or merge request page for the current branch. It uses the same host browser-opening path as host-open.

For example:

git-open

Opening URL: https://gitlab.example.com/group/project

git-open --show source

https://gitlab.example.com/group/project/-/tree/current-branch

git-open --show pr

https://gitlab.example.com/group/project/-/merge_requests/new?merge_request%5Bsource_branch%5D=current-branch

The --show option prints the resolved URL instead of opening it, which is useful for checking what git-open would do before it opens a browser window.

Clipboard flow

The environment also provides host-copy so that text can be piped to the host clipboard. The commands xsel and xclip are emulated inside the environment for the same purpose, which helps tools that already expect those Linux clipboard commands.

For example:

printf "Build completed" | host-copy

host-copy is silent on success; the text is on the host clipboard once the command returns, ready to paste outside the container.

Limitations

Host bridge commands do not provide a full interactive tunnel back to the host. For example, host-run does not behave like an interactive shell, and output from host commands appears through the terminal bridge rather than as data that can be redirected inside the container pipeline.

If host file opening or editing fails unexpectedly, an outdated Docker setup is often the first thing to suspect. Check the running image version against ROBUILD_DOCKER_VERSION, and see the version-pinning guidance in Installation for how to select a known-good image explicitly.

For host-run, recognised file arguments are often mapped back to host paths automatically, but the wrapper cannot understand every possible option syntax. Treat it as a convenience for simple host commands rather than as a general-purpose host shell.