#!/usr/bin/env bash
#-------------------------------------------------------------------------------
# Copyright (C) 2012-2019 British Crown (Met Office) & Contributors.
#
# This file is part of Rose, a framework for meteorological suites.
#
# Rose is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Rose is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Rose. If not, see <http://www.gnu.org/licenses/>.
#-------------------------------------------------------------------------------
# NAME
#     rose suite-run
#
# SYNOPSIS
#     rose suite-run [OPTIONS] [[--] CYLC-RUN-ARGS]
#
#     # Install and run a Cylc suite in $PWD.
#     rose suite-run
#
#     # As above, but start the suite in simulation mode.
#     rose suite-run -- --mode=simulation
#
#     # Install and run the suite in $PWD, and register it as "my.suite".
#     rose suite-run -n my.suite
#
#     # Install and run suite in "/dir/to/my.suite".
#     # Equivalent to (cd /dir/to/my.suite && rose suite-run).
#     rose suite-run -C /dir/to/my.suite
#
# DESCRIPTION
#     Install and run a Cylc suite.
#
#     Install a suite (in `$PWD`), register it in Cylc using the basename of
#     the configuration directory or the option specified in `--name=NAME`.
#     Invoke `cylc run` on it. Arguments (and options after `--`) are passed
#     to `cylc run`.
#
# OPTIONS
#     --config=DIR, -C DIR
#         Specify the configuration directory of the suite. (default=`$PWD`)
#     --define=[SECTION]KEY=VALUE, -D [SECTION]KEY=VALUE
#         Each of these overrides the `[SECTION]KEY` setting with a given
#         `VALUE`. Can be used to disable a setting using the syntax
#         `--define=[SECTION]!KEY` or even `--define=[!SECTION]`.
#         See also `--define-suite`.
#     --define-suite=KEY=VALUE, -S KEY=VALUE
#         As `--define`, but with an implicit `[SECTION]` for suite variables.
#     --host=HOST
#         Specify a host for running the suite.
#     --install-only, -i
#         Install the suite. Do not run it. Implies `--no-gcontrol`.
#     --local-install-only, -l
#         Install the suite locally. Do not install to job hosts. Do not run
#         it. Implies --no-gcontrol.
#     --validate-suite-only
#         Install the suite in a temporary location. Do not setup any directories.
#         Do not run any jobs. Implies --no-gcontrol. Overrides --install-only and
#         --local-install-only.
#     --log-keep=DAYS
#         Specify the number of days to keep log directories/archives.
#         Do not housekeep if not specified. Named log directories (created by
#         `--log-name=NAME` in previous runs) will not be housekept.
#     --log-name=NAME
#         Specify a name for the log directory of the current run. If
#         specified, it will create a symbolic link `log.NAME` to point to the
#         log directory of the current run. Named log directories will not be
#         automatically archived or housekept. Only works with `--run=run`.
#     --name=NAME, -n NAME
#         Specify the suite `NAME` in Cylc, instead of using the basename of
#         the configuration directory.
#     --new, -N
#         (Re-)create suite runtime locations. This option is equivalent to
#         running `rose suite-clean -y && rose suite-run` and will remove
#         previous runs. Users may want to take extra care when using this
#         option.
#     --no-gcontrol
#         Do not run `cylc gui`. Default is to run `cylc gui` if the suite is
#         running and the `DISPLAY` environment variable is defined.
#     --no-log-archive
#         Do not archive (tar-gzip) old log directories.
#     --no-overwrite
#         Do not overwrite existing files.
#     --no-strict
#         Do not validate (suite engine configuration) in strict mode.
#     --opt-conf-key=KEY, -O KEY, --opt-conf-key='(KEY)', -O '(KEY)'
#         Each of these switches on an optional configuration identified by
#         `KEY`. The configurations are applied first-to-last. The `(KEY)`
#         syntax denotes an optional configuration that can be missing.
#         Otherwise, the optional configuration must exist.
#     --quiet, -q
#         Decrement verbosity.
#     --reload
#         Shorthand for `--run=reload`.
#     --restart
#         Shorthand for `--run=restart`.
#     --run=reload|restart|run
#         Invoke `cylc reload|restart|run` according to this option.
#         (default=`run`)
#     --verbose, -v
#         Increment verbosity.
#
# ENVIRONMENT VARIABLES
#     `rose suite-run` provides the following environment variables to the suite.
#
#     ROSE_ORIG_HOST
#         The name of the host where the `rose suite-run` command was invoked.
#     optional ROSE_SUITE_OPT_CONF_KEYS
#         Each `KEY` in this space delimited list switches on an optional
#         configuration. The configurations are applied first-to-last.
#
# JINJA2 VARIABLES
#     `rose suite-run` provides the following Jinja2 variables to the suite.
#
#     ROSE_ORIG_HOST
#         The name of the host where the `rose suite-run` command was invoked.
#
# SEE ALSO
#     * `cylc help gui`
#     * `cylc help register`
#     * `cylc help run`
#-------------------------------------------------------------------------------
exec python2 -m rose.suite_run "$@"
