KDevelop4 project file

[Matt Rogers]

On Thu, Jul 20, 2006 at 10:15:20AM -0400, Adam Treat wrote:
> On Thursday 20 July 2006 5:42 am, Andras Mantia wrote:
> > On Thursday 20 July 2006 12:10, Andras Mantia wrote:
> > > Hi,
> > >
> > >  As I read in the commits, the project files are now in INI format.
> > > Is the structure of them described somewhere? I cannot find any
> > > discussion relating to this change, so it kind'a caught me at
> > > surprise and now I really wonder what is the good way to put my stuff
> > > in the project file. Until now it was easy, I put everything under
> > > the "project" node, and extending the "items" nodes with our own
> > > attributes was easy. How should I go on now? Of course, I could use
> > > my own XML file and insert a line in the kdev4 project file pointing
> > > to this XML file, but that is far from being ideal.
> 
> Yes, I've discussed this change many times in many different forums.  I've 
> discussed it on IRC with mattr, hamish and adymo.  The folks who I knew to be 
> working on kdevelop4.  I've discussed this on k-c-d in the course of a patch 
> to kconfig to allow this.  I've discussed this on the commit messages I've 
> made.  Finally, I've written documentation in the actual source files.  But, 
> no, you are right, I didn't discuss it here...  Sorry.
> 
> The project files are now in INI style format, it is true.  This is because we 
> now use the KConfig framework for project settings too.  This has the benefit 
> that we can use KConfigXT and that all settings are saved in the exact same 
> way.  This is how it works:
> 
> When a project is opened any changes to the settings will be reflected in the 
> project file(s).  When a project is not currently opened any changes to the 
> settings will be reflected as normal... in $USER/.kde4/config/kdeveloprc
> 
> This means that we have one configuration dialog for both kdevelop and the 
> project.  When a project is opened it is in project mode.  When a project is 
> not opened it is in regular 'configure kdevelop' mode.  I will be making a 
> change to the top-level menu item to reflect this.  When a project is opened 
> it will read 'configure project' and when a project is not opened it will 
> read 'configure kdevelop'.
> 
> Now, what does a kdevelop plugin developer need to know in order to use all of 
> this?  Just a few things.
> 
> 1.  All settings are saved to the global KConfig object.  Period.  The 
> framework handles the project opening behind the scenes.  Again, when a 
> project is opened the framework initializes the global KConfig object to 
> point to project file(s).  When a project is not currently open the framework 
> initializes the global KConfig object to point to regular config files.
> 
> 2.  You SHOULD NOT access the global KConfig object through KGlobal::config() 
> anymore.  Instead, you should access it through three different methods:
> 
> 	KDevConfig::standard() <-- This is the usual way you will access it.  Only in 
> 	very rare cases will you need to access it from the other two methods.
> 
> 	KDevConfig::localProject() <-- If you are making a setting without KConfigXT
> 	and wish to make sure the setting is NOT saved in the global shareable
> 	project file, then you can use this.
> 
> 	KDevConfig::globalProject <-- You should rarely if ever use this.  It is
> 	operationally the same as standard.  It may be removed.
> 
> 3.  You should be using KConfigXT for your settings dialogs wherever possible.  
> You can find examples of this in the documentview part, the cmake part and in 
> the shell.  We have two new classes that should be used for this:  
> KDevCModule and KDevConfigSkeleton.  They should be used in place of their 
> respective parents.  They enable the possibility of specifying settings that 
> should only be saved in the local project file such as hard coded paths.  
> Again, look at the cmake settings as an example, but the idea is that you 
> implement one virtual method in KDevCModule that points to a data file which 
> lists the settings that can not be shared.  The framework will then take care 
> to place those settings in the local project file, not the global project 
> file.
> 
> The advantages to this are numerous:
> 
> *  Plugin developers don't have to worry about whether settings belong in the 
> project or in the regular config.  Settings are settings.  When a project is 
> opened then settings are given a project scope.  When a project is not opened 
> then settings are given a regular scope.
> 
> *  Users don't have to wonder how to find a particular setting... "Is it in 
> the project config or is it in the regular config"... there is only one place 
> to get/set settings.  The config dialog.
> 
> *  We can finally pass around kdevelop project files and commit them to svn.  
> The global project file should be safe (ie, it won't contain hardcoded paths 
> or environment variables) to commit.
> 
> *  All settings can be configured on an individual project basis.  A project 
> manager could finally define AStyle settings for the whole project, for 
> instance.  And developers who work on more than one project might have AStyle 
> settings for each different project.
> 
> > As I look in the code it seems that now the project file cannot be
> > accessed at all, only via KDevFileManager, to manipulate folders/files.
> > No extra information can be stored in the project file?
> > Maybe I miss something, but this is a step back compared to KDevelop3
> > architecture.
> 
> No, you can no longer access the old projectdom.  That's because we are no 
> longer using it.  It all goes through KConfig now.
> 
> But, OF COURSE, you can access the project file.  It is just done in a 
> different way... through KConfig... actually through KDevConfig ;)
> 

Of course you now realize that all of this needs to go into some API
documentation somewhere, right? (and no, I'm not volunteering) :)
--
Matt