"Stories are part of every community. They communicate culture, organize and transmit information. Most importantly, they spark the imagination as you explore new ideas. They can ignite action."
I am looking for all KDE developers who have had to deal with program data requirements to give me their opinion on an issue I have and hopefully we can come up with an inovative way to solve the problem, in true KDE style. If you do not have time to read the full post please skip down to the technical question and add a quick comment.
Let me tell you a story. A college student studying Computer Science decides one day to download the source of his favourite Open Source program and build it from scratch. This college student wants to impress his friends by adding a simple button that shows a dialogue box with his name in it, hence proving his l33t skills.
This "user story" sets up a persona for the protagonist of this blog post, a very low commitment developer that is trying something on a whim. The user story also paints an interesting picuture of the requirements of the user:
- Download the program quickly and easily.
- Make a really small change, quickly and easily.
- Run the program quickly and easily.
So taking a well known KDE program as our test subject, how does this scenario fit with the Marble Desktop Globe code base?
1) Download quickly and easily:
The Marble website has a link on the frontpage to "Compiling Marble". Well placed and on a very nice looking website! My college student is having a good time so far, he downloads the source from the Subversion Repository and thinks to himself "Hey I like IDEs so why don't I just skip the next part of the instuctions and run marble from, say, QtCreator" ... move on to step 2
2) Make a really small change, quickly and easily:
This is a topic for another blog post. I believe that code be structured in such a sensible way that it will pratically guide a new developer to where they need to make their change. More on this some other time ... move to step 3
3) Run the program quickly and easily:
My student is loving his development experience so far. He's enjoyed looking at screen shots on the Marble website while downloading the source, he's found the part of the code he needs to change really quickly and has made his simple change. So what is there left? Just click that big play button in QtCreator and show off your skills to your friends. Wait a few minutes for it to compile and hey presto! I give you marble:
Eh.. Ok What happened here? Our student is confused and a little frustrated but he make at least a tiny bit of effort to see if he can find out the cause of the problem. He finds this message:
At this point the ease of development has completely disappeared for our imaginary student. What he doesn't know is that Marble is expecting its supporting data to be located in a specific place, and if he read the rest of the compilation instructions he would have seen that you have to run make && make install before running marble.
Now our student has a choice:
- Continue diving into the code of something that he doesn't understand to figure out the problem and fix it
- Get involved in the community by contacting someone on IRC or a mailing list (which he has to find) and wait for some help
- Give up.
Which do you think he will choose at this point? Which one of these outcomes do you think the *majority* of the population of mildly interested, not very commited people would do at this stage? What would you do?
I have brought this discussion up on the #kde-devel chanel trying to figure out a nice technical solution to the underlying problem in marble and I got the response from one of our KDE developers:
<*unnamed*>: i'm always concerned if we need those really non commited devels
Now the developer in question may make a very valid point. Why should we spend loads of time and effort on the people who think its too much effort to read the the full "Compiling Marble" page. It is a valid point but I fundamentally disagree.
I believe that our imaginary student should go away from this experience thinking that Marble is an easy project to develop for, and sometime in the future he will remember this fact. It might be days, weeks, months or even years but that developer will come to a time in his life where he has an extra 10 mins a day to work on some open source program and will remember his good experience with Marble. This has a powerful effect in the long run.
The thing that sparked this philosophical rabbit hole for me was a simple technical question: how do you make it so that a developer can just click "run" in QtCreator when working on a CMake based project where the program has data requirements? The current way Marble does it is that it requires the user to run make && make install before running, which to me is not optimal for 3 reasons.
- The uncommitted developer (our student from the user story above) may not read the documentation enough to realise that they need to make install before running.
- The uncommitted developer may not want to scatter files, programs and libraries around their computer without knowing that they will be able to clean their system afterwards.
- The default configuration of make install is that it places the install files in system paths that will most likely be security protected so in fact the user will have to run sudo make install.
Point 2 above is problematic for our uncommited developer because they, most likely, are not committed enough to read the CMake files and understand where the data will go when they do a make install. Point 3 can be avoided by configuring the install path but this is another piece of configuration our student needs to figure out or read somewhere, and frankly I don't even know how to do this.
So what do we do to solve this problem? Marble has a unique way of dealing with its data dependencies, it uses a class called MarbleDirs that is effectively a layer of indirection for the file system. It currently checks 2 places for any of the file names/paths that are requested
- The system install path for the data
- The user's application data folder, so that files can be created without administrator privileges
This system also serves the purpose of locating the "system install path" and the "user application data folder" in whatever OS Marble is installed on.
I have proposed a change to this system http://reviewboard.kde.org/r/6574/ that adds another folder to the "watched folder list". The new folder will be the application directory where the Marble executable is located. This ensures that if the data required by the Marble program is copied to the build directory at configure time (with CMake) the QtCreator IDE will run marble fine right out of the box.
I would ask anyone who writes any program that deals with a data dependency to please let me know what your program is and if you have the time a brief description of how you deal with this issue. If you don't have time just tell me where to find the code and I'll go have a look myself.
I am trying to get a feel for how other people have solved this same problem before I re-invent the wheel. Also if you have any ideas please chip in with a quick comment.