.gitlab-ci.yml

# Continuous Integration and Deployment of Utopia Framework Repository
---
# ++ Pipeline preparations ++++++++++++++++++++++++++++++++++++++++++++++++++++
stages:
  - setup     # set up the docker base image
  - build     # build utopia and all tests
  - test      # carry out tests
  - docs      # build the documentation (requires build stage artifacts)
  - check     # carries out static checks
  - deploy    # deploy documentation; build and deploy docker image (on master)


variables:
  # Need to clone submodules as well
  GIT_SUBMODULE_STRATEGY: recursive

  # Variables needed for docker image deployment
  # The different segments of the resulting test image tag
  BASE_IMAGE_UBUNTU_VERSION: jammy  # NOTE Adjust upon new Ubuntu Release
  BASE_IMAGE_VERSION: "2.1"         # NOTE Increment when changing dockerfile
  BASE_IMAGE_NAME: ccees/utopia-base
  BASE_IMAGE: "${BASE_IMAGE_NAME}:${BASE_IMAGE_UBUNTU_VERSION}-v${BASE_IMAGE_VERSION}"
  # NOTE Do not forget to increment the BASE_IMAGE_VERSION when changes to the
  #      docker file are introduced.

  # Variables controlling the deployed Utopia image and its development
  # counterpart (deployed from the ci_test stage for testing)
  UTOPIA_IMAGE_NAME: ccees/utopia
  UTOPIA_IMAGE_REMOTE_URL: https://gitlab.com/utopia-project/utopia.git
  UTOPIA_IMAGE_BRANCH: master

  # Utopia virtual environment shortcuts
  RUN_IN_UTOPIA_ENV: $CI_PROJECT_DIR/build/run-in-utopia-env
  ENTER_UTOPIA_ENV: source $CI_PROJECT_DIR/build/activate

  # Docker Hub login command
  DOCKER_HUB_LOGIN: docker login -u $DOCKER_HUB_USER -p $DOCKER_HUB_PW
  # NOTE Both variables here are secret and protected variables. While the
  #      login command will complain, using --password-stdin actually EXPOSES
  #      the variable! No no.

  # The GitLab Pages where artifacts can be shown
  PAGES_URL: https://utopia-project.gitlab.io/-/utopia

  # Variables that control whether certain jobs are executed.
  # These can be overwritten via the GitLab CI/CD interface.
  UPDATE_UTOPIA_BASE_IMAGE: "false"
  DEPLOY_DOCKER_IMAGE: "false"
  DEPLOY_DOCS: "false"
  FORCE_DEPLOY_DOCS: "false"


# Run pipelines:
#   - on tags
#   - for CI schedules
#   - for web-based triggers, i.e. from CI/CD -> Run Pipeline
#   - on merge request events
#   - *not* on branches that have a merge request associated
#   - on the default branch but not on any other branches
workflow:
  rules:
    - if: $CI_COMMIT_TAG
    - if: $CI_PIPELINE_SOURCE == "schedule"
    - if: $CI_PIPELINE_SOURCE == "web"
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH && $CI_MERGE_REQUEST_IID
      when: never
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH


# As base image for the jobs, use the Utopia image created in the setup stage
image: ${BASE_IMAGE}


# .. YAML Templates ...........................................................
# These are used in job definitions via the `extends` keyword

# Tags for jobs that need (or profit from) multiple vCPUs
.use_multicore_runner:
  variables:
    CPUS_BUILD: 4
    CPUS_TEST: 4
    CPUS_DIND: 4

    # Make flags that are used in building and testing
    MAKE_FLAGS_BUILD: -j$CPUS_BUILD
    MAKE_FLAGS_TEST: -j$CPUS_TEST
  tags:
    # 4vCPU, 16GB RAM instances
    # See:  https://docs.gitlab.com/ee/ci/runners/saas/linux_saas_runner.html
    # NOTE If adjusting this, update the
    - saas-linux-large-amd64

# Create artifacts of build results and meta-data that's shared between jobs
.default_artifacts:
  artifacts:
    name: "$CI_JOB_NAME"
    paths:
      - $CI_PROJECT_DIR/build       # Build files
      - $CI_PROJECT_DIR/python      # Editably-installed python code
      - $CI_PROJECT_DIR/.config     # Frontend configuration files
    expire_in: 3 hours


# Add coverage report visualization for MRs
# Docs: https://docs.gitlab.com/ee/user/project/merge_requests/test_coverage_visualization.html
# Reports are generated from multiple jobs and is then merged by GitLab
.coverage_report:
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: $CI_PROJECT_DIR/build/coverage/cobertura.xml


# Use the Docker-in-Docker executor and services, log into Docker Hub
.dind:
  image: docker:stable
  extends:
    - .use_multicore_runner
  services:
    - docker:dind
  variables:
    DOCKER_DRIVER: overlay2
  before_script:
    - docker info
    - $DOCKER_HUB_LOGIN




# ++ Job definitions ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# -- Setup stage --------------------------------------------------------------
# This stage takes care to build the utopia base testing image

setup:utopia-base:
  extends: .dind
  stage: setup
  rules:
    - if: '$UPDATE_UTOPIA_BASE_IMAGE == "true"'
      when: always
    - if: '$CI_COMMIT_BRANCH == "master"'
      when: always
    - when: never
  script:
    - docker build -f docker/utopia-base.dockerfile
                   -t ${BASE_IMAGE}
                   -t ${BASE_IMAGE_NAME}:latest
                   --build-arg UBUNTU_VERSION=${BASE_IMAGE_UBUNTU_VERSION}
                   .
    - docker push ${BASE_IMAGE}
    - docker push ${BASE_IMAGE_NAME}:latest



# -- Build stage --------------------------------------------------------------
# In this stage, the tests and models are built.
# Artifacts are needed in the next stages.

# Build the core unit tests; artifacts used in test stage
build:tests_core:
  stage: build
  extends:
    - .default_artifacts
    - .use_multicore_runner
  script:
    - mkdir build && cd build
    - cmake -DCPP_COVERAGE=On -DMULTITHREADING=On ..
    - make $MAKE_FLAGS_BUILD build_tests_core


# Build the data I/O unit tests; artifacts used in test stage
build:tests_dataio:
  extends: build:tests_core
  script:
    - mkdir build && cd build
    - cmake -DCPP_COVERAGE=On ..
    - make $MAKE_FLAGS_BUILD build_tests_dataio


# Build the models and their tests; artifacts used in test stage
build:models:
  stage: build
  extends:
    - .default_artifacts
    - .use_multicore_runner
  script:
    - mkdir build && cd build
    - cmake -DCPP_COVERAGE=On -DMULTITHREADING=On ..
    - make $MAKE_FLAGS_BUILD all
    - make $MAKE_FLAGS_BUILD build_tests_models
  after_script:
    # Copy the frontend configuration to the project dir such that it is part
    # of the artifacts and can be re-used in the test jobs
    - cp -r ~/.config $CI_PROJECT_DIR/


# Build in debug mode using gcc
build:debug:
  stage: build
  allow_failure: true
  extends:
    - .use_multicore_runner
  variables:
    CXXFLAGS: -Werror
  script:
    - mkdir build && cd build
    - cmake
        -DCMAKE_BUILD_TYPE=Debug
      ..
    #
    # Build all the tests
    - make $MAKE_FLAGS_BUILD build_tests_core
    - make $MAKE_FLAGS_BUILD build_tests_dataio
    - make $MAKE_FLAGS_BUILD build_tests_models
    #
    # Test that additional convenience targets exist
    - make $MAKE_FLAGS_BUILD build_tests_backend
    - make $MAKE_FLAGS_BUILD build_tests_all
    #
    # Build all the models
    - make $MAKE_FLAGS_BUILD all


# Build in debug mode using clang
build:debug-clang:
  extends: build:debug
  variables:
    CC: clang
    CXX: clang++
    CXXFLAGS: -Werror


# Build for installation tests using Release mode
build:install:
  stage: build
  extends:
    - .use_multicore_runner
  artifacts:
    name: "$CI_JOB_NAME"
    paths:
      - $CI_PROJECT_DIR/build
      - $CI_PROJECT_DIR/install  # installation directory
    expire_in: 3 hours
  script:
    - mkdir build && cd build
    - cmake
        -DCMAKE_INSTALL_PREFIX=$CI_PROJECT_DIR/install
        -DCMAKE_BUILD_TYPE=Release
        -DMULTITHREADING=On
        -DCMAKE_EXPORT_PACKAGE_REGISTRY=On
        ..
    - make $MAKE_FLAGS_BUILD install

    # Make packgage registry available as artifact
    - cp -r ~/.cmake .



# -- Test stage ---------------------------------------------------------------
# Uses artifacts of the build stage to test: backend, models, CLI, installation

# Test the core library
test:core:
  stage: test
  extends:
    - .coverage_report
    - .use_multicore_runner
  needs:
    - build:tests_core
  variables:
    GCOVR_PATHS:
      --root $CI_PROJECT_DIR
      --filter $CI_PROJECT_DIR/include/utopia/core
  script:
    - cd build
    - make $MAKE_FLAGS_TEST test_core
  after_script:
    - $ENTER_UTOPIA_ENV

    # Install gcvor
    - pip3 install gcovr
    - cd $CI_PROJECT_DIR/build
    - mkdir coverage

    # Run once for report in HTML (for viewing) and XML (for cobertura) ...
    - gcovr $GCOVR_PATHS --html --html-details -o coverage/report.html --print-summary --xml coverage/cobertura.xml

    # ... and again for a coverage report in the GitLab job log
    - gcovr $GCOVR_PATHS
  coverage: '/^lines: (\d+.\d+\%).*$/'   # matches output of --print-summary
  artifacts:
    name: "$CI_JOB_NAME"
    expose_as: Coverage report of Core tests
    paths:
      - build/coverage/
    expire_in: 1 week

  environment:
    name: review/coverage/core/$CI_COMMIT_REF_NAME
    auto_stop_in: six weeks
    url: $PAGES_URL/-/jobs/$CI_JOB_ID/artifacts/build/coverage/report.html


# Test the data I/O library
test:dataio:
  extends: test:core
  needs:
    - build:tests_dataio
  variables:
    GCOVR_PATHS:
      --root $CI_PROJECT_DIR
      --filter $CI_PROJECT_DIR/include/utopia/data_io
  script:
    - cd build
    - make $MAKE_FLAGS_TEST test_dataio
  artifacts:
    expose_as: Coverage report of DataIO tests

  environment:
    name: review/coverage/dataio/$CI_COMMIT_REF_NAME


# Test the models via their own tests and via the CLI
test:models:
  stage: test
  extends: test:core
  needs:
    - build:models
  variables:
    # Exclude any paths containing 'test', should not count towards coverage
    GCOVR_PATHS:
      --root $CI_PROJECT_DIR
      --filter $CI_PROJECT_DIR/src/utopia/models
      --exclude '.*[Tt]est.*'
  before_script:
    # Place a symlink at the expected path to make the model registry available
    - &add_cfg_symlink ln -s $CI_PROJECT_DIR/.config ~/.config && ls -la ~/
    #
    # Reduce number of steps for models to speed up CI
    - $ENTER_UTOPIA_ENV
    - utopia config user --set paramter_space.num_steps=10 --get
  script:
    # Test models using C++ and Python model tests
    - cd build
    - make $MAKE_FLAGS_TEST test_models

    # Also test each model via the CLI.
    # Need to enter the virtual env first
    - $ENTER_UTOPIA_ENV

    # First, the test and benchmark models:
    - utopia run dummy --debug
    - utopia run CopyMeGraph --debug
    - utopia run CopyMeGrid --debug
    - utopia run CopyMeBare --debug --no-eval
    - utopia run HdfBench --run-mode sweep --num-seeds 3 --debug

    # Now the actual models:
    - utopia run ContDisease --debug
    - utopia run Environment --debug
    - utopia run ForestFire --debug
    - utopia run GameOfLife --debug
    - utopia run Geomorphology --debug
    - utopia run Opinionet --debug
    - utopia run PredatorPrey --debug
    - utopia run SandPile --debug -N 100
    - utopia run SEIRD --debug -N 50
    - utopia run SimpleEG --debug
    - utopia run SimpleFlocking --debug
    - utopia run Vegetation --debug

  artifacts:
    expose_as: Coverage report of model tests

  environment:
    name: review/coverage/models/$CI_COMMIT_REF_NAME


# Test the utopia command line interface
# NOTE This does not test the full CLI, because that is utopya's job.
#      This job only makes sure that the most basic commands really work.
test:cli:
  stage: test
  needs:
    - build:models
  artifacts:
    name: utopia_output
    paths:
      - $CI_PROJECT_DIR/utopia_output/
    expose_as: Utopia Output
    expire_in: 3h
  before_script:
    # Make model registry available (from build:models job)
    - *add_cfg_symlink
  script:
    # Now, enter the virtual environment and test the CLI
    - $ENTER_UTOPIA_ENV

    # Adjust the user configuration to store to a local directory and use a
    # different default for the number of simulation steps
    - utopia config user --set paths.out_dir=$CI_PROJECT_DIR/utopia_output --get
    - utopia config user --set paramter_space.num_steps=3 --get

    # Show which models are available
    - utopia models ls --long

    # .. Running models .......................................................
    - utopia run dummy --debug

    # Test passing a custom run configuration and performing a sweep
    - utopia run dummy python/model_tests/dummy/sweep.yml --run-mode sweep --note sweep --debug

    # Write start and step
    - utopia run dummy -d --note write_sparse -N 10 --write-every 2 --no-eval
    - utopia run dummy -d --note write_last -N 10 --write-start 10 --no-eval

    # Select a different run mode
    - utopia run ForestFire -d --num-seeds=3 --note some_sweep
    - utopia run ForestFire -d --num-seeds=3 --run-mode single --note no_sweep

    # Test using a configuration set to specify run and plots config
    - utopia run ForestFire -d --cs long_run -N 10
    - if utopia run ForestFire --cs bad_config_set_name; then exit 1; else echo -e "\nFailed as expected"; fi

    # .. Evaluation ...........................................................
    - utopia run dummy --note plt0 --no-eval
    - sleep 1.1 && utopia eval dummy  # should create the corresponding plots

    # Interactive
    - sleep 1.1 && utopia eval -d --interactive dummy
        <<< $'\n--plot-only states\n--plot-only state_mean --debug'
    - sleep 1.1 && utopia eval -d -i dummy
        <<< $'--debug\n--debug --plot-only state_mean'
    - sleep 1.1 && utopia eval -d -i dummy
        <<< $'--plot-only some_non_existing_plot --debug'
    - sleep 1.1 && utopia eval -d -i dummy
        <<< $'some offending arguments\n--help'

    # .. Getting model information ............................................
    - utopia models info dummy
    - utopia models info ForestFire
    - utopia models info SEIRD

    # .. Model copying ........................................................
    # Test the model copying, first as a dry run, then for real
    - utopia models copy CopyMeGrid --new-name FooBar --target-project Utopia --yes --dry-run
    - utopia models copy CopyMeGrid --new-name FooBar --target-project Utopia --yes

    # Attempting to copy it again should fail (only in debug mode, files exist)
    - if utopia models copy CopyMeGrid --new-name FooBar --target-project Utopia --yes --debug; then exit 1; else echo -e "\n\nFailed as expected!"; fi

    # Test that it is registered. Note: Does not test building!
    - cd build && cmake ..
    - if utopia models ls | grep -q FooBar; then echo "Found copied FooBar!"; else echo "Could not find copied FooBar model!" && exit 1; fi

    # After registration via cmake, will also fail, even without debug mode
    # and when doing --dry-run, because the model already exists
    - if utopia models copy CopyMeGrid --new-name FooBar --target-project Utopia --dry-run --yes; then exit 1; else echo -e "\n\nFailed as expected!"; fi

    # .. Removing model registry entries ......................................
    # Test model registry entry removal interface; do this last, obviously
    - utopia models rm FooBar --all --yes

    - utopia models rm dummy --label added_by_cmake
    - if utopia run dummy; then exit 1; else echo -e "\nFailed as expected"; fi

    - utopia models rm SEIRD --all --yes
    - if utopia run SEIRD; then exit 1; else echo -e "\nFailed as expected"; fi


# Test if using Utopia in a downstream module works
test:link_build_tree:
  stage: test
  needs:
    - build:install
  dependencies:
    - build:install
  script:
    # Move the package registry into the user path
    - cd build && cp -r .cmake ~/

    # Build downstream module
    - cd $CI_PROJECT_DIR && mkdir build-dep && cd build-dep

    # Package should be found via registry
    - cmake ../test/dependency
    - make $MAKE_FLAGS_BUILD all
    - make test


# Test if using Utopia in a downstream module works also via the install tree
test:link_install_tree:
  extends: test:link_build_tree
  script:
    # Build downstream module
    - mkdir build-dep && cd build-dep

    - cmake
        -DUtopia_ROOT=$CI_PROJECT_DIR/install
        ../test/dependency
    - make $MAKE_FLAGS_BUILD all
    - make test




# -- Docs stage ---------------------------------------------------------------

# Build the documentation and expose it as a review environment
docs:build:
  stage: docs
  extends:
    - .use_multicore_runner
  needs:
    - build:models
  when: always
  allow_failure: false
  before_script:
    - cd build
    - cmake ..

    # Install dependencies and show installation result
    - pip install -r ../doc/requirements.txt
    - pip freeze
  script:
    # Now generate figures and build the docs
    - UTOPIA_DOC_GENERATE_FIGURES=True make doc

    # Run doctests (require models to have been built)
    - make sphinx_doctest
  after_script:
    # Append the error log such that it's more convenient to read in the CI log
    - echo "-------- Errors emitted during building of documentation --------"
    - cat $CI_PROJECT_DIR/build/doc/build_errors.log || true

  artifacts: &doc_artifacts
    name: $CI_JOB_NAME
    when: always
    paths:
      - $CI_PROJECT_DIR/build/doc/
      - $CI_PROJECT_DIR/doc/_static/_gen/    # output needed for linkcheck





# -- Check stage --------------------------------------------------------------

# Runs pre-commit hooks and checks that
check:hooks:
  stage: check
  image: python:3.10
  needs: []
  before_script:
    - pip install pre-commit
  script:
    - pre-commit run --all-files --verbose --show-diff-on-failure


# Checks the links in the documentation
check:docs_linkcheck:
  stage: check
  extends: docs:build
  when: on_success
  allow_failure: true
  tags: ~
  needs:
    - docs:build
  script:
    - make sphinx_linkcheck
  artifacts: ~



# -- Deploy Stage -------------------------------------------------------------
# Deploy ...
#   - a documentation review environment, which is meant to *always* be created
#     even if the build:docs job failed with allow_failure set.
#   - the production-level documentation by running a GitLab Pages job, which
#     ends up being served under docs.utopia-project.org — this will only be
#     deployed if the docs:build was successful
#   - the latest Utopia docker image to Docker Hub: ccees/utopia:latest


deploy:docs_review:
  image: alpine
  stage: deploy
  needs:
    - docs:build
  when: always
  script:
    - echo "Deploying Utopia Docs to review environment ..."
  artifacts:
    <<: *doc_artifacts
  environment:
    name: review/docs/$CI_COMMIT_REF_NAME
    auto_stop_in: six weeks
    url: $PAGES_URL/-/jobs/$CI_JOB_ID/artifacts/build/doc/html/index.html


pages:
  image: alpine
  stage: deploy
  rules:
    - if: '$FORCE_DEPLOY_DOCS == "true"'
      when: always
    - if: '$DEPLOY_DOCS == "true"'
      when: on_success
    - if: '$CI_COMMIT_BRANCH == "master"'
      when: on_success
    - when: never
  needs:
    - docs:build
  script:
    # Copy files into public directory which is then exposed as GitLab Pages
    - cd $CI_PROJECT_DIR
    - mkdir public
    - mv build/doc/doxygen    public/doxygen
    - mv build/doc/html       public/html
    - cp doc/_redirects       public/_redirects
    # see: https://docs.gitlab.com/ee/user/project/pages/redirects.html#create-redirects
  artifacts:
    paths:
      - public
  environment:
    name: production/docs
    url: https://docs.utopia-project.org/


deploy:dockerhub:
  extends: .dind
  stage: deploy
  # Speed up pipeline by requiring only test jobs to complete, not docs:build.
  # Need to specify them all individually to not trigger artifacts download.
  needs:
    - job: test:core
      artifacts: false
    - job: test:dataio
      artifacts: false
    - job: test:cli
      artifacts: false
    - job: test:models
      artifacts: false
    - job: test:link_build_tree
      artifacts: false
    - job: test:link_install_tree
      artifacts: false
  # Should always run on master and optionally via CI/CD variable
  rules:
    - if: '$DEPLOY_DOCKER_IMAGE == "true"'
      when: always
    - if: '$CI_COMMIT_BRANCH == "master"'
      when: always
    - when: never
  script:
    - docker build -f docker/utopia.dockerfile
                   --build-arg BASE_IMAGE=$BASE_IMAGE
                   --build-arg PROCNUM=$CPUS_DIND
                   --build-arg GIT_CHECKOUT=$UTOPIA_IMAGE_BRANCH
                   --build-arg GIT_REMOTE_URL=$UTOPIA_IMAGE_REMOTE_URL
                   -t $UTOPIA_IMAGE_NAME:latest
                   ./
    - docker push $UTOPIA_IMAGE_NAME:latest
  environment:
    name: production/docker-latest
    url: https://hub.docker.com/r/$UTOPIA_IMAGE_NAME