COBLE: Quick Start¶

Functionality Overview¶

An overview of the main functions, using an environment called codex:

To create environments¶

# Conda is the default
coble build --recipe my-recipe.cbl --env codex
# Or for a conda or singularity environment
coble build --recipe my-recipe.cbl --env codex --containers docker,singularity

To use environments¶

Conda¶

# Activate
conda activate codex
# Check the creation details (time, person, recipe)
coble me
# Check the validation if implemented
coble validate

Docker and Singularity (from the local build)¶

The containers have the environment ready activated when they load. Docker should have a working directory mapped to /workspace.

# Docker
docker run --rm -it \
-v .:/workspace -w /workspace \
cbl-my-env
# Singularity
singularity shell cbl-codex.sif

To recreate environments¶

For conda: the build will have created a file codex_export.cbl with the versioned files:

coble build --recipe codex_export.cbl --env codex-mirror

The docker build will have created a Dockerfuile that can be rebuilt directly, or of course an image that can be used directly as above.
The Dockerfile includes a commented header section that shows the build args used so it can be rebuilt directly from docker - an example below

# This Dockerfile was generated by coble with the following build args:
# Started at 2026-03-01 10:26:25"
# User: ralcraft"
# ------------------------------
# RECIPE_CBL=codex.cbl
# BUILD_TAG=codex
# GITHUB_PAT=$GITHUB_PAT
# VAL_FILE=recipes/papers/ProvGigaPath/validate/validate.sh
# VAL_FOLDER=recipes/papers/ProvGigaPath/validate
# CODE_SOURCE=local
# ------------------------------
# Instructions to build the image:
# 1. Set the above environment variables in your terminal (or export them in your shell profile)
# 2. Run the below command ensuring to amend paths to your location correctly:
# ------------------------------
################### GENERIC COBLE DOCKERFILE ############################
# Build with local recipe:
#
#    docker build -f "$DOCKERFILE" \
#    --build-arg RECIPE_CBL="$INPUT_RECIPE" \
#    --build-arg BUILD_TAG="$ENV_NAME" \
#    --build-arg GITHUB_PAT="$GITHUB_PAT" \
#    --build-arg VAL_FILE="$VAL_FILE" \
#    --build-arg VAL_FOLDER="$VAL_FOLDER" \
#    --no-cache \
#    -t "$IMAGE_NAME" .

The Four Functions¶

Build: Create or update an environment from a recipe file.

coble build --recipe my-recipe.cbl --env my-env

--- Optional arguments: - --alias : Can pass in an alternative solver to conda eg mamba or a path. - --containers : default is conda, comma delim list of containers. - --rebuild: Clean and rebuild the environment from scratch. - --skip-errors: continue building even if some packages fail to install. Default behaviour os to exit and promt you to fix. - --include-r-forge: include R-Forge when looking for packages as URLs through find: - by default it is turned off as it is slow. - --debug: keep all interim log files.

Freeze: Freeze an existing environment into a coble recipe file.

coble freeze --frozen my-frozen-env.cbl --env my-env

--- Optional arguments: - --env: Active environment is frozen if not specified. - --debug: keep temporary files for each package manager for debugging.

Network: Create a network dependency graph

coble network --frozen my-frozen-env.cbl --env my-env

--- Optional arguments: - --env: Active environment is frozen if not specified. The output is to the same folder as the input, frozen, called:
- <env>_network_interactive.html : an interactive dependdency explorer - <env>_dependencies.txt : the data for the dependency viewer - <env>_network_stats.txt : some info on the network

Template: Generate a template recipe file to start from.

coble template --recipe template-recipe.cbl --flavour basic

A coble recipe file¶

A simple recipe could look like this (my-recipe.cbl):

coble:
  - environment: coble-env-versions
channels:
  - bioconda
  - conda-forge
languages:
  - python=3.13.1@conda-forge
  - r-base=4.3.1@conda-forge
conda:  
  - pysam
r-package:
  - ggplot2
pip:
  - NumPy

Additional Information¶

The environment (--env) can be either a name or a folder path. COBLE will automatically use --name or --prefix as appropriate.
If you specify more than one R or more than one Python version in the language block, COBLE will complain and refuse to continue.
There is a find directive that initiates a search across pypi, cran, bioconductor and github for a package source.