Difference between revisions of "Getting Started/Sources/Subversion"

Revision as of 15:27, 22 September 2013

This is a quick KDE-specific introduction for using Subversion to access files and software in KDE's repositories. For comprehensive coverage of Subversion we recommend reading the book "Version Control with Subversion".

Please see the KDE Git page for more details about git within KDE. Also note that Subversion is currently being dismantled. See this timeline

Getting started

In order to use the KDE Subversion repository, you will need a Subversion client program.

If you only need SVN for checking out the sources (read-only), use the protocol: "svn" at the server: "anonsvn.kde.org".

So for example, instead of what you see throughout this tutorial, your paths would be similar to this: svn://anonsvn.kde.org/home/kde/trunk/KDE/kdevelop

If you would like to commit changes to the repository, you will need an SVN account, which is obtainable here: get an SVN Account.

Installing Subversion: instructions on installing the client are not presented here. Refer to your system installation instructions to find out how you can install Subversion. You will need version 1.1 at least . If you are compiling from sources and want to access the KDE repository by https (and not by svn+ssh), you will need SSL and ZLIB support, so you will need the --with-ssl --with-zlib options.

Alternatively, you can install one of the many graphical clients out there (for example, kdesvn, albeit unofficial). This tutorial is intended for people using the svn program only, referring to tasks accomplished with the usual cvs program.

Getting an account: if you have had a CVS account before, it has been migrated to the new Subversion client.

The KDE repository structure

svn.kde.org/home/kde

That's the address of the KDE Subversion repository.

The SSL certificate md5 fingerprint for the repositories:

F6BF EDE2 D016 D1B2   4F18 742E 2C8F B7EF

The SSL certificate sha1 fingerprint for the repositories:

e1:e6:41:96:3c:eb:ae:78:e2:73:0d:a2:32:2f:6b:21:13:bf:3d:0f

For people using svn+ssh, here's the fingerprint of the server's RSA key:

1e:89:fa:0d:c3:11:a4:81:36:84:b6:f2:6b:f0:5b:ad

The repository is organised in main directories:

1. /branches
2. /tags
3. /trunk

You can explore the repository structure at http://websvn.kde.org/

The top-level directory /trunk

The /trunk top-level subdirectory is where the main development for KDE occurs. What you will find here is what will become the next KDE release and its associated programs. Here you will also find the www module, which contains webpages for KDE's site and related ones.

/trunk is further subdivided into these sub-directories:

• KDE/
  KDE itself, what will become the next public release. It contains the following modules:
  • kdelibs - KDE basic libraries, used by all KDE programs
  • kdebase - KDE base programs, like the KDE Control Center, Kicker (the panel) and Konqueror (the web browser)
  • kdeaccessibility - Accessibility files
  • kdeadmin - KDE Administration applications
  • kdeartwork - Images, themes, sounds and other art files
  • kdebindings - Bindings for languages other than C++
  • kdeedu - KDE Educational applications
  • kdegames - KDE Games
  • kdegraphics - KDE Graphical applications
  • kdemultimedia - KDE Multimedia applications
  • kdenetwork - KDE Networking applications
  • kdepim - KDE Personal Information Management applications
  • kdepimlibs - Libraries used by KDE-PIM applications.
  • kdesdk - KDE Software Development Kit applications
  • kdetoys - KDE toy applications
  • kdeutils - KDE General utilities
  • kdewebdev - KDE Web development applications
• kde-common

Common admin/ directory

• bugs/

Bugzilla files

• developer.kde.org/

The content of developer.kde.org

• extragear/

KDE programs outside the main KDE releases.

• kdereview/

Temporary home for KDE applications that are believed to have reached release-quality. From here, once all major issues are resolved, applications are moved either to /trunk/KDE/ or to /trunk/extragear/

• kdesupport/

Supporting applications and libraries for KDE

• koffice/
  The KDE Office suite, containing the programs:
  • karbon
  • kchart
  • kexi
  • kformula
  • kivio
  • koshell
  • kplato
  • kpresenter
  • krita
  • kspread
  • kword
• konstruct/

Konstruct, the KDE build program

• l10n-kde3/

Translations for the "unstable" modules of KDE 3 (extragear, playground)

• l10n-kde4/

Translations for KDE 4

• playground/

The KDE playground: applications being developed, but not having yet reached release-quality.

• valgrind/

The Valgrind application, which is hosted on the KDE repository, but that is not part of KDE itself. Note that newer versions of Valgrind are developed on their own repository. The KDE Valgrind modules only holds up to Valgrind 2.4.

• www/

Webpages for the KDE site (and related sites). Write access to this directory is restricted.

The top-level directory /tags

This directory contains the official releases of the programs maintained and developed in the KDE repository. Each individual application has a subdirectory here. Inside it, you will find the release numbers.

For instance, the KDE 3.4.0 code can be found under /tags/KDE/3.4.0/.

The top-level directory /branches

This directory contains the branch versions of the applications after a major release.

Most KDE applications adhere to the philosphy that new features (as well as new user-visible strings) are added only to the next release cycle — the one that lives in /trunk/. However, bugfixes are applied to all applications, even after release.

In order to do that, a branch is created at the moment of the release, indicating the state of the files at that time. Bugfixes are then checked in to those files. Those branches are the ones in /branches/.

For instance, the KDE 3.4.x branch can be found under /branches/KDE/3.4/

The subdirectories you will find inside /branches are the application subdirs, like akregator/, amarok/, arts/, k3b/, etc. You will also find a KDE/ subdir, containing the official KDE releases since time immemorial.

One special subdir is found in /branches: work/. This subdir contains the so-called "work branches", that is, branches containing features being worked on, sometimes highly experimental. Multi-application work branches always are checked in to /branches/work/, but single-application branches may be found in each application's subdir. That is a decision left to the developers.

Checking out and updating

Checking out

In order to check out something with Subversion, you use the checkout subcommand.

WARNING: If you checkout trunk/KDE/ or branches/KDE/foo/ you will download complete kde-i18n!

Suppose you wanted to check out only kdeedu from the KDE repository. You would do:

Subversion users currently using ssh access should use protocol svn+ssh while subversion users currently using password access should use protocol https in the following:

svn checkout svn+ssh://svn@svn.kde.org/home/kde/trunk/kdesupport

For checking out kdevelop from extragear you would do:

svn checkout svn+ssh://svn@svn.kde.org/home/kde/trunk/extragear/graphics

If you don't have a KDE developers account, use:

svn checkout svn://anonsvn.kde.org/home/kde/trunk/extragear/graphics

Updating

In order to update, you use the update subcommand.

You change into your checked out copy (for those new to this whole process, the checked out copy should be in your Home folder) and issue a svn update (or, shorter, svn up) command.

Knowing the status of a file

To know which local files you had modified, you have to do

svn status

and look at the files with M (for modified).

Committing to the repository

Committing to the Subversion repository is accomplished with the commit (ci for short) subcommands:

svn commit
# or
svn ci
# or
svn ci filename.cpp

This way, svn will launch the editor specified in $SVN_EDITOR for you to compose the commit message. If you prefer, you can give svn the -m option with your full message:

svn ci -m "Updating protocol to conform to HTTP/1.1"

Ignoring files

Subversion stores ignored files per directory. To edit the ignored files of the directory you are currently in, do

 svn propedit svn:ignore .

that will launch your editor, write there the names of the files you want to ignore, one file per line. Once you are done, do a commit so the ignored list file gets updated on the server.

A lot of files were ignored in CVS with help from global ignore list which is not supported yet by SVN. You can wait for svn 1.3 or you need to add the ignore list to the [miscellany] group in your ~/.subversion/config (all in one line):

global-ignores = *.o *.lo *.la .*.rej *.rej .*~ *~ .#* #*# .DS_Store *.moc
*.moc.cc *.moc.cpp config.log config.status config.cache *.gmo .deps .libs
SunWS_cache *.lo *.la *.rpo *.la.closure *_la_closure.cpp *_la_closure.cc
*_la_closure.cxx *.all_cc.cc *.all_cpp.cpp *.all_C.C *.all_cxx.cxx
*_meta_unload.cc *_meta_unload.h *_meta_unload.cpp *_meta_unload.C
*_meta_unload.cxx index.cache.bz2 .memdump Makefile.rules.in Makefile.calls.in
Makefile.rules Makefile.calls autom4te.cache *.kidl

Working with multiple revisions and branches

Unlike CVS, Subversion doesn't generate a revision number for each file modified. Instead, the full repository is versioned, as a whole. This way, a given revision number represents the state the repository was on a given date. In other words, a revision number is like a timestamp (in fact, the Subversion server uses this fact to search for dates in the repository faster).

So, for instance, when you check out the KDE repository, Subversion will tell you the following:

Updated to revision 403821.

This means that the latest revision available at the time of the operation was 403821. If you make a modification and commit, Subversion will update the server-side revision and will inform you of it. Like CVS, only the committed files will be updated: you will need run cvs up to update the rest of the files.

If you want to retrieve a specific revision of a file, you can use the -r switch. Besides the revision number itself, -r accepts a number of other possibilities:

• The revision number: for example, use -r 403819 to retrieve that version
• BASE: the revision you updated to
• COMMITTED: the revision a file was last modified, before BASE
• PREV: the revision of the previous commit to the file before COMMITTED
• HEAD: the most recent revision available in the server
• { date }: between curly brackets, you can specify a date for searching the closest revisions

The following illustrates the evolution of the keywords:

1. You run svn up to update to the latest available revision. Suppose Subversion tells you it updated to revision 403821. This means that HEAD and BASE are 403821.
2. You modify file README and commit it. Suppose Subversion tells you it committed revision 403822. This means HEAD, BASE and COMMITTED are 403822.
3. You modify the file again and commit it. Now PREV is 403822, but HEAD, BASE and COMMITTED are updated to a new value (suppose it's 403823).
4. Now someone else modifies the repository, and you update your working copy. If Subversion tells you it updated to 403824, this means now HEAD and BASE are moved to 403824 (but PREV and COMMITTED stay the same)
5. If someone modifies the README file now, HEAD is moved. The other keywords stay the same for you, until you update. At this time, we will have HEAD = 403825 (the latest available revision), BASE = 403824 (the revision you last updated to), COMMITTED = 403823 (the revision of the latest change to the file when you last updated) and PREV = 403822 (the revision of the change before COMMITTED)

Those keywords are useful to retrieve logs and diffs for commits to the repository.

If you want to see the difference between your working copy and BASE, you can run:

svn diff

This is a very fast operation, since Subversion keeps a local copy of BASE. It doesn't need a network connection to accomplish this operation.

If you want to see the difference between your local copy and the latest available on the server, you will run:

svn diff -r HEAD

If you want to see what has changed in the repository since you've last updated, you can use:

svn diff -r BASE:HEAD

If you want to see the last change to a file before BASE, you can use:

svn diff -r PREV:BASE
# or
svn diff -r PREV:COMMITTED

That is also valid for the svn log command.

Checking out specific releases

KDE modules are also tagged at each release so that it is possible to get a specific release of KDE. Most KDE modules have a tag name in the format tags/KDE/X.Y.Z (where X, Y and Z represent the exact version). The arts module (only needed for KDE 2 and KDE 3) has a different format of tag name, tags/arts/X.Y.Z. For instance to get kdelibs as it was shipped in KDE 3.5.0, do:

svn co svn://anonsvn.kde.org/home/kde/tags/KDE/3.5.0/kdelibs/

If you then want to update this checkout to KDE 3.5.5, use this command:

svn switch svn://anonsvn.kde.org/home/kde/tags/KDE/3.5.5/kdelibs

 

Tip
If you used a /branch/ or /trunk/ path, then there is no need to switch, just run svn update.

Checking out translations

If you are looking for translations and other localizations, check out the appropriate language from the appropriate module: l10n-kde4 (KDE4) or l10n-kde3 (KDE3).

 

Warning
The l10n module is extremely large. Be sure you have lots of time and disk space on hand before checking out the entire l10n module. Most people only check out specific language subdirectories rather than the entire l10n module.

You are now ready to start building KDE! Visit this page for instructions on building trunk or this page for instruction on compiling the last stable release.

Checkout from behind a proxy

If the tip above didn't help you, and you've realized that the only way to go seems to be with http://anonsvn.kde.org/.. , then you will have to jump through a few hoops to get an svn checkout. Transconnect is a small piece of software that can tunnel all the traffic through your friendly neigbourhood proxy server. Get the transconnect sources from http://transconnect.sourceforge.net/ , compile it, and edit ~/.tconn/tconn.conf to point to your proxy server. Export the LD_PRELOAD variable as per the README from transconnect, and you're set to go.

Checkout behind a Firewall

If you are behind a firewall and port 22 is blocked, you can do the following if https traffic is allowed:

Add the following to your .ssh/config:

  Host sshsvn.kde.org
    Port 443

Use sshsvn.kde.org as hostname, for example try:

  svn ls svn+ssh://yourusername@sshsvn.kde.org/home/kde

Warning: the hostname sshsvn.kde.org will only work in this particular case. Use svn.kde.org if you are not using the above setup.

Also of interest

• Visit http://websvn.kde.org/ to browse the source code online.
• anonsvn.kde.org is made up out of multiple servers spread over the world.