KDevelop4 project file

[Adam Treat]

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 ;)

> Andras