Command Dispatch

How bulker routes commands at runtime, from shimlink invocation to container execution or host binary handoff.

Dispatch flow

When you type a shimlinked command (e.g., samtools view file.bam):

1. argv[0] detection — The OS invokes the shimlink, which is a symlink to the bulker binary. Bulker reads argv[0] and sees samtools instead of bulker.
2. BULKERCRATE lookup — Bulker reads the BULKERCRATE environment variable to identify the active crate.
3. Manifest load — The cached manifest YAML is loaded from ~/.config/bulker/manifests/.
4. Command lookup — Bulker finds the matching PackageCommand entry in the manifest.
5. Container command construction — Bulker builds the docker run or apptainer exec command with volumes, envvars, user mapping, and auto-mounted argument paths.
6. Spawn with signal forwarding — The container process is spawned as a child process. Bulker forwards signals (SIGINT, SIGTERM) to the container.

Containerized commands

Shimlinks point to the bulker binary. When invoked, bulker constructs the full container command:

• Docker: docker run --rm with -v volume mounts, -e environment variables (all host vars by default, or only the allowlist with --strict-env), --user mapping, and --network host (if configured).
• Apptainer: apptainer exec with --bind mounts. With --strict-env, adds --cleanenv and passes allowlisted vars via --env.

File path arguments are auto-detected and their parent directories are mounted into the container automatically.

Host commands

Host commands are native binaries included in a crate via host_commands in the manifest.

• Strict mode: The shimlink directory contains symlinks pointing directly to the resolved host binary path (resolved via which at activation time). Because the real binary path is the symlink target, tools like Python’s venv detection work correctly.
• Non-strict mode: No shimlink directory entry is created. The command is found directly on the preserved PATH, which is appended after the shimlink directory.

Interactive variants

Prefixing a command name with _ (e.g., _samtools) triggers interactive/shell mode:

• Docker: Uses bash as the entrypoint (TTY flags are auto-detected).
• Apptainer: Launches an interactive shell session.

Environment variables used during dispatch

Variable	Purpose
BULKERCRATE	Identifies the active crate (e.g., databio/pepatac:1.0.13). Set at activation time.
BULKERCFG	Path to the bulker config file. Used to load engine settings and templates.
BULKER_PRINT_COMMAND	When set, prints the generated container command instead of executing it.
BULKER_STRICT_ENV	When set to 1, containers use a clean environment. For Docker: only allowlisted vars get --env flags. For Apptainer: adds --cleanenv then passes allowlisted vars via --env NAME=VALUE.
BULKER_EXTRA_ENVVARS	Comma-separated list of additional env var names added to the --strict-env allowlist. Only has effect with BULKER_STRICT_ENV=1.
BULKER_EXTRA_DOCKER_ARGS	Additional raw arguments appended to docker run.
TMPDIR	Controls where shimlink directories are created. Defaults to /tmp. Set to a writable path if /tmp is unavailable.