Prerequiste modules: Development Software Suite
Version control is fundamentally important to developers. Whether you are an individual working on your own design, or part of a multi-person team working on pieces of a large project, having a central repository and the ability to track and review changes is essential. Two very common tools are SVN and Git. In EiE we use Git.
Git is an excellent solution for firmware systems on which multiple developers work. Git uses a server or central host (very often cloud-based) as the distribution point for code. Larger companies may host their own Git server, while smaller organizations may use commercial cloud-based services. For EiE, we use Github – arguably the most popular open source Git service available. All EiE participants are encouraged to open a GitHub account and learn how to actively participate as that can be beneficial to you later on. You should not use Github for anything proprietary because it is all public domain.
GitHub
All the course firmware version control is managed in GitHub under the “eiefirmware” user account (https://github.com/eiefirmware). The things you need to know for now are:
- Firmware is organized in a tree-like structure where the “master” code is the main source.
- Branches are created where new development or features are added.
- All related branches (including the master branch) are stored together in a “repository” or “repo” for short. The repo holds all the code along with all the history of branching and updates. This is extremely important for developers, as they can carefully control, share, and review code, while at the same time reverting back to any previous version in the history.
- You can “Fork” a repository into your account to work on your own version
- Users “clone” (duplicate) the online code to their local machines to make changes either explicitly by downloading it, or by checking out branches through GitHub.
- Updated code can be pushed back online to the same branch or up the tree – Git provides a good way to review changes and pull them in to the main code, and GitHub presents that in a decent graphical user interface.
- Git is natively command-line based and the full feature set is only available that way. However, the GUI interface to Github (called Github Desktop) makes it easy to use for EIE.
To get started, create a user account on Github (www.github.com). Choose a user name that you would be ok with providing to a potential employer, teacher, or colleague. In this example, the user is “JRL0xFF.” Make sure you are logged in.
Given the way Git works there are lots of ways to manage the source code. A nice branching model is here. EiE will use Git in a slightly different way, where a main (Master) branch will contain the starting source code for most of the modules, and you will create a branch to work in for every activity. That way, the working code base is not disrupted, and you can easily switch to different module work. By the end of the program, you will have a branch for each module.
For this introduction to Git, we will start with the “Master” branch of the “razor_sam3u2” repository (https://github.com/eiefirmware/razor_sam3u2/tree/master):
Though you can simply click “Download ZIP” to grab an uncontrolled copy of the firmware as you might have done in the Development Software Suite module , it is highly recommended to download the Github desktop application and properly use Git to interact with the source code. There is also a quick Git Bootcamp right off the main Github page that explains the basics a bit more.
When using Git properly, you typically end up with a single code base on your computer that is the current branch that you are working with. If you change branches, your local code is automatically updated with the current code for the branch in Github. If you have changes, you will be warned to abandon them or commit them. Committing in Git is a local operation. Once committed, the changes can also be synchronized / uploaded to the repo in the cloud.
If you want to move updates from a branch back up the tree you use “Pull requests” to offer your changes to the branch manager (which might be you) who can review them and decide to merge them or not. For example, if you branched “Master” for this exercise and discovered a bug, you could fix the bug and send a pull request for the Master branch to pick up your change. Git can take that code and update the Master branch and alert any other branches that an update has been made. It would make sense that all branches should receive that code. You just have to be careful when propagating any change. In many cases, the change is made and all is well. However, if another branch has also changed code that is supposed to be updated, then a “merch conflict” can occur and you have work to do to understand what changes are trying to happen and properly synchronize everything. This can become quite a mess, so a diligent branching model, careful administration, and regular code submissions are critical for success. EiE will keep things simple so this shouldn’t come up, but keep it in mind as you build your experience with Git or any other version control software.
Managing course code in Git
Follow through this exercise to ensure you can access the online code and get a local copy on your computer. It is assumed that you have GitHub Desktop installed and are subscribed to or at least can find “eiefirmware “on GitHub.
Go to the “eiefirmware” user in Github and open the “razor_sam3u2” repository. Use the “Fork” button to bring a copy of the entire repository to your own account.
Look carefully at the image below. Use the default information EXCEPT uncheck “Copy the master branch only” box. This ensures you get all the branches from the original repo. Then click “Create fork.”
You should now see the forked copy of the razor_sam3u2 repository in your own Github account.
At the top left, select the “Master” branch. This is the branch you will use for the majority of the modules in EiE. Then click “<> Code” and select “Open with GitHub Desktop.”
Choose a folder name that you know will be used by Git – this is really important, because Git will be managing files in this folder. Don’t ever use this folder for anything else. Click “Clone” and wait for the files to download and add themselves into Github Desktop.
Once the download is complete, click Repository > Show in Explorer
Navigate to ../razor_sam3u2/firmware_ascii/iar_9_40_1 (this should match the version of IAR you installed). Double click “eie_ascii-01.eww” which should open the project in IAR. If it doesn’t, open IAR and drag the file into the workspace.
Do not change any files! Activate the GitHub Desktop window and you should see that some changes have automatically occurred just from opening the workspace. IAR always changes a few files whenever you open a Workspace — these are simply window position files and things like that. Remember that whatever branch you currently have active in Git on your computer will show that it has changes in Git Desktop once it was been opened in IAR.
Try switching from “master” to “application_board_test” branch.
You cannot switch branches without doing something about the pending changes to the current branch.
In older versions of Github Desktop, the changes had to be committed locally (saved) or discarded. Newer versions of Github Desktop give the options to “stash” the changes or even bring them to the new branch. It’s up to you, but there are many things to consider. Note it is very easy to get confused about what changes are happening and where you left off, so use caution and develop a system that works for you. Unless you are switching to a totally different project, it might be best to properly tidy up your code and commit the changes before moving on.
If it is just the project files where in 99% of the cases the changes do not matter, the changes can simply be discarded. Cancel the “Switch branch” operation in Github Desktop.
Switch back to IAR and choose File > Close Workspace so the files stop changing.
Go back to GitHub Desktop, right-click where it says “x changed files” and choose “Discard all changes…”
Now read this carefully! As long as your current branch has no changes, you can select a different branch from the drop-down. Once you do this, GIT AUTOMATICALLY RETRIEVES THE NEW BRANCH FILES AND REPLACES THE FILES IN YOUR ACTIVE PROJECT FOLDER. It is very possible to wipe out changes that you made in IAR because Git overwrites the files via actions taken in Github Desktop. It is really important to save any changes in IAR and close the workspace (or the whole IAR program) before fiddling around in Git.
In Github Desktop, change the current branch to “application_board_test” and this time it should change without any warnings. In IAR, choose File > Recent Workspaces and select the first option which is the last workspace that was open.
Expand the “Application > Source” tree to confirm that “ascii_board_test.c” is in the list. Compile the code. If you have a development board, download the code, run it, and make sure you see the Board Test application running on the system.
Close the workspace in IAR. Remember, you have not changed the code in any way.
Did you close the IAR workspace? If so, switch over to Github Desktop. If you had opened the workspace and compiled / debugged it, there will be 4 or 5 changed files. Discard all these changes.
Change the Current branch to “master”
Switch back to IAR and select the same “Recent Workspace”
You should see there is NO “application_board_test.c” source file now because you are working with a different branch. In fact, every file in the project is a different copy than what was in the board test project. Even though both branches look like they contain the same base files, the files themselves are copies and unique to each branch.
Build the code and flash your dev board. The board will boot but does not run any application since this is the master branch project now. The LCD should say “RAZOR SAM3U2 ASCII” but the board does nothing else.
Double-click main.c to open it. Edit the top of the file to add a line inside the comments to indicate when you forked the code.
Save everything in IAR and close the workspace.
Did you close the IAR workspace? Switch to Github Desktop and click on “main.c” in the file list. Note the changes described in the right-side panel match what you just did. Green highlight indicates addition; red highlight indicates something was deleted (not shown here unless you deleted something). Git will always highlight changes and it is good practice to look over them to ensure you know what is being updated before committing.
Unless you have made specific changes to the IAR workspace that you want to keep, uncheck any file with “settings” in the path. In this case, keep only the changes to main.c by leaving its checkbox checked. This helps keep the code commits cleaner so you aren’t saving endless history of whatever IAR does to modify the project files all the time.
Be sure to add a summary note for the commit. A long “Description” space is provided if you need to add more detail. When ready, click the “Commit to master” button.
Now discard the remaining changed files (from the workspace). You should see “No local changes” on the right hand side of the screen and an option to “Push origin” near the top right. If you do not push the changes, they will only be on your local machine. Clicking the button sends them to the Github server – do this now.
Open github.com and make sure you are in your razor_sam3u2 repo. You should see the commit you just did. Github also keeps track of your commits relative to the repo that you forked from eiefirmware.
If all of this has worked, you have done everything you need for version control in EiE. As you work through the program, you will inevitably make some mistakes with the version control and end up writing to the wrong branch, having conflicts with your commits, deleting changes you wanted to keep, or generally tying yourself in a knot especially if you start working on a repo with another person. It’s always a good plan to copy your working Git folder to somewhere safe when you have a good working piece of code you don’t want to list. Even though you *should* be able to undo or redo any changes thanks to Git, there’s
While there are many arguments in favor of various code control systems, no system is perfect. Git still relies heavily on the command-line interface for operations that are more than what can be easily used in the GUI. If you use Git regularly in industry, we would recommend taking the time to really get to know the shell interface and your company’s version control model.
[LAST UPDATE: 2023-SEP-18]