Subversion – folders and projects

This post is about folder structures and project management in Subversion.. If you don’t already know what Subversion is check out the previous post: http://blog.akademy.co.uk-tips/2009/09/source-control-beginning-with-subversion/

Folder Structure

The folder structure you implement in your repository can have significant impacts on how well your project gets managed, now and in the future. With the right forethought you can implement things like:

  • release version tagging,
  • multiple simultaneous version releases
  • and have code, installers and build systems all in the same place.

Tags – release version tagging

Tagging is the term used to “mark” a certain version of your files as important in some way. Most often this will be to mark public releases of your code, this enables you to go back to that specific version even after other changes and version releases have taken place. In Subversion there is no specific tagging mechanism, instead you simply take a copy of the code as it is at the moment. Now this sounds like it would use a whole lot of memory space but you need to remember that Subversion only ever records the changes between files – a tag will not not have any changes in so is virtually copied for free.

To keep track of all your tags you’ll need somewhere to put them and in subversion this means a folder. So in the top level repository folder have a folder called “Tags”. Lets assume you have another folder called “Main” for now which contains your source, to create a tag you’d just copy it, so type something like:

  1. svn copy file://your-path/TestProj/Main file://your-path/TestProj/tags/release-1.0 --message "1.0"

Branches – multiple simultaneous version releases

To work on multiple versions you’ll need to once again copy the main source code. You might need to work on two different releases if you have two major changes to the code which you want to test separately, or you need to make bug fixes in an old release but don’t want to mix up the new code, or you just want to try an idea but don’t want to mess with the main source.

You’ll need to keep this code separate also so create another folder at the top level of your repository. We’ll call this one “Branches” as you are copying the main code to subsequently change it – it branches away from the main part. Now You’ll just need to copy the main code, so type:

  1. svn copy file://your-path/TestProj/Main file://your-path/TestProj/branches/newtest --message "fixing"

This command is near identical to the tag one. This is because all you are “really” doing is making a folder and copying some files to it.

Main (or Trunk) –  code, installers and building

When you read up on subversion you’ll come across the folder “Trunk”. Once again, this is subversion so it’s just a folder, and it’s where you main source is edited from. (It’s called “Trunk”, because it’s where the “Branches” come from!). The above paragraphs have called in “Main”.

I tend to split my main folder into several others to make the full building of a program easier. Typically this will be something like “Source”, “Installers” and “Builder” – “Source” holds things like c++ files, “Installer” will hold the files needed to create an installer, and “Builder” is the files needed to automatically build all the bits into some kind of release, such as a CD; (you might like to add “Content” or “Manuals” or something else to your own). This is very useful when you need to tag something as everything needed to rebuild a specific release will be copied into that tag.

Trunk, Branches, Tags or anything.

Obviously the folders you’ll need will depend on your own project. Don’t be afraid to experiment with your own names and structures – the folders are yours to play with!

A few caveats on changing from “Trunk”, “Branches” and “Tags”

  • Some client programs can automatically create tags and branches if you stick to these folder names.
  • Much of the documentation will make reference to these folder names.

Multiple projects

Up until now I have assumed a single Project in your repository but that’s not the only way to do it. There’s two main ways to store multiple projects in Subversion, each with positives and negatives.

  • Create multiple repositories, one for each project.
  • Create a single repository with a top level folder for each project.

Multiple repositories, single projects

This is the simplest to manage. Every new project his it’s own repository and is entirely separate from any others.

Positives:

  • You can reduce the impact from a single hardware failure as repositories can be kept on separate hard drives.
  • You can backup each project separately, depending on it’s value.
  • You can easily give user access to a single project
  • User subversion errors limited to a single project.

Negatives

  • Users will need to be created separately for each repository.
  • The merging of projects is very difficult.

Single repository, multiple projects

A single repository, with top level folders for each project. Each sub folder has the usual “Trunk”, “Tags” and “Branches” in.

Positives

  • A single list of users is all that is needed.
  • A single, simple, backup procedure.
  • Merging of several projects into one is very easy.

Negatives

  • Can mistakenly give access to a user for any project.
  • Single hardware failure can wipe out all projects at once. Single backups also at risk.
  • A subversion user error in one project can impact all other projects.

Conclusion

There is no right and wrong way to store your folders. It really depends on your use, for instance I use subversion to back up my fiction writing, and it contains no folders just a list of files.

There are some best practices you should consider though, decide how you’ll make taqgs or branches if you’ll need them, and if you are going to use multiple or single project repositories.

However, if you are looking for a quick set up, I’d recommend having a single repository for a project, then a sub folder structure of “Trunk”, “Branches” and “Tags”. In side that Trunk create a folder for each of the different parts you’ll need, although different parts can be added later.

That concludes this blog. A future blog will include subversion clients amongst other things.

PhotoSketch photoshops for you

PhotoSketch is some nifty software which allows you to creatively edit your photos by adding new parts to them.

As you  all you do is make a quick sketch of your scene, label each bit with some text and, seemingly by magic, you sketch is transformed into a unique photo.

photsketch

It looks like it takes your basic shape and matches them to parts in other photos. I’d imagine the parts have already been labelled inside the photo (maybe by way of GWAP). And then with some real clever pixel matching techniques the parts are embedded in a single photo background. In the above photo you can see the original photos and the sketch on the right with the new automatically created photo on the left.

More information from:

Subversion – source control

A good source control system is a must for almost all programming projects. For instance:

  • You can quickly check which lines across multiple files you’ve changed.
  • Revert changes to any previous date.
  • Never lose any file again.
  • Keep track of why a file was changed, by whom and when.
  • Take snap shots of release code versions.
  • Manage multiple engineers working on the same code base.
  • Automatically combine code from multiple engineers.
  • Split code development into various paths then quickly combine at a later date.

Over the years I’ve used many different source control systems – SourceSafe, CVS, Perforce, CodeSafe –  but the one I’m most impressed with is the only one I use at home and the one I encourage at work: Subversion.

Subversion is an open source, source control system (and they “eat their own dog food” – explained). It’s available on Linux, Windows and Mac and you can freely download it from their website.

If you used CVS before then you’ll probably understand how it works, but if you are more of a SourceSafe person (I feel for you) then Subversion takes a little explanation. Subversion works like this:

  1. First you create a “repository”, this will be where all the files are stored, lets call it “TestProj”, you’ll normally create this on your server so that multiple people can access it.
    1. type: svnadmin create your/path/TestProj
  2. Now locate where you want your own working copy to exist, lets call it “MyTestProj” and “Check Out” TestProj, this simply creates all the files in your repositiory (there isn’t any yet) together with some other files in a folder called “.svn” which holds the admin bits that subversion needs (you’ll see one of them in every subfolder you create).
    1. type: svn file:///your/path/TestProj MyTestProj
  3. Now create some files, say “TestProj.cpp”, “TestProj.h” and “TestProj.ico” in MyTestProj folder. These currently exist only on your computer so you need to “Add” them to Subversion. This just means you “are going to” add them, subversion won’t do anything until you subsequently “Commit” these changes, at that point you’ll get the opportunity to comment on your changes.
    1. type: svn add TestProj.cpp TestProj.h TestProj.ico
    2. type: svn commit --message "Adding first files"
  4. Now all your files are commiteed and the files are added inside the repository you created. Anyone else doing “Check Out” will see them in their working folder.

You can stick any folder or file in your working copy, and make any changes to the files you wish, nothing will happen to the Repository until you commit. You can “Update” you copy at any time to get everyone else’s changes or “Commit” you’re own changes back – by default there is no locking of files – if you change the same file as someone else then Subversion automatically merges them together –

…take a deep breath if you are a SourceSafe user, this will sound like witch craft…

– in almost all cases code can be automatically added as different lines will have been changed (this was hard for me to believe back when I first used it but believe me it’s clever enough to never cause a problem). On the rare cases (although this depends on project size, user number and frequency of updates) you’ll get a “Conflict” which means you’ve changed the same line someone else has and you’ll have to sort this out yourself before you are allowed to commit your changes.

There’s more information at:

That ends the first Subversion blog, in the future ones I’ll be looking at a folder structure you can use to make your projects easier to manage (see here), some of the client apps that exist to make working with subversion easier and more efficient, backups and a few more bits and pieces.

WordPress – my new home

As you can see – assuming you are reading this on my blog – I’ve just moved over from blogger.com to my own space, notice the new web address: “http://blog.akademy.co.uk-tips” .

After having a quick look around I decided to go with WordPress, WordPress.org that is. WordPress.org is where you can download the very popular blogging PHP system and install it to your own website (WordPress.com is the website that hosts blogs for you for free).

I made the decision to switch becuase I wanted a bit more control over my blog and files than blogger could provide, and I wanted to be able to play with the back end too. I decided not to go down the line of creating one myself; usually I’d have put something together just to see how to do it – teaching myself as I went – but in this particular case, I’d have never had the time to make something I would have deemed stable enough for long term use. So WordPress.

All you need to install WordPress on your own website is PHP 4.3 or higher and MySql 4.0 or higher. Run through the installation guide you’ll get when you download all the files – it’s really quick and simple. I had my Blog installed in just about 10 minutes and most of that was uploading time.

Even better, I already had a couple of blogs on blogger.com but wanted to move them over. I thought this was going to be a bit of a nightmare but I was very wrong. I just gave WordPress the address and it downloaded everything automatically. Log in an Administrator and select Tools->Import->Blogger. Magic.

There’s also loads of themes and extensions for WordPress, which gives you a great deal of control over what you show and how you’d like it to be presented. You can really personalise it any way you’d like.

All in all I’ve been very impressed by WordPress. It’s simple to install, easy to extend, and a joy to use, and it’s used by millions everyday.

A few things to take into account if you are thinking of switching to your own host:

  • You’ll have to perform backups yourself: database and website.
  • You’ll have to upgrade the system yourself (although this is pretty striaght forward if you haven’t made any of your own changes.
  • Hosting your own webpages will usually cost a  fee.

If you are looking to host your won blog then WordPress is throughly recommended.

Blackbird javascript debugging with PHP

If you’re still using the javascript “alert()” function to output all of your debug information then take not: You need Blackbird!

Blackbird creates a little window to output all your javascript debugging information. When you need it, you can pop it up with a quick key press and all the output from your javascript programs is there.

You can put different types of information out to the window then filter the display to just show what you need. You have a choice of Information, Debug, Warning, Error or Profile. The first four just output text, but the last takes a label to start a timer, the next call with the same label outputs the time difference.

It’s really simple to install. Just include a little javascript and CSS file like this:

  1. <link type="text/css" rel="stylesheet" href="/PATH/TO/blackbird.css" media="screen">
  2. <script type="text/javascript" src="/PATH/TO/blackbird.js"></script>

Make sure the script tag is above any other javascript you might want to debug.

Now all you have to do is call one of the functions:

  1. // Output text marked as debug:
  2. log.debug( "I'm trying to debug this thing" );
  3. // Output text marked as information:
  4. log.info("Hello World!" );
  5. // Start a timer with label testFunc1
  6. log.profile("testFunc1");
  7. // Stop the timer and output time (You'd usually do something between the two profile calls)
  8. log.profile("testFunc1");

That’s all great and really useful. Most of the time however, you’ll not want to include the Blackbird code, so with a little bit of PHP magic you can choose, on the fly, when to include it. Place this code in your PHP file in the HEAD section of the resulting page:

  1. if( isset( $_GET["debugging"] ) )
  2. {
  3. echo <<<END
  4. <link type="text/css" rel="stylesheet" href="/PATH/TO/blackbird.css" media="screen">
  5. <script type="text/javascript" src="/PATH/TO/blackbird.js"></script>
  6. END;
  7. }
  8. else
  9. {
  10. echo <<<END
  11. <script type="text/javascript"><!-- <![CDATA[
  12. var log={toggle:function(){},move:function(){},resize:function(){},clear:function(){},debug:function(){},info:function(){},warn:function(){},error:function(){},profile:function(){}};// ]]>-->
  13. </script>
  14. END;
  15. }

So the simple idea here is that if you include “debugging” in your URL call then Blackbird code will be included, at all other times the log functions are set to empty so no code will be output. This allows you to leave the actual debug calls in your code, without them causing errors or being display.

Here’s how my page works with this:
With debug (don’t forget to press F2)
http://www.akademy.co.uk/index.php?debugging
And without:
http://www.akademy.co.uk/index.php

The javascript “alert()” function doesn’t even come close!

Check out Blackbird here: http://www.gscottolson.com/blackbirdjs/

Teaching programming to the masses.

Most people believe it’s easiest to learn new things when you are young, however, I believe if you are still able to think then you are still able to learn, but there is one good reason for learning earlier and that’s the time to practice and gain experience.

Starting to learn programming early certainly has it’s benefits, the best ones are almost always the ones who started when they were young, and this leads us to the main part of this blog: Teaching Programmers.

I grew up programming the Sinclair ZX Spectrum, not an experience I’d want anyone else to try, (though it was pretty clever for its time). This was always a rather loney pursuit, and in many cases, still is. However, programming has come a long way since then, object orientated programming was a massive improvement and Garbage Collectors have improved far enough to be pretty fast and reliable.

But has the way we program really changed that much? Well, no not really. All programming comes down to opening up a file and writing symbols in certain orders that only a select few can understand. How does the majority learn what’s going on? Isn’t it a little strange that the world over uses software but a tiny minority actually know how to create it?

Well, I think so, but the good news is that programming is slowly going mainstream, and there’s several really useful and fun pieces of software available to teach it, here’s my top picks.

Alice (http://www.alice.org/) (Personal Favourite!)
With this you first create a 3D world with characters and props through a simple drag and drop interface. You then control what happens through coding. The tutorial is excellent and gets you going immediatey. It won’t be long before you are creating your own little world (See mine here)

Scratch (http://scratch.mit.edu/)
Two-dimensional images can be controlled to make all kinds of interesting games and tools. There’s a large list of examples created by people across the world.

Kudo (http://research.microsoft.com/en-us/projects/kodu/)
This one is especially for creating games and just looks really nice. The programming is just drag and drop.

Karel (http://mormegil.wz.cz/prog/karel/prog_doc.htm)
This isn’t actually a program but a fully fledge programming language. But it’s designed especially for people new to programming.

Project Euler. Problem Solving, Maths and programming

Here’s a fun little website to stretch those little grey cells.
http://projecteuler.net/

Named after the great Mathematician “Leonhard Euler”, it’s a website to test your programming and Maths prowess. Of course I’d only recommend it if you do actually enjoy solving maths puzzles and enjoy programming, otherwise it might be just a little torturous!

Each puzzle has a single number which you can enter on the website as a solution. It will keep a record of all the solutions you’ve found and if you solve enough, your name will be immortalised on the high score board (Though there’s a lot of work to do to get there!). Once you’ve got the right answer you can see how other people worked it out too in various different programming languages. You will certainly learn a few new skills and probably improve your own programming along the way.

I’ll see you there.

Update: It’s also a great way to practice any new programming languages you may be learning. Check out the list of languages people have used.

Exciting software: Photosynth

Already mention in my Exciting software blog, Photosynth is now released to the public.

This has been around for a while now, but is still pretty impressive software. The idea is it can take multiple shots of the same area and stitch them together to create a 3D world. You can then move about in this world, moving in and out of various areas.

You can try the software out for yourself here:
http://photosynth.net/

(A warning though, any photos you upload become public.) They say you can create a impressive shot with as little as 10 photos and they suggest you start small. For a guide on taken photos see this PDF’s but some quick tips to get you started:

  • Overlap the shots alot
  • Take zoomed out shots
  • Shoot the same thing from different angles.

The software works on either XP or Vista across most of the leading browsers. Let me know how you get along and have fun.

Coding fonts

Is it time to change your coding font?

A font created especially for coding sounds like a strange idea, but there are several things you can include in a font that can make coding an easier experience. For instance, most common fonts show the 0 (“zero”) and the O (“oh”) characters in an almost identical way, with a specific font these can be clearly identified.

There are others too, seemingly tiny changes but with big payoffs

  • Telling other charaters apart like “{“, “[” and “(“
  • Highlighting key characters like “{” or “;”
  • Changing the typical space size so more text can be displayed along a line.

Here’s a couple of examples you can download:
http://www.proggyfonts.com/index.php?menu=download
http://damieng.com/blog/2008/05/26/envy-code-r-preview-7-coding-font-released

Then there’s enhanced colours and font styles. Another from the website above is a rather nice colour scheme, very pleasing to the eye, even relaxing in a way:
http://damieng.com/blog/2007/10/14/colour-schemes-for-visual-studio

This is an example of what beauty you can achieve:
Let me know if you have any more examples or know other ways to improve your coding.

The paper and pen operating system : Livescribe


As interfaces go, handwriting and computers have never really got on together. Either the interface to actually write with is totally alien to how you actually write or when you can get some writing to the computer,they are notorious at trying to work out what you’re actually writen.

So, the solution – stick the computer inside a pen and turn paper into the screen. Oh, and why you’re at it, why not record what’s going on around you and associate that with what you’re writing – now no need to miss what is being said in meetings and lectures.

Sounds clever, no? That’s just what I thought but here’s the demo of this clever system: (There’s an advert on before it unfortunately)

There’s more information available at their website here:
http://www.livescribe.com/

It uses an infrared camera (records 70 fps) to record your writing and can store upto 2 GB of data. The website claims it can hold more than 100 hours of audio, which should be plenty even for a week of meetings. It doesn’t explain how the notepad buttons work though, which I find really interesting…

I haven’t yet used one of these in real life but I think in many meetings I’ve been in, not to mention some unfortunately dull lectures, they’d be very useful. They are also relatively cheap, (you can buy more expensive conventional pens than this) and with falling prices of solid state memory and infrared camers (have you notived these are popping up on everything lately) they’ll soon be recording in everyones hand.

Let me know if you get to play with one of these.