# -*- mode: org -*-
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="../css/emacs.css" />

*Overview:*

- 📽️ [[][*Overview video*]
- *Terms to know:*


* *Part 0: Tools overview*

For this course we will be using a couple of common and important tools
used in the professional software development world - an IDE (Integrated Development Environment)
and Soruce Control. First let's have a quick overview of what these are.

** *Integrated Development Environments*

[[file:images/ides.png]]

An IDE is a collection of tools in one program. While we can *build/compile* with one
program (like g++), edit our code with another, and run our program from the terminal,
an IDE puts all these tools (as well as a debugger and project management) in one place.

Every software company I've worked for has used Visual Studio, except a PHP
web development shop, where we just chose our own plaintext editor.

- *Windows:* The computers in the campus labs in Regnier Center all have
Visual Studio installed, so for *Windows* users that will be our default.

- *Windows (slow/old):* If you have a slow or older Windows computer, you could also use *Code::Blocks*,
  which is a cross-platform IDE that is lighter weight, but still has our desired features.

- *Linux:* If you're familiar with using Linux you can probably choose whatever tool you'd like,
  though I will default to *Code::Blocks* for instructions, as that is what I tend to use for C++ development.

- *Mac:* You will need to install *Xcode* from your app store no matter what you use (the easiest way
  to get the compilers installed). Xcode has our common IDE features, but if you are unable to get that
  working, you can also use *VS Code* and build/run *from the terminal*.


*NOTE: "VS Code" and "Visual Studio" are DIFFERENT IDEs! I refer to VS Code as VS Code and Visual Studio as Visual Studio.*


** *Source Control*

[[file:images/sourcecontrol.png]]

Source Control is a system for keeping track of changes to source code over time
and managing the change and merging of source code. Some various systems include
*Git*, *TFS*, and *SVN*, and there are older ones as well. We will be using Git.

To utilize source control, there will be a *server* that stores the *repository* for the project
in question. Each team member on a project will also have a *local* copy of that source code
on their own machine. They work on their own computer, and once done they *push* their changes
to the server. The system mostly takes care of automatically merging /your version/ of the code
with whatever version is on the server.

*GitLab* is a service that hosts Git repositories. GitHub is also a popular source control
hosting platform. We will be using GitLab during this semester.

For this class you will have a *personal repository* that I create for you.
Both of us will upload code to this repository - I might add notes when grading or add
additional assignment code as needed.

We may also have a *group repository* for the class for the semester's projects.
We can emulate working on a real codebase like this, teaching some professional development
skills as well.

The GitLab website also provides us with some project management tools such as creating
*Tickets/Issues* to track information like what changes should be made,
list of *Commits* to show who changed what and when, and *Wiki* hosting to add documentation.


* *Part 1: Setting up a GitLab username*

[[file:images/logo-gitlab.png]]

Before we get started with the rest of the setup you should first create
a GitLab account and submit the Canvas assignment *"Setup: What is your GitLab username?"*.
Once I have your username, I will give you access to your own *repository*
where you will store your code throughout this semester.

To create an account, go to
https://gitlab.com/users/sign_up

Select whatever Username you'd like - the school SSO is recommended,
but note that you may be working with classmates in a repository
so you can choose something non-self-identifying if you'd like.

*Note: If you register with a Google, GitHub, or Bitbucket account, you will need to do a PASSWORD RESET from the settings menu in order to create a GitLab password!*

After you've created an account, go to your *Profile* by clicking your avatar-circle and clicking on your username.
Your profile page should have a URL like https://gitlab.com/rsingh13 .
This is the URL you will paste into the *"Setup: What is your GitLab username?"* assignment so that I can find you.




* *Part 2: Installing and configuring Git*

[[file:images/logo-git.png]]

** *Installing git*

Go to the *git* homepage (https://git-scm.com/) and download the installer for your platform.
You can view the steps to install Git in a video I made:

- Install Git: https://youtu.be/fKIX98YEbFU


** *Configuring git*

Once the installer is done we will need to do a little configuration.
From the Start menu, find *Git Bash* and open that. (On Mac/Linux, just open your *Terminal*.)

In the Git Bash/Terminal, type each of these commands separately (or copy/paste) and hit ENTER after
each one. Make sure to update "you@example.com" with your own email (e.g., student email if wanted)
and "Your Name" with the name you want to show up on GitLab. The third command doesn't require
any changes.

1. =git config --global user.email "you@example.com"=
2. =git config --global user.name "Your Name"=
3. =git config --global pull.rebase false=

These steps only need to happen when you've just installed Git, so you won't need to do it anymore
unless you install Git to a new computer.

** *Cloning your student repository*

Once I've gotten your GitLab username in the *"Setup: What is your GitLab username?"* assignment
I will give you access to your repository's webpage on GitLab. Make sure to bookmark this page!
It will be something similar to:

https://gitlab.com/rsingh13-student-repos/2024-06_cs200/cs200-rsingh13-repo

reflecting the semester, course, and your school SSO in the URL. This repository is *private*
and only you and I can see and work with it.

From your repository webpage, click on the blue *"Code"* button and *copy* the URL under *"Clone with HTTPS"*.

[[file:images/welcome_setup-giturl.png]]


Next find a location on your computer where you want to store your course assignments.
Right-click in the empty space here and select *"GitBash Here"*.

The *clone* command allows you to pull down a repository from a server. You only need to do a clone
once per computer. Enter the following command, pasting in the URL you copied previously:

#+BEGIN_HTML
\begin{lstlisting}[style=terminal]
git clone URL
\end{lstlisting}
#+END_HTML

After you hit enter it will pull down the files.

[[file:images/welcome_setup-clonedrepo_bash.png]]

If you go back to your File Explorer, you will be able to see your *cs250-XYZ-repo* (or *cs235-XYZ-repo*)
now in the location you chose. *All of your course code must go in this directory*.
I will have setup instructions in early lab assignments.

We will work with Git a little more after we get all of our tools set up.


* *Part 3: Downloading your IDE*

If you're familiar enough with programming and computer software you can use whatever
IDE/compiler tools you want for this course. However, there are recommended IDEs I list
so that I can help out with diagnosing issues, so if you're still pretty new, please choose
from one of these.

|-------------------------+--------------------------------------------------+-------------------+---------------------------------------------------------|
| *IDE*                   | *Link*                                           | *Platforms*       | *Notes*                                                 |
|-------------------------+--------------------------------------------------+-------------------+---------------------------------------------------------|
| Visual Studio Community | https://visualstudio.microsoft.com/vs/community/ | Win               |                                                         |
|-------------------------+--------------------------------------------------+-------------------+---------------------------------------------------------|
| Code::Blocks            | https://www.codeblocks.org/downloads/binaries/   | Win / Linux       | WINDOWS users download the "mingw-setup.exe" version    |
|-------------------------+--------------------------------------------------+-------------------+---------------------------------------------------------|
| Xcode                   | https://developer.apple.com/xcode/               | Mac               |                                                         |
|-------------------------+--------------------------------------------------+-------------------+---------------------------------------------------------|
| VSCode                  | https://code.visualstudio.com/                   | Win / Linux / Mac | Only recommended if you have issues with the other IDEs |
|-------------------------+--------------------------------------------------+-------------------+---------------------------------------------------------|

Visual Studio Community can be a bit annoying to set up. I have some videos that show the step to set up
most of the IDEs:

- Install Visual Studio: https://youtu.be/LRNbq2a3rPk
- Install Code::Blocks: https://youtu.be/ZRp2N9k_1jE
- Install VS Code: https://youtu.be/HJ8AtZ0eVxw

I don't have a Mac so I don't have a way to record a setup video but I could possibly help you
via a Zoom screenshare or on campus.

[[file:../_images/pixel-practice.png]]


* *Part 4: Testing everything out*

Now that we have our software installed let's test everything out.

** *Create a new project*

Open your IDE. You will create a new project within your repo folder, under the =u00_Setup= folder.

| [[file:images/ico-vs.png]] |                                                                                                                                                 |
|                        | *Visual Studio:*                                                                                                                                |
|                     1. | From the start screen click *"Create a new project"*.                                                                                           |
|                     2. | Select *"Empty Project"* for C++ and click *"Next"*.                                                                                            |
|                     3. | Give your project a *"Project name"* and set the *"Location"* to with your repo folder and /inside/ the =u00_Setup= folder. Then click *"Create"*. |



| [[file:images/ico-cb.png]] |                 |
|                        | *Code::Blocks:* |
|                     1. | From the start screen click *"Create a new project"*.                |
|                     2. | Select *"Empty project"* then click *"Go"*.                |
|                     3. | Give your project a *"Project title"* and set the *"Folder to create project in"* to your repo folder and /inside/ the =u00_Setup= folder. Then click "*Next*".                |
|                     4. | The rest of the defaults are fine, continue and click *"Finish"*.                |



# | [[file:images/ico-xc.png]] |                                                                                                                                                              |
# |                        | *XCode:*                                                                                                                                                     |
# |                     1. | From the start screen click *"Create a new Xcode project"*.                                                                                                  |
# |                     2. | Select the *"macOS"* tab, then select *"Command Line Tool"* and click *"Next"*.                                                                              |
# |                     3. | Give your project a *"Project Name"*, and under the *"Language"* dropdown select *"C++"*.       Use whatever for Organization identifier, then click *"Next"*. |
# |                     4. | Select a directory where to save the project. This should be within your repo folder and /inside/ the =u00_Setup= folder.  Click *"Create"* to finish up.    |



| [[file:images/ico-vsc.png]] |                                                                                                |
|                         | *VSCode:*                                                                                      |
|                      1. | Go to the *File* drop-down menu and select *Open Folder*.                                      |
|                      2. | Navigate to your repo folder and /inside/ the =u00_Setup= folder. Click the *"Select"* button. |

*Videos:*

1. Create a new project in Visual Studio: https://youtu.be/4f1UJSGAcT8
2. Create a new project in Code::Blocks: https://youtu.be/mGoCoV0L8hU
3. Create a new "project" in VS Code: https://youtu.be/rNF7ZZW5Biw
4. (CS Hero's YouTube) Create a C++ project in Xcode: https://youtu.be/v=j_2Ows2hXHg


** *Add a new file to your project*

| [[file:images/ico-vs.png]] |                                                                                                                      |
|                        | *Visual Studio:*                                                                                                     |
|                     1. | On the right-hand side is the *Solution Explorer*. Right-click your PROJECT and select *"Add"* then *"New Item..."*. |
|                     2. | Give it a name such as "test.cpp" and click *"Add"*.                                                                 |
|                     3. | Double-click your new file to open it in the editor.                                                                 |



| [[file:images/ico-cb.png]] |                                                            |
|                        | *Code::Blocks:*                                            |
|                     1. | Go to the *File* drop-down menu and select *"Empty file"*. |
|                     2. | It will ask if you want to save the file, click *"Yes"*.   |
|                     3. | Save the file as "test.cpp" and click *"Save"*.            |
|                     4. | Double-click your new file to open it in the editor.       |



| [[file:images/ico-vsc.png]] |                                                                                                  |
|                         | *VSCode:*                                                                                        |
|                      1. | Go to the *File* drop-down menu and select *"New File..."*.                                      |
|                      2. | Go to the *File* drop-down menu and select *"Save As..."* and name it something like "test.cpp". |
|                      3. | Double-click your new file to open it in the editor.                                             |


*Videos:*

1. Create a new file in Visual Studio: https://youtu.be/9-VgiCXgdxk
2. Create a new file in Code::Blocks: https://youtu.be/q9D8LIn0QCg
3. Create a new file in VS Code: https://youtu.be/obcAcHvAltk




** *Build and run your program*

First, add the following C++ code to your file. We will cover the details later on, this is just to make sure
everything builds and runs properly. You can replace "XYZ" with your own name. *Note that copy-pasting from a PDF file
may result in hidden invalid characters, causing build errors!*

#+BEGIN_HTML
\begin{lstlisting}[style=cpp]
#include <iostream>
using namespace std;

int main()
{
    cout << "Hi, I'm XYZ!" << endl;
    return 0;
}
\end{lstlisting}
#+END_HTML

| [[file:images/ico-vs.png]] |                                                                                                                                           |
|                        | *Visual Studio:*                                                                                                                          |
|                     1. | From the *"Build"* drop-down menu select *"Build Solution"*.                                                                              |
|                     2. | A bottom "Output" window will pop up and run the build. It should say "1 succeeded" after a bit.                                          |
|                     3. | Click on the *"Local Windows Debugger"* button in the toolbar, or go to *"Debug"* and select *"Start with Debugging"* to run the program. |



| [[file:images/ico-cb.png]] |                                                                                                                        |
|                        | *Code::Blocks:*                                                                                                        |
|                     1. | From the *"Build"* drop-down menu select *"Build"*.                                                                    |
|                     2. | A bottom "Build log" window will show the build progress. Once it's done building it should say "0 errors 0 warnings". |
|                     3. | Click on the *"Build"* drop-down menu and select *"Run"* to run the program.                                           |



| [[file:images/ico-vsc.png]] |                                                                                                                                        |
|                         | *VSCode:*                                                                                                                              |
|                      1. | From the *"View"* drop-down menu select *"Terminal"*.                                                                                  |
|                      2. | Within the terminal, type in =g++ test.cpp= to tell the g++ compiler to build your source file. No message means there were no errors. |
|                      3. | To run your program, type =./a.out= for Linux/Mac or =./a.exe= for Windows.                                                            |


Every time we make changes to our code we need to *save the file* and *Compile/Build the project*.
The compile process turns our C++ source code into an executable (runnable) file. If you don't re-build
after your changes you will be running an /old version/ of your program.
When you run the program it will pop up a little terminal with your hello message.


*Videos:*

1. Build your code in Visual Studio: https://youtu.be/DmrgpzXUk2w
2. Run your code in Visual Studio: https://youtu.be/pP0SWeDHNaQ
3. Build and run your code in Code::Blocks: https://youtu.be/OY1Pg7Ao990
4. Build and run your code in VS Code: https://youtu.be/lps2-W7B4H0

After your project builds successfully we can use Git to back up our work to the server.
Save and close your project, if you want to open it again later just locate your project file
from the =u00_Setup= folder and double-click the project file. (In Visual Studio it will be *.sln*,
in Code::Blocks it will be *.cbp*, and in VS Code just open the folder.)



** *Backing up your changes with Git*

From your File Explorer open up your repository folder on your computer. When you click in the /blank space/
in this folder, the *"Git Bash Here"* option should show up (or *"Open Terminal Here"* for Linux and Mac(?)).
There are several steps to make backups but it is only a few commands each time.

*** =status= - *Check what files changed*

#+BEGIN_HTML
\begin{lstlisting}[style=terminal]
git status
\end{lstlisting}
#+END_HTML

The "git status" command will show you what file(s) have changed since your last backup.
You can use this to double-check that your changes are showing up before you do your backup.

*** =add= - *Add which files you want to back up*

#+BEGIN_HTML
\begin{lstlisting}[style=terminal]
git add *.cpp
\end{lstlisting}
#+END_HTML

The =add= command lets you tell Git which files you want to backup. Sometimes you might not want
to back up every file since you're not done with them yet. There are several forms you can use:

| *Form*              | *What it does*               |
|---------------------+------------------------------|
| =git add *.cpp=     | add /every .cpp file/        |
| =git add *.cpp *.h= | add /every .cpp and .h file/ |
| =git add .=         | add /every changed file/     |
| =git add FILENAME=  | only add the given file      |

I've set up a special =.gitignore= file in your repository as well, so you can use =git add .= without
a bunch of garbage files being automatically added. When our IDEs build our files, it generates a bunch
of temporary files - we don't need those backed up.

For this assignment,  use =git add .=

*** =commit= - *Make a backup snapshot*

#+BEGIN_HTML
\begin{lstlisting}[style=terminal]
git commit -m "Description"
\end{lstlisting}
#+END_HTML

The =commit= command takes all your file changes and packages them up as a snapshot,
the curren status of these files. Usually on the job you'd make several /commits/ as you
work on a new feature so that you have periodic backups. Making a commit /does not send/
your files to the server yet - we are still working locally.

The =-m= portion means "message", it is often required to add a message or description
of what you worked on as part of your commit message. You can replace ="Description"=
with a message of what you changed.

For instance: =git commit -m "Finished setup"=

*** =push= - *Send your changes to the server*

#+BEGIN_HTML
\begin{lstlisting}[style=terminal]
git push
\end{lstlisting}
#+END_HTML

The =push= command takes all your pending commits and sends them to the GitLab server,
then they will be backed up and you can reference your latest and all previous versions
of your files.

If the push command gives you an error message, try using =git push -u origin main= instead.


** *View your changes on the GitLab server*

Go to the webpage you should have bookmarked earlier, where your course repository is
( for example, https://gitlab.com/rsingh13-student-repos/2024-06_cs200/cs200-rsingh13-repo )
You should now see your latest commit message near the top of the page:

[[file:../../../reference/images/gitlab_web_commitmessage.png]]

If you make multiple commits and push those commits you can go to the *"Code"* section in the left-side
navigation bar and select *"Commits"* to see the list of all changes.

[[file:images/welcome_setup-commitlog.png]]

** *Looking at merge conflicts*

From your *repo homepage* click on the =u00_Setup= folder and select your =test.cpp= file
(it might be in a subfolder further in).

[[file:../../../reference/images/gitlab_web_editfile1.png]]

When you click on it you can preview the code. Select the blue *"Edit"* button and select *"Edit single file"*.

[[file:../../../reference/images/gitlab_web_editfile2.png]]

From the web-based text editor, change your code so that instead of saying "Hi" it says something else like "Hello".

At the bottom of this webpage click on the *"Commit changes"* button.
Now the server has a new version but you still have the /older/ version of the source file on your own computer.

On your hard drive in your repository folder, open up =u00_Setup= and open your project again in your IDE.
Just make a small change, similar to what you did on the web, but different - change "Hi" to a /different/
word, like "Goodbye", and save your changes and close your IDE.

Now there are two different updates: A /server/ version and your /local/ version.
This is similar to what might happen when working at a company where multiple employees
might make modifications to the same files. Most of the time Git is pretty good at merging
changes together, but if two people edit the /exact same parts of the code/ then Git
has a hard time knowing which is the proper version to use.

Open up *Git Bash* or your *Terminal* within your repository directory. Go ahead and make an add and commit
to back up your current changes:

#+BEGIN_HTML
\begin{lstlisting}[style=terminal]
git add .
git commit -m "Changed text in u00 Setup"
\end{lstlisting}
#+END_HTML

If you try to do a =push= now it will give you this error message:

#+BEGIN_HTML
\begin{lstlisting}[style=terminal]
! [rejected]
error: failed to push some refs
hint: Updates were rejected because the tip fo your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
\end{lstlisting}
#+END_HTML

[[file:images/git-pushfail.png]]

This is talking about there being new updates on the server and that you need to =pull= latest changes
before you can backup your changes. To do this, we use:

#+BEGIN_HTML
\begin{lstlisting}[style=terminal]
git pull
\end{lstlisting}
#+END_HTML

This will bring down the changes and attempt a merge.
However, we will get a merge conflict - I want to show you how to resolve these
just in case you encounter one. You will get a message like this one:

#+BEGIN_HTML
\begin{lstlisting}[style=terminal]
Auto-merging FILENAME
CONFLICT (content): Merge conflict in FILENAME
Automatic merge failed; fix conflicts and then commit the result.
\end{lstlisting}
#+END_HTML


Open your project in your IDE again. Once you do, you will see some =<<<=
and
=>>>= markers, these denote the two different changes detected:

#+BEGIN_HTML
\begin{lstlisting}[style=cpp]
#include <iostream>
using namespace std;

int main()
{
<<<<<<< HEAD
    cout << "Hello, I'm XYZ!" << endl;
=======
    cout << "Goodbye, I'm XYZ!" << endl;
>>>>>>> a0c7bd54e2c5c19d1ebd41a84e7a6b8820573cf9
    return 0;
}
\end{lstlisting}
#+END_HTML

To merge this, you can choose whether you want the "Hello" version or the "Goodbye" version -
erase everything else that you don't need. I would then close your IDE again.


Back in *Git Bash* or your Terminal, finalize your merge and back everything up to the server:

#+BEGIN_HTML
\begin{lstlisting}[style=terminal]
git add .
git commit -m "Done merging"
git push
\end{lstlisting}
#+END_HTML

Your changes should now successfully be uploaded to GitLab.

** *Turning in your work on Canvas*

Once you're done with a programming assignment you will need to submit it on *Canvas*
so that it gets marked as awaiting grading. I generally want you to submit a URL to your
repository, in the folder that you were working in.

Open up your gitlab repository webpage and copy the URL here:

[[file:images/welcome_setup-gitlaburl.png]]

On Canvas locate the corresponding assignment (this assignment is *"Lab: Setting up your system & tools"*).
Open it up and click *"Start Assignment"*.

[[file:../../../reference/images/canvas-start2.png]]

Paste your gitlab URL into the *"Website URL"* box and click *"Submit Assignment"* to finish submitting your work.

[[file:../../../reference/images/canvas-submit.png]]

You are now done with the setup assignment!

* *Why use Git?*

- *Easy problem solving:*
  When you get stuck on a programming assignment you can add/commit/push your changes so far
  and I can easily pull them down on my computer to build and check the code. I can add comments
  into your code and do my own add/commit/push which you can then pull down and continue working with.



- *Professional tool:*
  Git and source control is an important tool of professional software developers. It will be much
  less stressful for you to learn the tool during a class where I can help you out than trying to
  learn it on the job with real, "important" code. :)



- *Working with a team:*
  Group project assignments in the course will be made easier to coordinate by using source control.
  We will also use various project management tools within GitLab to help emulate working in a
  real development team.



- *Backing up your work:*
  The work you've pushed to GitLab will be saved on a server and still available even if your computer
  is destroyed or dies during the semester. You can pull down your repository from any computer
  as long as you remember your login information and continue working from there.

  You can also check old versions of your work, if you end up making an error but you don't know what
  changed - you can make a commit and check the difference between the last working version and the
  current version.


- *Good for portfolio building:*
  You can create a portfolio repository with your GitLab account and put various projects in there.
  This can be useful for when you're applying for jobs and want to add a portfolio of coding projects
  to your resume.


[[file:../_images/cuties/team.png]]