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 (firstname.lastname@example.org).
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.
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:
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.
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.
|Fortran Compilation in Windows using MinGW-64 compilers and the Code::Blocks IDE||This guide is intended for people who wish to build any of the SwanSim source code using Windows but do not have access to/do not wish to use Microsoft Visual Studio Community Editions and/or the Windows Intel Fortran compilers.|
|CMake User Guide||This guide introduces the CMake build system which is used for every SwanSim product. The reader is taken through a set of examples ranging from a single executable to a mixed-language project involving libraries.|
|CMake User Guide - Examples||These are the simple set of examples used in the CMake User Guide. They have been provided to save creating the files manually.|
|Converting a Project to Git (GitLab)||This guide takes you through the steps of converting an existing software project into a Git repository and storing it on the SwanSim GitLab server. For software projects involving C, C++ or Fortran, it is recommended to also read the CMake User Guide which guides the reader through the process of converting the build process to use CMake.|
|GitFlow User Guide||This a link to a very good explanation of the Git Flow workflow. It also compares it to a number of other workflows that are commonly used with Git.|