KDE SVN

From KDevelop

Update: KDE has switched to SVN. While much of structural and KDevelop setup information is still valid, you will need to adjust some commands for communicating with SVN. See Version Control With Subversion for guidance.

Suppose you'd like to use KDevelop 3 to work on an existing KDE application residing in the KDE SVN repository. If you've looked at the KDE SVN repository, you've probably noticed that some of the directories contain .kdevelop files, but when you attempted to open these files in KDevelop, you discovered the project would not build correctly. This article explains how to solve this problem.

Or perhaps you've developed a new application using KDevelop 3.x. Now you'd like to add your application to the KDE SVN repository. There are some gotchas to doing that. You cannot just simply copy your KDevelop project directory into the KDE SVN module. This article will explain one technique that will work.

[edit] Working with Existing Applications in KDE SVN

Let's say you want to work on an application called ExistingApp. You know that this application resides in the kdenonbeta module in directory existingapp. After you've retrieved the kdenonbeta module from the KDE SVN, you'll have a kdenonbeta directory and a kdenonbeta/existingapp directory. We shall refer to the kdenonbeta directory as the Module Working directory. We shall refer to the existingapp directory as the Project Working directory.

Step 1

Assuming that you haven't already done so, change to a suitable place on your hard drive. and check out the kde-common module from the KDE SVN Repository.

svn co kde-common

See Retrieving the source for more information on retrieving modules from the KDE SVN repository.

Step 2

Assuming that you haven't already done so, check out the desired module (kdenonbeta) from the KDE SVN Repository.

svn co kdenonbeta

This creates the Module Working directory, i.e., kdenonbeta.

kdenonbeta is quite large. You can save some time by only checking out the root directory of kdenonbeta, then manually symlinking the admin subdirectory to kde-common, like this

svn co -l kdenonbeta
cd kdenonbeta
ln -s ../kde-common/admin admin

Check out the application you want to work on.

# (Still in kdenonbeta)
cd ..
svn co kdenonbeta/existingapp

This creates the Project Working directory, i.e., existingapp.

If the application has a User Manual, also check out its documentation.

svn co kdenonbeta/doc -l
svn co kdenonbeta/doc/existingapp

Step 3

In the Module Working directory, create a file called inst-apps. Put a line into this file with the name of the Project Working directory. If you also checked out the User Manual, add the doc directory too.

cd kdenonbeta
echo existingapp >inst-apps
echo doc>>inst-apps

Step 4

In the Module Working directory, execute the following command, which will create a Makefile.am file for ExistingApp.

make -f Makefile.cvs

Step 5

Create a new KDevelop project that is "homed" at the Module Working directory, i.e., kdenonbeta. To do this, start KDevelop. Select Project -> Import Existing Project. In the dialog that appears, specify the Module Working directory for Directory, in other words, use the browse button to navigate to the kdenonbeta directory and click OK. For Project name, enter kdenonbeta. For Project type, select KDE C++ Application (Automake based). Click the OK button to complete the dialog.

Depending upon how your system is configured, you may need to tell KDevelop where the running KDE is installed, a.k.a. the "prefix" when running configure. On my RedHat 9 system, I don't normally need to do this, but on Debian for instance, the following may be required. Go to Project -> Project Options -> Run Options and add the environment variable KDEDIR and set it to /usr/local/kde/ or whereever your KDE is installed. You can also accomplish the same thing by setting the KDEDIR environment variable before starting KDevelop.

In the Automake Manager (it's that tab on the right side of your screen if you've configured KDevelop to use IDEA! mode), select existingapp in the top panel. Then right-click on the target in the bottom panel. Typically, this will be a binary, but it may be a library if ExistingApp is an applet or kpart for instance. Select Make Target Active in the menu that pops up.

You should now be able to build ExistingApp from KDevelop using this new project. You should be able to do a Make clean, followed by a Distclean. Then do Run automake and friends followed by Run Configure. Finally, do Build Active Target. All of these commands are in the Build menu. Execute Program in the Build menu and Start in the Debug menu should also work.

[edit] Porting an Independent KDevelop Project into KDE SVN

Suppose you've created a new application using KDevelop 3. You did this independently of the KDE SVN tree. Now you want to add your application to the KDE SVN repository. You cannot just copy the project directory into the KDE SVN repository. Here's how to do it.

Firstly, a few prerequisites:

You must have write access to the KDE SVN repository. See the " KDE Developer FAQ for how to obtain a KDE SVN account.

You must have developed your application using KDevelop 3.x. This technique might work with KDevelop 2.x, but I haven't tried it. These instructions assume you've built a KDE C++ application.

You've read and followed the KDE Policies.

You've read and implemented everything in the KDE Developer's Checklist.

Let's say you've created an application called MyApp. You've developed this application with KDevelop 3 and have a directory called myspiffyapp. We'll call this directory the KDevelop Project directory. It might contain the following files and directories:

acinclude.m4
aclocal.m4
admin
AUTHORS
autom4te.cache
ChangeLog
config.h.in
configure
configure.files
configure.in
configure.in.in
COPYING
doc
Doxyfile
INSTALL
myapp.develop
myapp.kdevelop.pcs
myapp.kdevses
Makefile.am
Makefile.cvs
Makefile.in
NEWS
po
README
src
stamp-h.in
subdirs
templates
TODO

./admin:
acinclude.m4.in
am_edit
ChangeLog
compile
conf.change.pl
config.guess
config.pl
config.sub
configure.in.bot.end
configure.in.min
cvs-clean.pl
cvs.sh
debianrules
depcomp
detect-autoconf.sh
Doxyfile.am
Doxyfile.global
install-sh
libtool.m4.in
ltmain.sh
Makefile.common
missing
mkinstalldirs
nmcheck
ylwrap

./autom4te.cache:
output.0
requests
traces.0

./doc:
en
Makefile.am
Makefile.in

./doc/en:
index.docbook
Makefile.am
Makefile.in

./po:
Makefile.am
Makefile.in

./src:
myapp.cpp
myapp.desktop
myapp.h
myapp.lsm
Makefile.am
Makefile.in

./templates:
cpp
h

As you can see, KDevelop tends to generate a lot of files. Most of them you will not check into the repository. Notice that the real source for you project resides in the src sub-directory within your KDevelop Project directory (You have the option in KDevelop of giving the src directory a different name if you wish.). Also notice that KDevelop creates an admin directory which is used to Run automake and friends and Run Configure in KDevelop. Here's where the problems begin. You are not allowed to check an admin directory into the KDE SVN repository. Instead, you're expected to use the kde-common/admin directory provided by the KDE team. Also, you are not allowed to check the po directory in either. Finally, KDE requires that application documentation (not programmer API documentation) be placed in the doc subdirectory one level below the module directory, not in individual project directories.

Suppose you want to add your application to the kdenonbeta module. You want to add it as a first-level subdirectory under kdenonbeta, in other words you want it to end up in kdenonbeta/myapp. In the steps that follow, we'll call this the Project Working directory. We'll call the kdenonbeta directory the Module Working directory. If you created application documentation, you will place it into kdenonbeta/doc/myapp directory.

Step 1

In KDevelop, do a Clean Project and do a Distclean. Both commands are in the Build menu.

Step 2

Assuming that you haven't already done so, change to a suitable place on your hard drive and check out the kde-common and kdesdk modules from the KDE SVN Repository.

svn co kde-common
svn co kdesdk

See Retrieving the source for more information on retrieving modules from the KDE SVN repository.

Step 3

Assuming that you haven't already done so, check out the desired module (kdenonbeta) from the KDE SVN Repository.

svn co kdenonbeta

This creates the Module Working directory, i.e., kdenonbeta.

kdenonbeta is quite large. You can save some time by only checking out the root directory of kdenonbeta, then manually symlinking the admin subdirectory to kde-common, like this

svn co -l kdenonbeta
cd kdenonbeta
ln -s ../kde-common/admin admin

Step 4

Create your Project Working directory in the Module Working directory.

(still in kdenonbeta)
mkdir myapp

Step 5

Copy the contents of the src sub-directory of your KDevelop Project directory to the Project Working directory.

cd myapp
cp /myspiffyapp/src/* .

Notice that you are copying the src sub-directory — not the entire KDevelop Project tree.

Step 6

Copy additional files from your KDevelop Project directory to the Project Working directory.

cp /myspiffyapp/README .
cp /myspiffyapp/AUTHORS .
cp /myspiffyapp/COPYING .
cp /myspiffyapp/INSTALL .
cp /myspiffyapp/NEWS .
cp /myspiffyapp/TODO .
cp /myspiffyapp/ChangeLog .

Notice that you are "collapsing" your original project directory structure down to a single directory by doing this. There may be additional files and directories you want to copy, but do not copy the Makefile and configure files or their variants in this step. Also do not copy the admin, po, or doc directories.

Step 7

In the Module Working directory, create a file called inst-apps. Put a line into this file with the name of your Project Working directory.

cd kdenonbeta
echo myapp >inst-apps

Step 8

In the Module Working directory, run the following command, which will create a Makefile.am file for MyApp.

make -f Makefile.cvs

Step 9

Create a new KDevelop project that is "homed" at the Module Working directory, i.e., kdenonbeta. To do this, start KDevelop. Select Project -> Import Existing Project. In the dialog that appears, specify the Module Working directory for Directory, in other words, use the browse button to navigate to the kdenonbeta directory and click OK. For Project name, enter kdenonbeta. For Project type, select KDE C++ Application (Automake based). Click the OK button to complete the dialog.

Depending upon how your system is configured, you may need to tell KDevelop where the running KDE is installed, a.k.a. the "prefix" when running configure. On my RedHat 9 system, I don't normally need to do this, but on Debian for instance, the following may be required. Go to Project -> Project Options -> Run Options and add the environment variable KDEDIR and set it to /usr/local/kde/ or whereever your KDE is installed. You can also accomplish the same thing by setting the KDEDIR environment variable before starting KDevelop.

In the Automake Manager (it's that tab on the right side of your screen if you've configured KDevelop to use IDEAL mode), select myapp in the top panel. Then right-click on your development target in the bottom panel. Typically, this will be a binary, but it may be a library if you're building an applet for instance. Select Make Target Active in the menu that pops up.

You should now be able to build your application from KDevelop using this new project. Test to make sure you didn't leave anything out or make any mistakes. You should do a Make clean, followed by a Distclean. Then do Run automake and friends followed by Run Configure. Finally, do Build Active Target. All of these commands are in the Build menu. Execute Program in the Build menu and Start in the Debug menu should also work.

If all is well, do Make clean and Distclean once more to prepare for adding the files to SVN.

Step 10

In the Project Working directory, create a file called .cvsignore containing the following text:

Makefile
Makefile.in

Step 11

At this point, you should have a Project Working directory that looks like this:

.cvsignore
myapp.cpp
myapp.desktop
myapp.h
myapp.lsm
Makefile
Makefile.am
Makefile.in
configure.in.in
README
AUTHORS
COPYING
INSTALL
NEWS
TODO
ChangeLog

You're ready to add your project to the KDE SVN repository. Change to the Module Working directory and svn add the Project Working directory.

cd kdenonbeta
svn add myapp

(Unlike most SVN commands, this one immediately creates a directory in the repository.)

Change to the Project Working directory and svn add each of the files in there, with the exception of Makefile and Makefile.in.

cd myapp
svn add .cvsignore
svn add myapp.cpp
svn add myapp.desktop
svn add myapp.h
svn add myapp.lsm
svn add Makefile.am
svn add README
svn add AUTHORS
svn add COPYING
svn add INSTALL
svn add NEWS
svn add TODO
svn add ChangeLog

Finally, commit the changes to the KDE SVN repository.

cd kdenonbeta/myapp
svn commit -m 'New application that does wonderful things.'

Step 12

Check that everything was committed correctly by doing a svn up.

cd kdenonbeta/myapp
svn up

("up" is short for "update") If you see filenames with question marks listed, these are files that exist in your Project Working directory, but do not exist in the KDE SVN Repository. If they are source files you forgot to add, svn add them now and svn commit. The general principle is that only source code should be committed to the repository. If they are files generated by automake or configure, do not add them to the repository. Instead, add them to the .cvsignore file and commit that.

Step 13

If you created an application users manual for your program (not programmer API documentation), you will copy it to the doc directory in the Module Working directory and commit from there. For example

cd kdenonbeta/doc
mkdir myapp
cd myapp
cp /myspiffyapp/doc/en/* .
cd ..
svn add myapp
cd myapp
svn add index.docbook
svn add Makefile.am
# Add other source files and image (png) files needed by the documentation.
# Do not add Makefile or Makefile.in.
svn commit -m "User manual for myapp."

Add the doc directory to the inst-apps file.

cd kdenonbeta
echo doc>>inst-apps

In KDevelop, add the doc subproject to your existing project. In the Automake Manager top panel, right-click on the root (kdenonbeta) and choose Add Subproject. In the dialog that appears, enter "doc". You will see a message that the subproject already exists. Click OK. If you Build the entire project, the documentation should also be generated now, including the docs for your application.

That's it! Congratulations, you've made your contribution to the KDE community. Don't forget to announce your new app in the kde-announce mailing list.

Notes:

In the example above, you added your new Project Working directory as a first-level sub-directory under the Module Working directory. In some cases, you may want to add your application down further in the module tree. For example, if you create a new Kicker applet, you should put it under the applets directory in kdenonbeta. If this is the case, there are a couple of additional steps you need to do.

1. The inst-apps file can only contain first-level directory names. For example, the following is not possible:

applets/myapp

Instead you have to just put applets in inst-apps.

2. You need to modify the Makefile.am in the directory that is the parent to your application's Project Working directory. For example, if you put myapp under applets, then you must modify Makefile.am in the applets directory. Use a text editor and find the line that begins with SUBDIRS. Add your Project Working directory to this line. For example

SUBDIRS = kdoomload kcvsapplet kim rappelKiste myapp

You must svn commit this file to the repository as well.

If the Makefile.am contains

SUBDIRS = $(AUTODIRS)

leave it as is.

In KDevelop, when you do Run automake and friends, Configure, Clean Project, Distclean, etc., they will run against the entire applets subtree. You can either live with that or remove the other directories from the Makefile.am. Just be careful not to svn commit this version of Makefile.am to the repository, otherwise you'll be removing those applications from the build system.

[edit] Building a Distribution Tarball

Now let's say you want to build a tarball of your project so that users who do not have access to SVN can build your application. Basically, we need to put back all the configure and make files that we so carefully removed in the procedure above. Here's how to convert the SVN working directories to such a tarball. (You could, of course, do this using your original KDevelop Project directory, but let's assume you don't want to do that.)

We need the cvs2dist script, which is part of the kdesdk module. If you have not already done so, checkout, build and install the kdesdk module.

cd kdenonbeta
cd ..
svn co kdesdk
cd kdesdk
make -f Makefile.cvs
./configure
make
make install

Note: If you have trouble building kdesdk for some reason, don't sweat it. Just substitute kdesdk/scripts/cvs2dist for the cvs2dist command below.

Change to the directory above the Module Working directory and run the cvs2dist utility.

cd kdenonbeta
cd ..
cvs2dist kdenonbeta myapp

This builds two files called myapp.tar.gz and myapp.tar.bz2 in the current directory. The tarball contains a copy of the admin directory, plus configure. If you added documentation for you app to SVN, it also inserts a doc directory in the tarball containing your documentation source files. For more info about cvs2dist type cvs2dist -h.

Optional: You may want to do the steps below and create a new tarball before you distribute to other people.

[edit] Round Trip Back to Independent KDevelop Project

Let's say you want to take the files from the SVN working directories and work on them in KDevelop independently of the SVN tree, in other words, you want to build the same directory and file structure that you originally started with. (We're pretending the original KDevelop Project directory doesn't exist anymore.)

The tarballs you created above are almost ready to do this, with three small changes needed. Untar one of the tarballs to a new location on your hard drive.

cd scratch
tar xvfz myapp.tar.gz
cd myapp

cvs2dist did not include a copy of Makefile.cvs in the tarball. Without this, you cannot do Run automake and friends in KDevelop. Copy this file from any convenient location, such as kdenonbeta to the scratch/myapp directory.

cvs2dist probably included kdenonbeta.kdevelop and friends in the tarball, so delete the following files:

rm kdenonbeta.kdevelop
rm kdenonbeta.kdevelop.pcs
rm kdenonbeta.kdevses

Start KDevelop. Select Project -> Import Existing Project. In the dialog that appears, specify the directory you untarred to for Directory, in other words, use the browse button to navigate to the scratch/myapp directory and click OK. For Project name, enter your application name, i.e., myapp. For Project type, select KDE C++ Application (Automake based). Click the OK button to complete the dialog.

Test to make sure that everything is working correctly. You should be able to do Run automake and friends, Run configure, and Build.

If you will be building a new tarball, be sure to do Clean Project. You can build the new tarball right from KDevelop using the Project Distribution & Publishing option in the Tools menu.