Computing stuff tied to the physical world

Out with the old – in with the new!

In AVR, Software on Dec 29, 2011 at 00:01

Le roi est mort …

It’s time to move on. I’m dropping all support and maintenance of the Ports and RF12 libs, as well as some others. Well, as far as subversion is concerned. All files are kept read-only at svn.jeelabs.org – for reference.

… vive le roi!

But the good news is that all this software has now been moved and updated on GitHub … and is fully supported.

All libraries on GitHub have been adjusted to work with Arduino IDE 1.0 (they may or may not still work on 0022 or 0023, but that will be supported only to the point of accepting patches to increase backward compatibility).

There is one change which I’ve been meaning to get to for a long time: the Ports and RF12 libraries have been combined into a new library called JeeLib. This means that you no longer have to include “Ports.h” and “RF12.h” at the start of your sketches (although those still continue to work). Instead, insert this one line instead:

    #include <JeeLib.h>

All the examples from both libraries have been retained, but make sure that the old Ports and RF12 are gone.

There are three other libraries for the JeeNodes which you may be using: EtherCard, GLCDlib, and RTClib. These too are now on GitHib and have all been adapted for use with Arduino IDE 1.0.

So how does one start using any of these libraries? Ah, glad you asked :)

  • go to GitHub, and pick the library you’re interested in to get to its home page
  • at the bottom of each home page is a README section with the latest info – always worth a check
  • one of the links at the top is marked “ZIP” – you could click it to download everything as ZIP archive
  • … but you shouldn’t !

The reason for this is Git. If you download a ZIP archive, unpack it, and install it in the right place (which is in the “libraries” folder where all your sketches are), then you’ll get a copy of the code your after, but no way to stay up to date. That might sound like a minor detail, but with open source, there are usually many changes over time. Bug fixes as well as new features. If you grabbed a ZIP file, then you’ll be forced to re-install the next version over the previous one every time there is an update. This quickly gets very boring, and can lead to all sorts of awful mistakes, such as overwriting a file you had fixed in some way (after a lengthy debug session, long ago).

I can’t stress it enough: don’t grab open source software and install it on your disk by just downloading and unpacking it. Not just the stuff from JeeLabs – any open source software distributed in source code form. It’s a nuisance, a ticking time bomb, a mine field, a disaster waiting to happen – get the message?

There is only one sane / long-term approach to working with source code, and that’s through a Version Control System. In this case Git – in combination with GitHub, which is the web site where all source code is stored.

So instead of downloading a ZIP or TAR archive, you need to create a “clone” of the original code on GitHub. The difference with the ZIP archive is that a clone knows where it came from, and gives you the ability to find out what changed, to instantly update your clone, or to revert to any older version, since GitHub keeps track of all versions of the code – past, present, and future.

The trick is to get started with Git and GitHub without drowning in the capabilities they offer. How depends on the environment you’re in:

  • On Windows, you can install TortoiseGit – then you need to get that clone onto your machine. For JeeLib, you’ll probably need to enter this path to it somewhere: git://git.jeelabs.org/jcw/jeelib.git

  • On Mac OSX, you need to install the Xcode developer tools, which includes Git (it’s a free install from the App Store). If you have an account at GitHub (or don’t mind getting one, it’s free), then I highly recommend getting the GitHub for Mac application. If not, you can always use the command line, like so:

        cd ~/Documents/Arduino/libraries
        git clone git://git.jeelabs.org/jcw/jeelib.git
    
  • On Linux, you need to install git through whatever package manager you’re using. On Debian / Ubuntu, this command line will probably do it:

        sudo apt-get install git-core
    

    After that, it’s the same as the Mac OSX command-line version, i.e. “cd …” and “git clone …” (see above).

So far, this is only a little more involved than grabbing that ZIP file. The gains start when you want to update your copy to the latest version. In git-speak, this is called “pulling” the latest changes (to your local disk). I encourage you to search around on the web, it’s usually as simple as doing “git pull” from inside the cloned area (from the command-line, some GUI, whatever). The difference with re-installing is absolute security – “git pull” will never overwrite or lose any changes you made, if they conflict with the original.

If all you do is track changes from time to time, then this is all you need to benefit from Git and GitHub.

If you actually make changes, then you’ll need to dig a little deeper when a “conflict” occurs, meaning you’ve made a change which interferes with changes made in the original on GitHub. But on the plus side, you’ll also be able to easily submit your changes (GitHub calls this “making a pull request”, i.e. pulling your changes back into the original). Why bother? Because contributions, no matter how small, are what make open source software fly!

Welcome to the world of open source software collaboration – where code lives, evolves, and grows.

  1. I am not sure the statement about grabbing everything from vcs all the time, is actually correct. A lot of software is pinned at specific library releases. New libs add features that can break backwards compatibility. So you have repositories of known good releases all pegging their dependancies. This is how tools for python like distutils, easy_install etc.. work. So it really depends if your running open source packaged releases or developing from a mainline trunk or branch etc… If the later then what you say is correct. If your trying to run some app server of a particular release then you would be installing packages.

    • Yes, I agree – good point. I was really writing this with the Arduino / embedded ecosystem in mind, which tends to be smaller scale, more ad-hoc, and more bug-fix oriented.

      As an example, the EtherCard was updated yesterday, merging changes from a separate “development branch” – so if you were tracking the master branch, you’d see no changes until now, whereas if you were on the development branch, you’d have seen all the little changes from the recent past. So one way this distinction works out in Git is with branches, i.e. stable (the “master” branch) vs work-in-progress (other branches).

      OTOH, I tend to push fixes and new additions to JeeLib directly to its master branch. It’s more an evolutionary process.

  2. Hi jcw.

    I knew that was your angle, but I felt a lot of new people to Jeelabs are also new to the whole world of open source, or at least seeing it at this level for the first time, and it was worth pointing out the different scenarios, may mean different strategies for getting code.

    I have been actively promoting and utilising open source software since the early 90’s, and your site and the information you publish is really incredibly valuable, and approachable for people coming to this corner of technology.

    Its a real gem

    Cheers

    Tim

  3. great post, I never have really looked at git, but with this post and the cvs one the other day I have taken the plunge!. Created account, downloaded Android 1, made a clone of jeelib and changed my includes…and it all still works !

    I agree with comments around testing of new libs before they are deployed, I have two jeenode projects which are now almost ‘business critical’ (sprayer control and irrigation control), I have already had an issue with a s/w change I made, so no more time machine backups for me, git it is.

Comments are closed.