Introduction

In order to ensure the experience of an end-user or contributor is as smooth as possible, it is important that each product available within SwanSim can be downloaded, built and installed in a similar manner. This guide will provide a simple checklist that will ensure that this is the case.

The purpose of this section is to provide a set of guidelines which, if followed, will guarantee that your software follows the same processes as the other products available in SwanSim.

If assistance is required for any of the tasks below please contact Dr Jason Jones (j.w.jones@swansea.ac.uk).

The Checklist

This section provides a simple checklist that will ensure each product within SwanSim has a similar structure; and can be built and installed in a similar manner. This ensures consistency across the entire suite of software.

Important Files

There are a number of files which must be placed in the root directory of your software. These are:

• COPYING.txt – This contains the standard GNU General Public License (GPL v3)
• COPYRIGHT.txt – This contains the copyright notice ensuring that this is retained by Swansea University.
• README.md – This provides a short introduction to the software that will appear on the GitLab server.

Each of the items above is a link to a sample file. Feel free to modify these files to suit the individual product but please keep the overall text the same.

Each source code file must also have a short copyright notice placed at the top of it. This ensures that even if components of the software get distributed, the license remains intact. The list below provides links to the copyright notice in plain text file as well as commented versions which can be placed directly in the source code of the following languages:

• Plain text
• C/C++
• Fortran 77
• Fortran 90

Each of these files contains the same text - the files for each language just have the appropriate comments added to enable the source code to compile.

It is possible to perform this task later in the process but it is best that it is done before the source code is committed to the GitLab repository.

CMake

Each product must use CMake for the build process. This allows the software to be built on a variety of platforms including Windows, Linux and MacOS. A guide to converting your software to use CMake is provided here (the sample files used in the guide are available as a zip file here). This guide covers the basic steps for a typical Fortran / C / C++ project. Please ask for assistance for more complex requirements.

Uploading to the GitLab repository

Each component within SwanSim is managed in GitLab. GitLab provides a friendly web interface to the Git repository which contains the source code for that component. Git is a powerful Revision Control System which allows you to track the entire history of all changes made to the code.

There are lots of tutorials on Git on the web. Some of the better ones are listed below:

• Git Tutorials by Atlassian - This comprises a series of tutorials concentrating on various aspects of Git
• Try Git - This site allows you to try Git commands in a safe environment.
• Git SCM Tutorials - This is a rather verbose tutorial. It's more suited as a quick reminder rather than learning Git for the first time.

Git is a very flexible tool that allows any number of workflow models to be implemented. In order to maintain consistency, SwanSim uses the GitFlow workflow. A guide to GitFlow is provided here and the original documentation and script files for GitFlow is available here.

Git is typically command-line driven. However, if using Windows, then a free tool called SourceTree is available which provides a friendly graphical interface to Git. Although there are a number of similar tools available on the web, SourceTree has the advantage that it natively supports the GitFlow workflow.

In order to be able to upload your source code to GitLab, please ask for an account. Assistance will be provided if required.

List of Guides

Throughout this section, reference has been made to user guides which have been provided in order to make the transition to SwanSim easier. The table below collates all of these guides (and a few not mentioned above) together.