[Guide][Windows][UPDATED 12/31/11] Use SVN to download Synergy & Other ROM Nightlies
Ignore this quoted section if you are reading this guide for the first time. Start at the blue "New SVN Users" line.
List of SVN Checkout Links for ROMs that are developed with SVN:
Do NOT edit the URL in any way. Copy it exactly as it is shown.
Attention All Eternity/Airborne/Synergy SVN Users: As of 11/29, Eternity and Synergy SVN access is restricted. Virus has stated his reasons here and here. Please do not ask him for a username or password, you will not get one.
To quickly check to see if he has lifted the restriction on SVN, all you have to do is to open the trunk links below in your browser. If it shows you a list of files, Virus has enabled it again. If it asks for a password, it's still locked down. It's much easier to check that way than to SVN Update every so often.
ROM Developers, if you'd like your ROM to be featured here for easy reference, please PM me your SVN checkout link.
New SVN Users, start reading from here!
As promised, I'm posting this graphical guide up for those who wish to use SVN in order to obtain nightly builds of ROMs and all other items that utilize SVN for distribution. As always, my guides are meant for the completely clueless, and come with screenshots for help
First of all. Let's start with the big question.
What is SVN, and why do I care?
SVN is actually not an acronym for anything. "SVN" is the command line phrase that triggers a system called "Subversion", but no one wants to type out Subversion every time they want to refer to svn :P. Long story short, it allows for simple distribution of computer software/ROMs/etc with methodical updating that can be rolled back at any time. It may sound intimidating, but I'll be making it quite easy for you to understand, and ultimately, you'll find it quite useful. Don't get intimidated or freaked out. A few days ago, I had never used SVN either, but now it's a piece of cake!
Well, uh, that sounds interesting, but seriously, why do I care?
Well, you should. Let's take our Sense-based ROMs, for instance. They're all roughly 300+ MB (maybe less for the Sense-stripped ROMs).
Doesn't it suck to have to download a new 300+MB zip file each time there's a small fix that you really want to get to?
What if I told you, that using SVN, you only have to download the select files that the ROM devs have updated, which tends to be a fraction of the size, rather than download a full massive zip of the ROM each time? That instead of downloading 300 MB, you'd only have to download 30 to get a bunch of fixes and updates? What if I also told you that you can revert changes which broke your previous setup with ease? Sounds good? Great! Let's get started!
*What is this? An SVN checkout link is the link that your ROM dev or software author will provide you. It tells Tortoise SVN where to get all those yummy files. For the sake of our example, we will be using the Synergy ROM, which is developed using Google Code. Google Code provides automatic SVN links for those who know how to use it. Read on to understand more.
BOLDED Text - These are folder locations. Red Underlined/Bolded Text - These are hyperlinks. Blue Bolded Text - These are bonus tidbits that may or may not appeal to you.
Step 2: Create the proper folder structure
So then, you don't HAVE to do it this way, but this is how I do it, and will keep your organized.
Start by making a folder called Evo 3D, anywhere on your computer. (I keep mine inside my My Documents Folder).
Inside it, create two more folders. Because the ROM we are downloading for our example is Synergy, we will title it synergy-evo3d and the other one Current. You may change the title of the first folder accordingly based on what ROM you're downloading it. It doesn't matter what you call it, as long as you know what it is. In the screenshots of this post, all screenshots show the folder titled synergy-evo3d, so if you're downloading a different ROM, mentally replace that name with the name of your ROM in each screenshot
Step 3: Start Downloading!
Now that we have our folders set up, let's be clear about which folder is for what. The synergy-evo3d folder is meant as your "cooking pot". You will update your ROM and revert your ROM from there, much in the same way you'd add more and more spices and ingredients to your cooking pot.
Once you have updated or reverted the ROM, you then will export that updated content into your Current folder, which will end up being the zip you flash to your phone. If this doesn't make sense right now, fear not. I'll explain when we get to that step and why we do it this way.
So let's start the downloading process, because this will take some time.
Part 1: Download
Right-click on the synergy-evo3d folder.
Click on SVN Checkout. The following dialog will pop up.
Now, we need the link of the repository. The developer of your ROM/software will provide this for you, you simply need to ask, or look below for a list of SVN Checkout links for SVN-based ROMs.
If you are downloading Synergy ROM, we can find it at their Google Code site here. If you are NOT downloading Synergy ROM, please see the top of this post for the most recently updated list of trunk links.
When you're on that page, select ONLY the shown part of the URL:
We don't want the "svn checkout" part or the "synergy-evo3d-read-only" part. Also, we don't want the last "/" in the URL either.
Remember, if you're not downloading Synergy, look at the top of this post for all recently updated SVN trunk links!
Paste the link of your ROM of choice back into our Tortoise SVN window, and press "OK".
Now begins the downloading process. It will download the proper folder structure. Just sit back, and let it do it's thing. It can take anywhere from 5-10 minutes to an hour and a half, depending on your internet connection. If you have a slower connection, don't worry. Bite the bullet once with this, and then you'll see the beauty of SVN.
Once it finishes, we're left with the completed folder! You'll notice there's now a green checkmark on it, signifying that it's our SVN folder and it has been properly synced:
If we open this folder, we see the following:
Congrats! We synced it properly. Now, here's the thing. Each one of those folders you see contain a hidden .svn folder, which Tortoise SVN uses to keep track of the version numbers whatnot. Therefore, if you zipped up all the files you see right now, you'd have a massive ZIP file full of unneeded files, and it might also malfunction/not flash on your device. This is where we use the "Export" command.
Part 2: Export, Zip, and Flash!
So, to ensure we don't copy any of the .svn folders that are unneeded for our ROM zip, we will use the Export command. This is where we will use the Current folder we created earlier.
Start by right-clicking synergy-evo3d, go to Tortoise SVN, and find "Export".
This dialog will pop up, asking you where to export. Navigate to our EVO 3D folder, and then click on our Current folder.
Click OK. It will begin exporting:
Once it is finished, it will create a synergy-evo3d folder inside the Current folder. If you see green checkmarks on any of these items, you're looking in the wrong location. You need to be looking at EVO 3D/Current/synergy-evo3d
Open it up, and voila! There's our ROM package!
BONUS: From this point on, you can customize the ROM before we zip it up. Stuff in the system/app folder you want to remove? Go on, get rid of it now! Or perhaps you want to add in your own Ringtones now? Do it
Once you've made any personal changes you want (or none, if you want to just flash it as is), highlight all of the files, and click "Add to archive".
This window appears. You've probably seen it before if you've ever zipped anything up.
First and foremost, make sure you select the format to be "zip" and not the default "rar".
Then, pick your level of compression. The idea is simple. if you go as simple as "Store", your file will zip up in seconds, but the finishing zip will be large (in my case, roughly 550MB). If you choose to take the "Best" compression level, it will takea few more minutes (depending on your computer) and can be as small as 330 MB. (That's of course approximate, different people may have different sizes depending on what they remove or don't remove).
Finally, name it what you want, and click OK!
When that's all done? Take the zip, put it on your phone's SD card, and flash that thing. Enjoy!
But wait, Liquid, you said we could update without downloading each time!
Yes, I did. That will be the next post, scroll down!
Respect open source development and the benefits that it brings; say no to CyanogenMod.
Part 3: Updating Incrementally
So then, now that we've gone through all that trouble, we've just discovered that Virus, TrevE and Ziggy, being the crazy developers they are, just added 10 or 15 more changes which you saw here. ASDJKHA SLDFKJHS DLKJFHSD KL CURSES!!!!
But this is the fun of SVN Read on.
Go back to your EVO 3D folder. Right click on your synergy-evo3d folder.
Click on it, and it will update ONLY what Virus/TrevE/Ziggy changed. If they removed a file, Tortoise SVN will remove it. If they added a file, Tortoise SVN will add it. And of course, if they edit a file, Tortoise SVN will update that file. When it completes, you'll be told what revision it is at. It may take a few minutes, just be patient
You'll notice it only downloaded about 26 MB, and has placed/overwritten/removed all files accordingly. It also states that I am now properly at Revision # 259.
BONUS: Want to see what was updated and why it was updated? Simply click "Show Log" to get to THIS window:
You'll be able to see all the revisions made since your last update, and you can go farther back in time if you'd like. If you're the kind of guy who presses "Show Details" when installing applications on Windows, play around with this window, you'll find much that is interesting
Once it finishes, press OK. Go back to EVO 3D/Current/synergy-evo3d. Ensure it's not your SVN folder by making sure you see no green checkmarks on any of the folders or files. Once you have made sure of this, delete the synergy-evo3d folder completely.
If your previous ROM zip is still in there, either delete it too or move it somewhere else. This is to make space/room for the fresh Export we are about to do.
Return to our main EVO 3D folder. Right click, and then export to the Current folder, just like we did the first time. Once it finishes, again, zip it up, just like we did the first time. If you forgot this step, or want to make sure you're doing it right, scroll up to "Part 2: Export, Zip, and Flash!" in post #1.
And that's it! A hell of a lot easier than downloading the ROM over and over, eh? Keep reading, the fun isn't over yet.
Part 4: Reverting To Previous Builds
So then. This is the nature of the beast known as the "nightly" build. A revision has gone in and borked your setup. Maybe it's killed off your battery life, maybe it changed something visual you don't like, maybe it removed an app that you preferred to have in the ROM. Your reasons may vary, but it doesn't matter. You can revert to a working version very easily.
Heads up! This can get a bit hairy depending on what you want to do. There's recommended strategies, and then there's things I wouldn't recommend. Read on to learn more.
Alright then, let's begin.
Remember that "Show Log" button we hit earlier when upgrading? We want to go back there now. Right click on your SVN folder, and click on "Show Log".
Then, this window will pop up. It's a catalog of all the changes made. You can control by many different factors. Let's start by finding the timeframe of the revision you want to go back to. Then, from there, you'll notice there's a search box.
So there's two scenarios here.
One, you already know what build number you want to revert to, in which case, scroll down until you find the right revisions.
Two, you're not entirely sure what revision you want, but you remember the changelog comment. For instance, let's say I'm having issues with the kernel. To see all the changelog comments that contain the word "kernel", I type "kernel" into the search box and press Enter:
Or we could go even more detailed.
Let's say you're a Themer, and you're trying to find a certain framework-res.apk that was modified at some point to ensure your theme still works or to redo your theme.
Simple! We just type "framework-res.apk" into the searchbox, and we press enter.
As you can see, it is showing me every single change that modified the file "framework-res.apk".
For the sake of keeping it simple for this guide, I theoretically want to find all changes related to the "overscroll" effect. So I type it in, pick the revision I want, and then I right click it.
This is where you need to stop and think about what you're doing. As you can see, you have two options in the screenshot above. You can revert to that revision, or you can revert changes from that revision. There is a HUGE difference between the two, and there is a list of things you need to remember before you pick which one to do.
Use Revert To Revision (Recommended)
This will revert ALL changes since the revision you clicked on. If you are on Revision 296 and want to revert to Revision 260, ALL revisions between 261 and 296 will be reversed. If something was added, it will be deleted. Modified files will be restored to what they were in 260. Removed files will be readded to where they were as of build 260.
Use this Option ONLY if:
The latest revision has wrecked a key part of your phone, such as the mobile network, the 4G, the battery, MMS, etc etc, and you need said functions working asap.
You want to revert to a revision that you feel simply worked better, and you will stick with that revision until the changelog reflects that your complaints have been addressed.
It's simply a temporary deal while you wait out the process of more fixes being added.
Use Revert Changes From Revision (Not Recommended)
This will revert a SINGLE revision's changes only. For instance, if you are on revision 290, and there was a change in Revision 260 you liked better than the one in 290, it will only take that single change from 260 and "inject" it into your current 290 build. If this sounds too complicated to you, DO NOT DO IT. Read the NOTE at the end of this section to understand why.
Use this Option ONLY if:
You are an advanced developer, and you're interested in figuring out what changes Team Synergy made to what, and how it affects the items around it.
You are a ROM themer, and you need access to previous files to troubleshoot your theme as you upgrade it.
You are an advanced user and you are trying to troubleshoot how one file that Team Synergy changed is affecting your programs/development/mods etc.
Decide which one suits you (most likely the first option), and click Yes when it asks you to confirm. It will finish reverting the changes (it calls this "reverse-merging")
Once it completes, follow the steps to Re-Export, and Flash!
Using SVN Revert is a tricky thing. For now, as far as what I've guided you to know, SVN is only a TEMPORARY solution. And it can also be a problematic one. Why? Because you'll still want to update to a new build, right? No matter which option you chose above, using SVN update will overwrite any revisions Reverts that you have done before. This will get to be a problem if you try to keep reverting back to a version you prefer. The more and more you cherry-pick which changes you want to keep, the more and more unstable you may make the ROM. You might also miss out on new features; say that the ROM's framework-res.apk was updated with some new features as of revision 290, but you're still using the framework-res.apk from build 260. You won't be able to get any of those new features. It gets worse when you get to System files. What if you chose to keep a reverted apk, and in a new build, it gets overwritten? If you keep your old apk, and newer builds have dependencies on that apk, you'll run into errors, because the system will not find the apk it's looking for, it will find your old one.
Essentially, the best place to get ROM fixes is straight from the Devs. Use SVN Revert ONLY as a temporary solution until they fix it!
There's plenty more coming, but I'm tired of this thread again, stay tuned. I'll add some more helpful tips later on
Well guys, that's it for the guide for now. As always, I do my best to make sure you have the easiest and clearest guides to go by, because XDA is about the more knowledgeable spreading their knowledge to the less. Enjoy, and most importantly, spread what you learned here to other people that use SVN. They may not be using SVN for ROMs, but the guide is more or less the same as long as they have their own SVN link.
XDA Developers was founded by developers, for developers. It is now a valuable resource for people who want to make the most of their mobile devices, from customizing the look and feel to adding new functionality. Are you a developer?