.. _setup:

Environment setup
=================

With the setup described here, you will have one copy of the |ece4| code ready
for development.
This setup, with references to two Gitlab remotes, is needed once only.

Prerequisites
-------------

* We assume a minimum knowledge of git. If you are unfamiliar with it,
  have a look at these resources:

  * `software carpentry beginner lessons <https://swcarpentry.github.io/git-novice/>`_

* You should have registered for an account on the SMHI gitlab
  instance. See :ref:`registration`.

* Finally, a recent version of Git is recommended. Versions older than
  2.14 miss some features related to submodule. You can check the Git
  version with:

  .. code-block:: bash

     >>> git --version
     git version 2.25.1

  Check with your administrator if you need to upgrade.

Setup the superproject
----------------------

* Get a copy of the |ece4| project

  This step is needed if you did not go through the :ref:`clonecode`
  and are starting from scratch. Then you clone the repository with:

  .. code-block:: bash

     git clone -o upstream --recurse-submodules https://git.smhi.se/ec-earth/ecearth4.git

  You will see a lot of output on the screen. Version numbers may
  differ according to the project advancement, but it should look like:

  .. code-block:: bash
     :emphasize-lines: 12
     
     >>> git clone -o upstream --recurse-submodules https://git.smhi.se/ec-earth/ecearth4.git
     Cloning into 'ecearth4'...
     Username for 'https://git.smhi.se': XXXX
     Password for 'https://sager@git.smhi.se': 
     remote: Enumerating objects: 698, done.
     remote: Total 698 (delta 0), reused 0 (delta 0), pack-reused 698
     Receiving objects: 100% (698/698), 1.87 MiB | 4.73 MiB/s, done.
     Resolving deltas: 100% (337/337), done.
     [...]
     Submodule path 'sources/nemo-4.2': checked out '68e39f70a8e32452e7fc480f17c36ff6ad3d092a'
     Submodule path 'sources/oasis3-mct-5.0': checked out 'b9ea055f25bbff466acbe46e72bb4f88763f8498'
     Submodule path 'sources/oifs-43r3v2': checked out '27d3451306d4e2757016494e8e9a150df4d7f691'
     Submodule path 'sources/xios-2.5+': checked out 'cddb36170c6d8001fbfdb9dc8301e27fac8e966e'

  Note the submodules listed at the end. They correspond to the
  components of EC-Earth that have their own repository. Some extra
  steps (see next section) are required to contribute to their
  development. But not all components have a dedicated repository.
  Currently only NEMO, OpenIFS, OASIS3-MCT and XIOS do.

.. hint:: Please have a look at the hint given in :ref:`clonecode`, regarding the time it takes
   to download the complete |ece4| repository with submodules.

* Fork the |ece4| project

  To share your work, you will need a fork of the project on GitLab.  Go to
  `<https://git.smhi.se/ec-earth/ecearth4>`_. Click on the fork button (top right). You will be
  asked to "Select a namespace" for the project URL: choose your name in the drop down list,
  and click on "Fork project".

  To allow your colleagues to see your changes to the code, you will need to open up the
  permissions of the fork. This can be done for individual users or for the full ecearth group.

  .. figure:: fig_fork_members.png
     :alt: add members to fork

  You will end up with your own project:
  ``https://git.smhi.se/YOURNAMESPACE/ecearth4``, where YOURNAMESPACE
  is your user name in GitLab. You need to add a reference to it in
  your local copy of the code:

  .. code-block:: bash

     cd ecearth4
     git remote add origin https://git.smhi.se/YOURNAMESPACE/ecearth4.git

  Finally, get up-to-date repositories references:

  .. code-block:: bash
                  
     git fetch --all

  You can double-check that the two remotes are correctly set with:

  .. code-block:: bash

     >>> git remote -v
     origin     https://git.smhi.se/YOURNAMESPACE/ecearth4.git (fetch)
     origin     https://git.smhi.se/YOURNAMESPACE/ecearth4.git (push)
     upstream   https://git.smhi.se/ec-earth/ecearth4.git (fetch)
     upstream   https://git.smhi.se/ec-earth/ecearth4.git (push)


Setup a submodule
-----------------

Let's now assume that you want to modify the OpenIFS code. You first
navigate to its directory:

.. code-block:: bash
   
   cd ecearth4/sources/oifs-43r3v2

and then retrieve information about its remote:

.. code-block:: bash

   git remote -v

It should read:

.. code-block:: bash

   origin  https://git.smhi.se/ec-earth/vendor/openifs/oifs43r3.git (fetch)
   origin  https://git.smhi.se/ec-earth/vendor/openifs/oifs43r3.git (push)

This output indicates the project page:
`<https://git.smhi.se/ec-earth/vendor/openifs/oifs43r3>`_. The page can
also be found by navigating to the "sources" directory in the web
interface:

.. figure:: fig_checking_sources.png
   :alt: sources directory listing in GitLab
   
Clicking on the component name will bring you directly to its project
page.

Visit that project page and **fork the OpenIFS project** in the same way you
forked the |ece4| project. You should now own a second project:
``<https://git.smhi.se/YOURNAMESPACE/oifs43r3>``.

Finally, configure the component repository:

.. code-block:: bash

   cd ecearth4/sources/oifs-43r3v2    #if not there already
   git remote rename origin upstream
   git remote add origin https://git.smhi.se/YOURNAMESPACE/oifs43r3.git
   git fetch --all


.. note:: To summarize, you have:
   
   * forked the |ece4| and the OpenIFS repositories
   * setup your local copy of |ece4| with references to your (as
     origin) and the reference (as upstream) repositories