cylc-admin

Getting Started with Cylc Development

Development Setup

  1. Say Hi On The Cylc Developers Chat.

  2. Install System Dependencies:

    Note: We recommend developing in a Conda environment, although it is possible, though less flexible, to install the required system dependencies and work in Python virtual environments.

    Use whatever Conda client you prefer, micromamba is the most performant.

    This command will give you a Conda environment containing all the things you might need for Cylc development:

    conda create -n cylc-dev python pip configurable-http-proxy graphviz nodejs yarn shellcheck

    To ensure your Conda environment is automatically activated across a distributed network, create a pair of activate/deactivate files:

    $ conda activate cylc-dev
$ echo "export CYLC_ENV_NAME=$CONDA_DEFAULT_ENV" > $CONDA_PREFIX/etc/conda/activate.d/cylc.sh
$ echo 'unset CYLC_ENV_NAME' > $CONDA_PREFIX/etc/conda/deactivate.d/cylc.sh

  3. Fork & Clone

    On GitHub, create a fork of any of the Cylc repositories you want to work on and create a local clone of them (i.e, git clone git@github.com/<yourname>/<repo>.git).

    Please star https://github.com/cylc/cylc-flow and https://github.com/metomi/rose/ :)

  4. Install Python Projects

    Install any Python projects you have just cloned into your Conda environment.

    Install cylc/cylc-flow and optionally:

    pip install -e "path/to/repo[all]"

    You only need to repeat this pip install command when certain project files are modified:

    • setup.py
    • setup.cfg
    • pyproject.toml
    • MANIFEST.in

    Note: You can use uv pip as a stand-in for pip.

  5. Install and configure cylc/cylc-ui (optional)

    cd path/to/cylc-ui
conda activate cylc-dev
yarn install
yarn run build  # create your first build

    The Cylc UI Server comes with a bundled version of Cylc UI. To use your personal build add the following to your Jupyter configuration:

    # ~/.cylc/hub/jupyter_config.py
c.CylcUIServer.ui_build_dir = '~/cylc-ui/dist'  # path to build

    Then launch the UI:

    ```bash

    standalone (single-user mode, good for development)

    cylc gui

    via Jupyter Hub (multi-user mode)

    cylc hub

    You will be asked to log in with your desktop credentials if you have not

    done so before.

  6. Contributor License Agreement

    Read the CONTRIBUTING.md file and add your name to it with your first commit.

    You will have to do this for each Cylc / Rose repository. Note repositories may use different licenses. ```

Running Your First Workflow

# clone the workflow into ~/cylc-src
cylc get-resources tutorial/cylc-forecasting-workflow

# install the workflow into ~/cylc-run and start it
cylc vip cylc-forecasting-workflow

# watch it run
cylc tui  # in-terminal
# OR
cylc gui  # in-browser

# stop it
cylc stop cylc-forecasting-workflow

# uninstall it from ~/cylc-run
cylc clean cylc-forecasting-workflow

Versions & Branches

Cylc projects use semantic versioning, e.g: for the version 8.1.2:

Cylc projects are all pinned to the minor version of cylc-flow, e.g:

This tight coupling prevents unintended combinations of Cylc components being installed into the same environment whilst allowing them to be installed in a modular fashion.

Bugfixes

When we make a minor release, we create a branch with a .x suffix for bugfixes.

E.g. 8.1.x was for bugfixes to 8.1.0. We merge these .x branches back into master.

Raise any bugfixes against the .x branch, the “sync” PR will be automatically created after it is merged.

Supported Versions

The currently supported (i.e. actively developed) versions are documented here.

This site is open source. Improve this page.