mc2

Provides user configured development environments.

An continuation of ooxi/mini-cross.

Configuration

Config Locations

Config files name be placed into the one of the following locations relative to the work directory:

• <machine>.yaml
• .mc/<machine>.yaml
• .mc/<machine>/<machine>.yaml

If machine name is not provided, machine name will default to 'mc'.

Additional lookup paths for machines can be defined in .mc2aliases.yaml, wich contains a map from machine name to relative path of alias file.

my-custom-machine: ../custom-toolchains/brainfuck

User Config

Mutible user config can be included to mount custom volumes, declare environment variables and publish ports.

Config will be loaded from the following paths and merged into one:

• ~/.mc2config.yaml
• ~/.config/mc/config.yaml
• ./.mc2config.yaml
• ./.mc/.mc2config.yaml

publish:
   - 8080:80  # (3)
   - 8443:443
volume:
   ./my-dir:/data   # (4)
env:
   MY_VAR: Hello Word   # (4)

Environment Config

---
base: ubuntu:22.04	# (1)
install:
 - nodejs   # (2)
 - npm
publish:
 - 8080:80  # (3)
 - 8443:443
volume:
   ./my-dir:/data   # (4)
env:
   MY_VAR: Hello Word   # (5)
---
#!/bin/bash

cargo install mc2	# (6)

The configuration file contains two sections: first a YAML frontmatter section followed by an optional shell script. Splitting the configuration into a declarative and an imperative section enables describing common operations with minimal boilerplate while still allowing arbitary actions.

1. base describes the Docker image to be used as starting point for further setup.
2. install contains a list of packages to be installed from the distribution's package manager
3. publish contains a list of [<host_ip>:]<host port>:<container port> declarations describing port forwarding from host to container
4. volume contains a list of <host port>:<container port>[:<otps>] declarations
5. env contains a map of <key>: <value> declarations
6. shell script containing arbritrary commands to be executed while creating

Since mini-cross needs to know how to install packages on a certain distribution, not all Docker images are supported as base images. Current support includes:

• Alpine (Not working atm)
• Arch Linux
• Debian
• Fedora
• OpenSuse (Tumbleweed and Leap)
• Ubuntu

CLI

There two ways of invoking mini-cross

1. The command invocation
2. The shell invocation

While technically similar, they provide for different use cases. The first allows to run individual commands inside the development environment while remaining attached to the host shell. The second changes the point of view to the inside of the development environment so that multiple commands can be executed while attached to the same container.

Therefore the command invocation is more suitable for scripted usage while the second is crafted toward comfort for interactive use.

Command invocation

mc2 --help

When using mini-cross with command invocation, a machine has always to be specified. The machine determines where to look for the mini-cross configuration and allows for multiple configurations in the same project. The special machine _ is the default machine (most useful for shell invocation though).

This command will start the referenced machine and execute the command using the default docker entry point (most likely a bash shell).

Shell invocation

mc2 [<machine>]

Invoking mini-cross without additional commands is referred to as shell invocation because the development environment will stay attached to the current shell. Multiple commands may now be executed inside the same container, which can be quit using the exit command (assuming the container uses a shell like bash as docker entry point).

Since the shell invocation does not use arguments, the machine name can be omited and _ (the default machine) will be assumed.