Overview
For this assignment, will be primarily getting your environment set up, making sure it works, and doing a test commit and tag.
Assignment Goals
The primary goals of this assignment are:
- Make sure you have the tools you will need.
- Get a copy of your class git repository.
- Make sure you can build and run code.
- Use git tags for submission.
Github
Git is free version control software that allows you to track multiple changes to files in a project, either locally or on a central repository or repo. It also helps you to keep the local and central repository histories in sync. Github is a web site that will host git repositories online. You will be using both git locally on your own computer to track your work, and github to submit that work and get new files from the course staff.
You will need a free github account to access and submit code for the class. Sign up for one if you do not already have one, then fill out the class github ID google form so we will be able to give you access.
Note that granting access to the class github repository is a manual process after you submit the google form, that will result in an email invitation you have to accept before you can get to the class materials on github. Do not leave it to the last minute!
Tools
Git
In addition to github, you will need some local git tools. You should not upload any files for this class using the github web interface. You will lose significant points if you do. On your local computer, you can use one of the many graphical user interfaces for git, the command-line tools, or a combination of both. Even if you are using a git GUI, the command-line tools are available, and it is possible to use them both on the same repository. Directions and help from the TA or instructor will be for the command-line tools. They are the common denominator for everyone, and it is usually easier to translate command-line instructions to a GUI than the other way around.
- Command-line tools:
- Windows: Download from git-scm.com. Will install a GIT bash terminal application you can use to run git commands.
- Linux: Use your package manager or download from git-scm.com.
- Mac: Comes with MacOS, and accessible from the Terminal.
- GUIs
- Github desktop (Windows/Mac): Popular, though not as polished looking or capable as some others. May have to fall back to the command-line tools more often than with some of the other GUIs.
- Sourcetree (Windows/Mac): Used to be my preferred git GUI. Need to register (free) to use.
- Fork (Windows/Mac): This is the one I currently use. $50 license, but free evaluation.
- Many more (including some for Linux).
CMake
CMake is a cross-platform tool for making build files (Visual Studio solutions, Makefiles, XCode projects, etc.) from a common CMakeLists.txt text-file description. This will help make sure we don't actually need to use the same OS as you to build, run, and test your code.
C++ tools
You will be using C++ for all of the programming assignments this semester.
- Linux: Probably already installed. You'll want the C++ compiler and make, eclipse, or your favorite C++ IDE.
- Windows: Install Visual Studio. The free "Community Edition" is fine. Make sure you have it set up with the "Desktop Development with C++" and "Game Development with C++" workflows. You can re-run the Visual Studio setup to change or add workflows if you aleady have it without these.
- Mac: Install Xcode.
PPM Viewer
You will need something to view ppm image files. On Windows, I have used Gimp, IrfanView, and the "display" program from ImageMagick. On Linux, I've primarily used ImageMagick's display or Gimp. On Mac, the built-in Preview app will open ppm files.
Get the Code
You will need a local clone of your github repository on your computer. This clone can have its own history of changes, that you will regularly sync up with the copy on github. Keeping things up to date on github will help keep you from losing work, and can help the instructor or TA to be able to look at your work in progress if you ask for help.
- If you have not already filled out the class google form to tell us your git ID, do it now!
- You will be manually added to the UMBCGAIM github group.
- Once you receive and accept the GitHub team invitation email, you will be able to see the class repository at github.com/UMBCGAIM/cg23.
- Fork the repository (using the "Fork" button on the top-right of the cg23 github page). This will make your own copy on github that you will use for the class. It will show up with a URL of the form github.com/your-git-ID/cg23.
- Make your own local clone of your copy of the repository. Click the "Code" button, copy the repository path it shows, and either use it in your GUI's clone, or use the command line
git clone repo-path
. There are plenty of online tutorials to help you clone a github repository.
Build & Run
You'll use CMake to create the build files for your platform (Visual Studio, Make, or XCode), then use that native tool to actually build and run.
- Go into the trace directory in your local copy of your class repository.
- Create a build directory there.
- Run CMake, pointing it to trace as the source directory, and build as the build directory.
- Build and run the test program:
- On Windows, open the resulting trace.sln, right click on trace in the solution explorer and choose "set as startup project", then hit the "play" button in the top ribbon to build and run.
- On Mac, open trace.xcodeproj, choose trace from the drop-down list next to the "play" button, then hit that "play" button to build and run.
- On Linux, type "make" in the build directory, then run the resulting "trace" executable.
- The test program should create a trace.ppm output file.
Commit
To tell git about your changes, you commit them to your local git history, then push those changes back to github. If there have been changes on github that are not in your local copy, you may also need to pull those changes back.
- Add trace.ppm to the files to be committed. If using the command-line git commands:
- Do a
git status
to see what files have changed (should be just trace.ppm). - Do a
git add trace/trace.ppm
to add it to the commit staging list. - Do a
git status
again to confirm if the files you want are staged to be committed.
- Do a
- Commit this change to your local history. If using the command-line git commands:
- Do a
git commit -m "Created test image file"
. - The commit messages can be short, but they should be descriptive!
- Do a
- Push that change to github:
- First merge in any changes from the github history you don't have yet:
git pull
- Then push your changes back:
git push
- First merge in any changes from the github history you don't have yet:
- Do a second commit: Create an assn0.txt file with notes on your submission. At a minimum, tell us what OS you are using, and if you ran into any problems. Follow the same steps to add, commit, and push that file.
Submit
Git uses tags to mark major milestones like software releases. In fact, on github you will see both the terms tag and release used. Since several assignments will build on each other in the same directory, we will be using tagged releases for you to tell what you want us to grade. You tag a release after you have committed it. The timestamp is not changed by tagging it, so you should be sure to commit by the deadline, but can tag that commit after the deadline. If you tag the wrong commit, it is possible (though a little tricky) to change it.
- To tag the latest commit as your assignment 0 submission and push it to github:
git tag assn0
git push origin assn0
- To move a tag:
- Delete the previous local tag:
git tag -d assn0
- Delete previous tag from github too:
git push --delete origin assn0
- Re-tag locally:
git tag assn0
- Push the updated tag back to github:
git push origin assn0
- Delete the previous local tag: