Let GIT into your life...

We intend to distribute templates and exercises for the exercise classes using git and recommend you use the features of a version control system in order to keep track of the code for this lecture and long-term projects in general. The concept of a version control system is even more relevant as soon as you start to work on your Master's thesis or in a successive scientific career. Unfortunately many Physicists do not choose to use the tools already available. That is why we will show you the light of GIT and how to properly use it in a "learning-by-doing"-scenario. Do not hesitate to send us an email and ask for help but please do first attempt to find a solution to your problem by asking your preferred search engine. In general you will find that there is a vivid online community on multiple platforms discussing various aspects of programming. If you encounter a problem while coding or while using git, the probability that someone else has already encountered the same problem before is pretty high. Copying error codes to the search engine is usually a good starting point. Please do not forget to remove aspects specific to your project like project names, specific file paths, e.g. before triggering the search as you might end up with no results in case of a too specific set of words.

How to start with this introduction

The basic idea of this introduction is for you to create your own repository, copy the files within this repository to your own repository and then proceed to fiddle with the samples and attempt to solve the programming training tasks in src/task_*.cpp (Higher numbers require more intricate understanding of the programming concepts).

First you will require a gitlab account.

Proceed to the FAU gitlab server and login using your idm credentials. To finalize the creation of your account, please click on the image in the top right, select "Settings" and proceed to the "Password" section selectable on the left. There you will need to assign a password that will be used in all further interactions using the command line.

Creating the project

Proceed to create your project by clicking on the plus (+) sign in the top bar and selecting "New Project". Assign a name that will tell you what this project is about (e.g. "cp1_cpp_introduction") and add an adequate description. Do not select "Add a Readme" or any other options populating your project with an initial set of files. You can keep your project privacy at "Private" and create the project.

Configuration

You will now be redirected to the front page of your new empty project repository. Gitlab will provide you with a list of initial commands to run. You only require to copy the two git config --global ... lines at the top to configure your user setup for git. Copy those to a terminal window on your computer and run them.

Getting a local copy of the repository

Now that you have configured your git user information, you need to obtain a local copy of your empty project. Go to a directory where you want git to create a subfolder containing the repository. Then with a terminal in the directory of your choice, run the command git clone <repository_https_url> Where <repository_https_url> can be obtained by clicking on the blue "clone" button on your repository page. There will be one link starting with "https://" in the modal window popping up. Copy that one and use it instead of <repository_https_url> to trigger the copying process. If the command asks you for your username and passwort provide your idm username and the password you assigned in the gitlab settings. Ignore git's warnings that your project might be empty.

You should see a new directory with the name of your project on gitlab in the current folder. Navigate to that subfolder. If the command 'ls -al' displays a folder .git you should be in the right folder.

Obtaining the data from the official repository

We will now proceed to copy the files from this repository to your personal copy. With a terminal open in the directory of the cloned repository, run git remote add vorlage https://gitlab.cs.fau.de/cp1_ws19/cpp_introduction This will register this repository as a source for files with the name "vorlage". Your own repository on gitlab should be registered as "origin". To check that this is indeed the case, you can run git remote in order to list the registered remote repositories and git remote get-url <remote_name> to display the url that remote is associated with. To copy the files of this repository to yours run git pull vorlage master You should see the files from this repository appear in the project's directory.

Working on the program files and using the version control

You can open the source files in "/src" with any text editor or a development environment of your choice. I will be using "Code::Blocks" for my demonstrations. Once you have changed a source code file and want to keep your changes save, you can use

git add <file_path>

in order to register the file for subsequent versioning. The command

git status

should give you an overview of which files are new, which have been removed and which have been changed. All three types of changes can be registered for subsequent versioning via git add Make sure not to add any binary/compiled files as git is not good at keeping those files and it bloats your repository. In case you ever accidentally add any file, you can revert the registration (not the actual changes to the file) via

git reset <file_path_to_unregister>

If you have accidentally changed or deleted a file and would like to reset it to its last stored state, you need to use

git checkout <file_path_to_restore>

Once you have registered all changed files that you would like to store, run

git commit

and enter a message describing the changes you performed. This will be done using a command line text editor. If you have vim set as your default editor, you first need to type the letter i to enter "input" mode. Then you can type your message. Once you have finished, you can leave "input" mode using the ESC key and write out your message by typing ":wq" (the colon needs to be included). Git will notify you of the changes being stored. Congratulations, you have just created a local version of your project. It is good practice to create new versions often even with small changes. The changes introduced within individual versions/commits can be reverted if you should realize that they introduced problems/errors. But in a big commit with many changes you can only roll back all of the changes possibly losing you valuable changes to your project. A good practice would be to add and commit every smallest set of changes to the project adding a new logical aspect/functionality that still leaves your project in a state that can be built/executed.

How to protect the versions and work on multiple machines.

If you want to protect your stored versions/commits from hard drive failure/loss or if you plan to cooperate with other people you will want to copy your changes back to the gitlab server. You can always do that by running

git push

and entering your credentials. When running this command for the first time, git might recommend running an alternate version of this command to setup the repository even further. In that case just copy the recommended command and run that. Any subsequent pushes can be run by just git push. It might happen that git rejects your push due to changes on the server. In that case you will need to retrieve the changes on the server using

git pull

first. Git will attempt to unify your changes with the version on the server. If it succeeds it will suggest a commit message for the merge of the versions which you can simply accept and retry the push.

If it fails to merge the changes, it will tell you, in which files there were unsolvable conflicts. You will have to look at thos files manually. Git marks the lines with conflicts with lines of '=' signs. The version labelled 'HEAD' will be the version previously on your local machine. Any other versions will refer to the latest version on the server. Delete any code that should not persist in the unified version, delete the markings introduced by git and register the manually merged files with git add just like if you had originally modified them. Once all files with errors have been fixed and added (you can always check git status if there is still one missing). Use git commit to store the merged version and retry git push.

Final remarks

Congratulations, you have successfully created your own version of this repository and you can keep track of your progress using git. You can even grant other people access to your code on the gitlab which should always be the preferred version over sending someone a zip archive via E-mail. The default options for git push and git pull will only update your own version of the project and will only retrieve changes to your own gitlab repository. If you ever wish to obtain changes introduced to other remote repositories such as this template repository ("vorlage") you can tell git to specifically look for changes there by calling

git pull <remote_name>

most likely

git pull vorlage

Merge conflict might still occur. You can resolve them the same way that you resolve merge conflicts within your own project.

C++ introduction

This repository contains multiple templates for the C++ introduction in the module CP1.

In the "sample_*.cpp"-files you will find examples of C++ code detailing different aspects of the language.

In the "task_*.cpp"-files you will find problem statements for you to complete on your own. Read the problem statement detailed by the comment in the file and implement a program that behaves as described.

A basic overview

C++ Reference

There are various ressources for tutorials on C++. The most important reference for looking up C++'s builtin features is C++Reference. You should look out for markings like (C++20) or (C++17) that sometimes occur in the references. This means that you have to specify at least this language level (-std=c++17 or -std=c++20) for your program to compile if it uses any of those functionalities. Be aware that several C++20 features might not yet actually be supported by current compilers

Additional ressources

The second big reference can be found on Cplusplus.com and even contains a tutorial detailing the various aspects of C++. I can also recommend following one of the many video tutorials on youtube, where there is often an extensive explanation on why are things done that way. One tutorial spanning from very simple introductory concepts to rather advanced features of C++11 is that by TheNewBoston. Obviously you should not just watch all of these videos from start to finish but you might find certain of theses videos interesting or focussing on an aspect of C++ that you have not yet mastered.

How to compile a program

C++ is a human-readable language. In order to be executable by a computer, the program has to be translated into machine code.

You can use the command

g++ <source_code_file> -o <name_of_output_program> -std=c++11 -Wall -Werror

This tells the compiler (g++) where to find the source code and how to name the resulting program. In case you omit the name of the output program the result will most likely be an executable file called "a.out". The flags at the end of the command tell the compiler which version of C++ to use (C++ 2011) and to trigger all warnings your code might produce and elevate them to errors. It is generally a good practice to use these last two flags. If your code does compile without these two options but does not compile with them, chances are high that there is still a programming error in your program.

A sample invocation of the command:

g++ src/sample_4.cpp -o sample_4 -std=c++11 -Wall -Werror

And the sample program can then be run by calling

./sample_4

in the console.