Subversion

From WikiROMS

Jump to: navigation, search
Subversion

ROMS source code is distributed using Subversion(SVN). There are SVN clients available for nearly every operating system and a list of popular clients can be found here. If you wish to use Subversion to maintain your own copy of ROMS you will also need an svn server. This page will help you get started with downloading ROMS with Subversion. There is also a way to download ROMS using git, described elsewhere.

Contents

SVN Overview

Subversion is a tool for managing software development that keeps track of who modified what and allows the return to a previous version if changes don't work as expected. All the ROMS/TOMS files are stored in a SVN repository on www.myroms.org with access controlled by requiring authentication with the same ROMS Username/Password combination assigned to registered users of the ROMS Forum.

This SVN repository is the official version of the code which only the developers are allowed to change. Users should download the ROMS code to their local machines using an svn client. Don't attempt to use a regular web browser to browse or download files from the SVN repository - there are much better tools for interacting with the code repository. See the notes below under the heading View the Repository.

We strongly recommend users always check out the current trunk version since this has the most recent updates and bug fixes. The tags version is kept largely as an historical record of stable releases at the conclusion of major code upgrades.

Below is a general description of how subversion works. Please look at the svn book for more detailed information. Brief instructions for using two GUI clients (one for PC and one for Linux) we've tried are included.

Downloading ROMS

WarningWARNING: It is strongly suggested that you checkout the ROMS source code using the same operating system you wish to compile and run ROMS on. If you download the code on a Windows machine and wish to run it on a non-Windows machine you will need convert the line endings with a utility like dos2unix or recode. Even with these utilities you may still have problems compiling ROMS.


In order download source code from a Subversion repository, svn client software must be installed on your local machine. If you are compiling subversion on your own be sure to build it with SSL support or you will not be able to download the ROMS source code. Most Linux distributions come with subversion (the command name is svn), so shell commands may be used without installing additional software. If your username on your local computer is not the same as your ROMS username you will need to pass the --username <username> option to svn; an example is given below. The general form of subversion commands is:

   svn action from to {optional_qualifiers} 

To check-out the files from the ROMS repository trunk (latest version), enter (notice https instead of http):

   svn checkout https://www.myroms.org/svn/src/trunk MyDir 

where MyDir is the destination directory on your local computer. It will be created if not found. If your username on your local computer is not the same as your ROMS username you will need to pass the --username option to svn:

   svn checkout --username joe_roms https://www.myroms.org/svn/src/trunk MyDir

There is an additional repository that provides idealized Test Cases and realistic applications to introduce you to ROMS many capabilities. You may use these examples as a guideline in setting up your own application. Currently, this repository requires ~388MB of disk space. This is because the realistic applications require several input NetCDF files. To checkout this repository, enter:

   svn checkout https://www.myroms.org/svn/src/test MyTest

Similarly, to check-out the files from the ROMS repository matlab (official scripts), enter:

   svn checkout https://www.myroms.org/svn/src/matlab MyDir

To check-out the files from the ROMS repository plot (NCAR's library-based plotting package), enter:

   svn checkout https://www.myroms.org/svn/src/plot MyDir  

To check-out the files from the ROMS repository test (realistic applications examples), enter:

   svn checkout https://www.myroms.org/svn/src/test MyDir 

To check-out the files from the ROMS repository branches, plot, matlab, tags, test, and trunk, (this is not recommended because it takes a long time to complete) enter:

   svn checkout https://www.myroms.org/svn/src MyDir

You only check out once, after that, a hidden directory called .svn exists to keep track of the source, destination and a bunch of other information. Your username and password will also be saved. For more detail on command line use and syntax, see the svn book.

Several GUI front-ends to subversion exist, allowing the user to have visual prompts to help them manage their files.

Updates

Now and again, you might feel the urge to get up to speed with the latest changes that have been made to the ROMS repository. When that happens, simply go to the directory that was "MyDir" above and type:

   svn update

Subversion will remember where you checked out from before and see if a newer revision exists. If so, it will download and apply all the relevant changes.

Code changes

As you use ROMS, you may find yourself adding new files and new chunks of code to existing files. Unless you are a developer with write access to the repository at www.myroms.org, you have no easy way to save your changes within the svn framework, since any one directory can only point to one repository. To keep getting updates from the trunk, you must keep using the svn server at myroms.org. At the very least, saving a tarball before fetching major updates is a prudent step. A more organized approach to revision control for your own files can be achieved by using git.

Conflicts

Sometimes when you make changes to your copy of the ROMS code, those changes will conflict with changes made to the repository (the code that resides at https://www.myroms.org/svn/src/trunk). This means that the changes from the server overlapped with your own, and now you have to manually choose between them.

Whenever a conflict occurs, three things typically occur to assist you in resolving that conflict:

  • Subversion halts during the update, offering you several choices, and remembers that the file is in a state of conflict if you don't clear it right then.
  • If Subversion considers the file to be mergeable, it places conflict markers (special strings of text which delimit the “sides” of the conflict, usually "<" and ">" characters) into the file to visibly demonstrate the overlapping areas.
  • For every conflicted file, Subversion places three extra unversioned (not under Subversion control) files in your working copy:
  • filename.mine: This is your file as it existed in your working copy (local copy) before you updated your working copy. This file has only your latest changes in it. (If Subversion considers the file to be unmergeable, then the .mine file isn't created, since it would be identical to the working file.)
  • filename.rOLDREV: This is the file that was the BASE revision before you updated your working copy. That is, the file that you checked out before you made your latest edits.
  • filename.rNEWREV: This is the file that your Subversion client just received from the server when you updated your working copy. This file corresponds to the HEAD (latest) revision of the repository.

For example, let's say you checked out revision 280 and made some changes to User/Functionals/ana_hmixcoef.h. Now you want to update your ROMS source code to take advantage of a new algorithm but when you run svn update your ana_hmixcoef.h is now in conflict with the new version in the repository.

> svn update
U Version
U ROMS/Modules/mod_mixing.F
U ROMS/Functionals/ana_hmixcoef.h
C User/Functionals/ana_hmixcoef.h
Updated to revision 291.

>

The above is with an older version of svn. The latest, greatest does this:

Conflict discovered in 'ROMS/Utility/inp_par.F'.
Select: (p) postpone, (df) diff-full, (e) edit,
(mc) mine-conflict, (tc) theirs-conflict,
(s) show all options:

Selecting (p) will behave as the old version.

If you get a conflict, you need to do one of three things:

  • Merge the conflicted text “by hand” by examining and editing the conflict markers within the file.
  • Copy one of the temporary files on top of your working file.
  • Run svn revert <filename> to throw away all of your local changes.

Once you've resolved the conflict, you need to let Subversion know by running svn resolved. This removes the three temporary files and Subversion no longer considers the file to be in a state of conflict. More on this below.

Merging Conflicts by Hand

NoteNote: We recommend that you make a backup of the <filename>.mine file before you begin to be certain you don't accidentally lose your modifications.

To merge your changes with those from the latest revision in the repository, open User/Functionals/ana_hmixcoef.h in your favorite editor and look for a string of "<" characters. You should see something like this:

<<<<<<< .mine
#ifndef DISTRIBUTE
IF (Lanafile.and.(tile.eq.0)) THEN
#else
IF (Lanafile) THEN
#endif
=======
#ifdef DISTRIBUTE
IF (Lanafile) THEN
#else
IF (Lanafile.and.(tile.eq.0)) THEN
#endif
>>>>>>> .r291

After comparing the two code blocks (separated by the "=" symbol), you decide that you prefer the logic from the repository so you remove the conflict markers and your code so the section now looks like this:

#ifdef DISTRIBUTE
IF (Lanafile) THEN
#else
IF (Lanafile.and.(tile.eq.0)) THEN
#endif

Now you can save the file and let Subversion know that you have resolved the conflict:

> svn resolved User/Functionals/ana_hmixcoef.h
Resolved conflicted state of 'User/Functionals/ana_hmixcoef.h'

Copying a File Onto Your Working File

NoteNote: We recommend that you make a backup of the <filename>.mine file before you begin to be certain you don't accidentally lose your modifications.

If you get a conflict and decide that you want to throw out your changes, you can merely copy one of the temporary files created by Subversion over the file in your working copy. Let's say you want to use the new revision from the repository:

> cd User/Functionals
> ls ana_hmixcoef.h*
ana_hmixcoef.h ana_hmixcoef.h.mine ana_hmixcoef.h.r280 ana_hmixcoef.h.r291

> cp ana_hmixcoef.h.r291 ana_hmixcoef.h
> svn resolved ana_hmixcoef.h
Resolved conflicted state of 'ana_hmixcoef.h'

Punting: Using svn revert

NoteNote: We recommend that you make a backup of the <filename>.mine file before you begin to be certain you don't accidentally lose your modifications.

If you get a conflict, and upon examination decide that you want to throw out your changes and start your edits again, just revert your changes:

> cd User/Functionals
> svn revert ana_hmixcoef.h
Reverted 'ana_hmixcoef.h'

Note that when you revert a conflicted file, you don't have to run svn resolved.

Using GUI SVN Clients

WarningWARNING: It is strongly suggested that you checkout the ROMS source code using the same operating system you wish to compile and run ROMS on. If you download the code on a Windows machine and wish to run it on a non-Windows machine you will need convert the line endings with a utility like dos2unix or recode. Even with these utilities you may still have problems compiling ROMS.


Most of the GUI svn clients are very similar to each other. In this example we will use eSVN, although several users have reported better luck with the free "Foundation Version" of SmartSVN.

View the Repository

The easiest way to view a repository is to simply look at it with Trac in a web browser. Enter the URL:

https://www.myroms.org/projects/src/browser

You will be prompted for your ROMS username and password. This is also a good way to see individual files in the repository without actually downloading them.

To view the repository with eSVN, Click on the file menu and choose "Browse Repository" and enter repository URL:

Image:esvn_browser.jpg

Click "Browse" and you should be able to look at the branches, tags, and trunk. You can navigate the repository with a web browser as described above, but cannot do any of the version control stuff that follows.

Checkout a Copy of the Trunk

This process brings a copy of the main code from the repository to your computer and places it under svn control. "Local Path" tells eSVN where you would like your copy of the source code to be located.

Image:esvn_checkout.jpg

You should see a bunch of text stream by like:

   svn checkout https://www.myroms.org/svn/src/trunk /home/ocean/src --username ocean 
   --password ****** --non-interactive 
   A /home/ocean/src/ROMS
   A /home/ocean/src/ROMS/License_ROMS.txt
   A /home/ocean/src/ROMS/Tangent
   A /home/ocean/src/ROMS/Tangent/tl_rho_eos.F
   A /home/ocean/src/ROMS/Tangent/tl_uv3dmix.F
   A /home/ocean/src/ROMS/Tangent/tl_def_his.F
   ...
   A /home/ocean/src/Compilers/UNICOS-mk-f90.mk
   A /home/ocean/src/Compilers/CYGWIN-g95.mk
   A /home/ocean/src/Compilers/OSF1-f90.mk
   A /home/ocean/src/Compilers/Darwin-ifort.mk
   A /home/ocean/src/Compilers/AIX-xlf.mk
   A /home/ocean/src/Compilers/SunOS-f95.mk
   A /home/ocean/src/makefile
   Checked out revision 11.
   successfully (0)
Personal tools