Use SVN and Git to access and contribute to the course firmware
|Platform||Test Tools||SAM3U2 Firmware||nRF51422 Firmware||Software|
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.
SVN is straight forward to use and works well for code, documents or any other files that tend not to diverge to different versions or feature sets. Git is an excellent solution for firmware systems that multiple people will work on and/or will have new features or parallel builds. SVN and Git both use a server or central host (very often cloud-based) as the distribution point for code. For SVN, we use a host called xp-dev. For Git, we use Github – arguably the most popular open source Git service available. All users are encouraged to open a GitHub account and learn how to actively participate as that can be beneficial to you later on.
All the course firmware version control is managed in GitHub. The things you need to know 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.
- Users duplicate the 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 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.
Given the way Git works there are lots of ways to manage the source code. A nice branching model is here. All of the code-based exercises are set up with links that go directly to the specific branch you need on GitHub (in most cases we start with the clean Master branch). Try clicking the “SIMULATOR CODE” link at the top of the page to access the SAM3U2 firmware for this exercise.
Though you can simply click “Download ZIP” to grab an uncontrolled copy of the firmware, it is highly recommended to download the Github desktop application and properly use Git to interact with the source code. When Git Desktop is installed, it will also install Git Shell for command line access. The shell is a much more powerful interface to Git. There is a quick Git Bootcamp right off the main Github page. A short introduction to some of the most common features is here: Git-Bash Instructions (thanks to Maddie Lowe for putting this together!)
When you are 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. Unlike SVN, committing is a local operation. If you want to push updates from a branch back up the tree you use “Pull requests” to offer your changes to the branch manager who can review them and decide to merge them or not.
Managing course code in Git
Follow through this short 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 Engenuics on GitHub.
Clone the Razor_Atmel repository either from github.com (shown on the left) or in GitHub Desktop (shown on the right)
At the top left, select the “Master” branch. This is the branch you will use for the majority of the modules in this course, so make sure this works. As soon as you make the selection the files in the local Git directory you chose will be updated with the Master branch.
Now open the Workspace in IAR but do not change any files. Activate the GitHub Desktop Window and you will likely see that some changes have automatically occurred. IAR always changes 3-6 files whenever you open a Workspace — these are simply window position files and things like that. Therefore, whatever branch you currently have through Git on your computer will show that it has changes in GitHub.
Try switching from “master” to “simulator” branch. You cannot switch branches without doing something about the pending changes to the current branch. They must be committed (locally) or discarded. If it is just the project files where in 99% of the cases the changes do not matter, the changes can simply be discarded. First, close the Workspace in IAR so the files stop changing. Then in GitHub Desktop, right-click where it says “changes” and choose “Discard all changes”
Remember, this is all happening locally which can be confusing. To access the main repository in the GitHub cloud, you must click the “Sync” button. This will copy all local commits up to the cloud, and will refresh your local copy. If you want to push a change from a branch into the Master (or back to wherever you branched from), you must do a “Pull request.” You can read all of the GitHub documentation about how it works, how code can be reviewed, and how conversations between developers can be had. A Pull request through GitHub is an all-or-nothing process which is one grievance we have with GitHub and GitHub Desktop. You cannot pick specific changes to accept from a pull request. All local commits are bundled together and the pull request has to be accepted entirely or rejected. Much more control for “cherry picking” and patching is available on the command line through GitShell.
As long as your current branch has no changes, you can select a different branch from the drop-down. THIS WILL AUTOMATICALLY RETRIEVE THE NEW BRANCH FILES AND REPLACE THE FILES ON YOUR ACTIVE PROJECT. This should still be safe because in order to take this step, you had to commit your changes (or discard them).
Open IAR back up and open up the Workspace again. Hint: you can always use “Recent Workspaces” to access the project in the Git directory. Since that location is where GitHub always puts the Branch code, you do not have to go searching for it. The files present should be different if you look around. Press Ctrl-D to start the debugger — this will work even if you do not have a development board plugged in because the SIMULATOR branch is set up to run in the IAR simulator. It does not do too much, but this sets you up for the next module.
If you plan to develop your own code, you should fork the repository to your own account and work there (or work in branches there). You can still merge updates from the Razor_Atmel Master into your code if we fix bugs or add features. If you find a bug, you are welcome to submit a pull request so we can review it and bring it in. Please make sure you only send pull requests with a manageable number of changes. It is suggested that you submit only one or two changes at a time since the pull request is an all-or-nothing merge. You might have 99 great updates to contribute, but the pull request will be closed without merging if there is a problem with one of them.
We use SVN to manage information that is not intended to be modified by our users and will not have multiple versions and features. It is mostly an archive for the “MPG” version of our program and it will likely disappear over time. For now it will largely be devoted to code releases, notes or other non-code files that need to be distributed. In this case we prefer it over Git because SVN offers more traditional file access.
Like Git, SVN requires a local client application to access the SVN server. We prefer Tortoise SVN as it gives you fast context-menu access to SVN. Once you have an SVN client, use the following information to access the course repositories:
- Public (read/write access) for sharing files: https://xp-dev.com/svn/mpg_public
- Source (read-only) for notes and archived code builds: https://xp-dev.com/svn/mpg_source
- In both cases, the username and password are mpg-user
Once you have Tortoise SVN installed, create an EiE SVN directory, open the directory in Windows file explorer and then right-click the directory and choose SVN Checkout…
Copy and paste one of the two repository links above into the Checkout window. Enter a Checkout directory (we suggest using the repository name) and leave everything else default. Enter the user authentication. You should then see a window showing a whole bunch of files transferring to your computer. This is known as your “working copy.”
SVN works like Git in that you work on a local copy and has much less control over how changes are merged. SVN uses “update” to get changes from the server, and “commit” to push changes to the server (assuming you have write access). There is no chance to approve changes before they update the central repository. There is also no easy way to branch code like there is in Git. Likely the more you use Git, the less you will use SVN especially for projects with multiple developers. SVN is still a great tool for certain applications. Notice that Tortoise SVN will add different icons to tell you if files are current (green check), modified but not committed (red !) or queued to be added. New files will not have any icon.
It is a good idea to regularly commit changes to the server, though you have to manage this carefully. For raw-text files, SVN does a decent job of automatically merging the code you write into the repository. It also has a built-in “Diff” tool that will help you compare files that are flagged as “conflicted” when SVN commits or updates. Neither Git or SVN can merge or show differences with binary files like Word documents or Altium files, however SVN can still be used to keep those central and at the latest version. The worst case is that a conflict occurs and you have to either revert and lose some changes, or manually go through the files. At least you know that there was an issue, though.
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 or online. If you use Git regularly in industry, we would recommend taking the time to really get to know the shell interface as then you will really have control over your code repository.
2018-APR-27: Add Git Shell instruction link
2016-MAR-04: First release