Multiple Dev Containers Support
Relevant source files
The following files were used as context for generating this wiki page:
Vscli provides robust support for projects containing multiple dev container configurations. This feature allows developers to define different environment setups for the same codebase and switch between them seamlessly during the launch process. The system automates the discovery of these configurations and provides interactive selection tools when ambiguity exists.
Sources: README.md:12-14, src/workspace.rs:114-118
Dev Container Discovery Logic
The core of the multiple dev container support lies in the discovery algorithm implemented within the Workspace struct. The system searches for configuration files in specific locations to mirror the behavior of Visual Studio Code.
Search Locations
The application scans the following paths relative to the workspace root:
- Direct Root: A
.devcontainer.jsonfile located directly in the root directory. - Standard Directory: A
.devcontainer/devcontainer.jsonfile. - Subdirectories: Any
devcontainer.jsonfiles located exactly one level deep within the.devcontainer/folder (e.g.,.devcontainer/python/devcontainer.json).
The discovery is performed using the find_dev_container_configs function, which utilizes WalkDir to traverse the .devcontainer directory with a maximum depth of 2.
Sources: src/workspace.rs:114-142
Configuration Discovery Flow
The following diagram illustrates how the system traverses the file system to identify potential dev container configurations.
The diagram shows the sequential check of the project root followed by a shallow crawl of the .devcontainer directory.
Sources: src/workspace.rs:120-145
Selection and Resolution
When multiple configurations are discovered, the Setup module handles the resolution process based on the user's provided arguments and the current environment.
Detection Strategies
The Setup::detect function determines which configuration to use based on the following precedence:
- Manual Override: If a specific path is provided via the
--configflag, it is used immediately. - Single Match: If exactly one configuration is found, it is selected automatically.
- Ambiguity Resolution: If multiple configurations exist and no override is provided, an interactive selection prompt is displayed to the user.
Sources: src/launch.rs:107-133, src/opts.rs:44-46
Interactive Selection
For interactive selection, vscli utilizes the inquire crate to present a list of DevContainer objects. Each object is displayed using its name field from the JSON configuration, with the file path provided as a fallback.
| Component | Description | Source |
|---|---|---|
DevContainer | Data structure containing config_path, name, and workspace_path_in_container. | src/workspace.rs:11-15 |
inquire::Select | The UI component used to prompt the user for a choice among multiple containers. | src/launch.rs:128-132 |
Display Trait | Implemented for DevContainer to format the selection list entries. | src/workspace.rs:18-26 |
Launch Architecture
Once a configuration is selected, vscli generates a specific URI to trigger the editor's remote development capabilities.
Remote URI Generation
For dev containers, vscli does not simply open the folder. It constructs a vscode-remote:// URI. This involves:
- Path Normalization: Converting paths for WSL if necessary using
wslpath2. - JSON Metadata: Creating a
DevcontainerUriJsonobject containing the host path and the configuration file path. - Hex Encoding: Encoding the JSON metadata into a hex string.
- Final URI: Appending the target container folder to the
dev-container+<hex>prefix.
Sources: src/workspace.rs:163-221, src/uri.rs:36-43
Execution Flow
The sequence below describes the interaction between the workspace detection and the final execution of the editor command.
The sequence diagram details the transition from command-line parsing to the interactive selection and finally the generation of the remote URI.
Sources: src/launch.rs:136-160, src/workspace.rs:163-221, src/main.rs:58-71
History Integration
The history system tracks which specific dev container was used for a workspace. This allows the "Recent" UI to store and reuse the config_path associated with a specific entry, bypassing the detection logic on subsequent launches unless the user chooses to change it.
| Field | Purpose | Source |
|---|---|---|
workspace_name | Name of the root folder. | src/history.rs:24 |
dev_container_name | The name defined inside the selected devcontainer.json. | src/history.rs:26 |
config_path | The specific path to the JSON file used for that session. | src/history.rs:30 |
Sources: src/history.rs:22-35, src/main.rs:73-81
Conclusion
The Multiple Dev Container support in vscli provides a flexible way to manage complex development environments. By mirroring the standard VS Code discovery paths and providing an interactive TUI for selection, it ensures that developers can manage multiple environment definitions within a single repository without manual path configuration.