3.1 Summary of Development Tools and Best Practices

3.1.1 General Resources

Mailing List

Please make sure that you sign up to the Nektar++ mailing list. This can be done at the following URL:

https://mailman.ic.ac.uk/mailman/listinfo/nektar-users

While the name suggests it is for users of Nektar++, this list is also used to ask questions about Nektar++ development.

Blog

The Nektar++ blog (https://www.nektar.info/cat/community) provides a broad range of posts on topics such as compiling the code on specific machines, to discussions of Nektar++ in specific application areas, to recently published papers which have made use of the code.

Contributing to this resource is a valuable way to support the project, as well as promoting your own work.

Annual Workshop

In 2015, we held the first Nektar++ workshop, which was a great success and followed by a similar event in 2016. It is now an annual event and allows first-hand access to the core Nektar++ development team as well as a range of other Nektar++ users.

3.1.2 Version Control (git)

The Nektar++ code is managed in a distributed version control system called git. To obtain the code directly from the repository and add new content to the repository requires the git command-line tool (or a suitable GUI equivalent). This is available for Linux, Mac OSX and Windows.

If you plan to work with the Nektar++ community, you will need to have a reasonable understanding of the git software. While it is beyond the scope of this document to discuss how to use git, it is important for someone new to git to spend time understanding how the tool works. For this purpose, we highly recommend familiarizing yourself with it using any of the many online resources (such as https://git-scm.com).

Anonymous Access

Nektar++ may be cloned anonymously using the following command:

git clone http://gitlab.nektar.info/clone/nektar/nektar.git nektar++

Your local copy of the code can be updated to include the latest changes in the repository using the command:

git pull

The Anonymous Access approach will provide you with a complete copy of the code, but you will be unable to push changes or new developments back to the repository. For this, you should use Collaborative Access.

Collaborative Access

Once you are familiar with git, have introduced yourself to the development community (see the mailing list information above), and are ready to become a contributing developer, you will need to register an account on the Nektar++ Gitlab website:

https://gitlab.nektar.info.

To use use authenticated access, using your new account, you must first upload the public part of your SSH key to your Gitlab profile. Generating and managing SSH keys is beyond the scope of this document. However, on Linux and OSX, one generally finds these keys in the \$HOME/.ssh directory.

To upload the key, visit: https://gitlab.nektar.info/profile, select SSH keys from the menu on the left and follow the instructions.

Registering for an account and uploading your SSH key need only be done once.

To clone Nektar++, use the git command:

git clone git@gitlab.nektar.info:nektar/nektar.git nektar++

Note the different URL to use authenticated access, in comparison to the anonymous access.

Managing and Contributing code

Code contribution then follows three basic steps:

  1. Create an issue to describe the code updates you are making;
  2. Branch the Nektar++ master branch and make your changes on that branch; and
  3. Submit a merge request on the Nektar++ Gitlab website that your updates are ready to be merged into the master branch.

More details regarding the concepts mentioned above is found below. The information is also available in the CONTRIBUTING.md file in the root directory of the code, or online at: https://gitlab.nektar.info/nektar/nektar/blob/master/CONTRIBUTING.md

3.1.3 Building (CMake)

Nektar++ uses the CMake tool to manage the build process for the three supported operating systems: Linux, Windows, and OSX. For detailed instructions on how to use CMake to build Nektar++, including a list of required software dependencies and CMake option flags, please refer to the Nektar++ User Guide section 1.3.

3.1.4 Testing (CTest)

Before you are ready to have your code merged into the Nektar++ trunk, you should make sure that it passes the built-in test suite - in addition to any new tests that you have added for your updates. To run the test suite, on the command line type:

ctest [-j#]

The -j# optional argument will run # tests in parallel taking advantage of multiple cores on your machine. It is highly recommended that your use all available cores to minimize the amount of time spent waiting for the tests to complete. There are currently several hundred built-in unit tests for Nektar++.

For more information on testing, see “Software Testing Approaches” below.

3.1.5 Merge Requests (Gitlab)

The final step in contributing your code to the Nektar master repository is to submit a merge request to the development team using the Nektar++ gitlab website:

https://gitlab.nektar.info/nektar/nektar/merge\_requests

Submitting a merge request will automatically trigger the continuous integration (CI) system, which will build and test your code on a range of platforms. You can monitor the progress of these tests from the merge request page. Selecting individual workers will take you to the buildbot website from which you can examine any failures which have occurred.